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
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.
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.
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:
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.