Adding Menu Options to A Sketch

Did you know that you can add UECIDE menu items to your sketch? Not sure what I mean? Ok. Here goes.

Imagine you have one sketch that you want to use in multiple different ways. Maybe you have both “master” and “slave” code within the same sketch and want to select between them. Or maybe you want to be able to set a different communication speed, or a different buffer size, depending on how you are using the sketch at that moment. The traditional way of dealing with that sort of thing is to use #define and #ifdef, etc:

#define BUFSZ 1024

int16_t bufferA[BUFSZ];
int16_t bufferB[BUFSZ];

Change the default buffer size for both buffers by changing BUFSZ. Fine. No problem there. It’s easy enough to change the value. But it could be nicer, really. How would it be if, instead, you got to choose different pre-defined values for BUFSZ from a menu within UECIDE? Well, you can.

Have you ever noticed the “Options” menu entry in the “Hardware” menu? There’s usually things like optimization, USB control, etc in there. Well, did you know that none of that is hard coded in the IDE? All of it comes from settings in configurations files. They can be added and removed at will by compilers, cores, boards, etc. They can even be added and removed by sketches!

Yes, by sketches!

There’s a little-known feature in UECIDE called the “sketch.cfg” file. This is a file which sits in the root of your sketch folder and tells UECIDE all about the sketch. It can hold things like which board to use for this sketch, which core, etc. It can also contain almost any other UECIDE settings you choose to add.

The file is normally created when you go to the “Sketch -> Sketch Properties…” menu where you get to set such things as the default board, the author’s details, and such like.

So let me now show you, through example, how to do magic things with it.

Step 1: Create the file

The simplest way of creating the file is to use the “Sketch -> Sketch Properties…” menu. First you have to make sure that the sketch has been saved somewhere, and isn’t just an “Untitled” sketch – otherwise things get a little confused. So do that now.

Then open the Sketch Properties window. Unless you have done this before all the boxes will be blank. You can fill them in if you fancy, but you don’t need to. As soon as you click “OK” a blank “sketch.cfg” file will be created in your sketch folder.

Back in the main IDE window click the “Refresh” icon at the top of the project tree in the “Project” tab on the left. Then switch to the “Files” tab. You should now see the “sketch.cfg” file in there. You can double-click it to open it in the editor. If you entered anything in the previous window you should now see it in the editor as a list of “key = value” pairs. If you didn’t the file will be blank.

Step 2: Fill the file.

So now you get to add things at will. Everything in the file is a “key = value” pair, and of course many keys have special meanings. One group of keys start with the word “options”. These are parsed and placed in the Options menu in Hardware.

Let’s create a new Options menu for our BUFSZ macro then shall we? It really doesn’t matter what you call it, so we’ll call it “bufsz” to save confusion.

options.bufsz.name=Buffer Size

The moment you save the file you should see the “Buffer Size” menu appear under Options. It will be empty for now. So let’s add some options to it.

options.bufsz.default=0128
options.bufsz.0128.name=128 Bytes
options.bufsz.0256.name=256 Bytes
options.bufsz.0512.name=512 Bytes
options.bufsz.1024.name=1024 Bytes

You notice I have prefixed the smaller numbers with 0. This is because the options are ordered alphabetically by their key – that is, the bit that goes between “bufsz.” and “.name”. One vital entry that you must have is a “default” entry. Without this (at the moment) the whole thing goes belly up (it’s a bug I am looking at right now). If you find that your Options menu has suddenly broken you will just need to re-load your sketch.

So now we have options in the menu. But how do you link those to your BUFSZ macro? Well, that’s quite simple. You just set some “flags” for each option. These flags are added to the command line at compile time, so you can add anything you like. The best though is to use “-D” to define a macro:

options.bufsz.0128.flags=-DBUFSZ=128
options.bufsz.0256.flags=-DBUFSZ=256
options.bufsz.0512.flags=-DBUFSZ=512
options.bufsz.1024.flags=-DBUFSZ=1024

You can now get rid of your “#define BUFSZ 1024” from the sketch and the value selected in the menu will be used.

Genius, eh?

To keep your sketch portable though you might like to hard-code in a default:

#ifndef BUFSZ
#define BUFSZ 1024
#endif

In other words – if there is no BUFSZ provided by the IDE or command line then use 1024 as the default.

There are a couple of other options you can use as well. The most useful is:

options.bufsz.purge=true

This option will force the whole sketch, the core, and any libraries, to be recompiled from scratch when an option changes. Great for if your flags are used to affect the compilation of a library that would need to be recompiled after an option change.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: