Author Archives: uecide

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]; Continue reading

Debugging chipKIT sketches in MPLAB-X

You have a rather complex sketch. It’s not working right, and you just can’t find out why. If only there were a way to single-step the program and see what it’s actually doing.

Well, there is now, and here’s how.

From version 0.8.6t (beta version) there are now enhanced facilities for linking up with MPLAB-X.

First you will need a decent hardware programmer, such as a PICkit™3, ICD, or the chipKIT™ PGM. Secondly you will need to install MPLAB-X (if you don’t already have it).

Once that’s all set up and running as it should be you are ready to set it up for chipKIT debugging.

The first thing you need to do is tell it what a .ino or .pde file is.  So in MPLAB-X, go to Tools -> Options, then select the Miscellaneous section.  Within there is a Files tab.  You need to add two entries to the File Associations section.

Start by clicking the New… button and entering “ino” as the file extension.  Now in the Associated File Type (MIME) drop-down list select “C++ Data Loader (text/x-c++)”.

Repeat for “pde” with the same MIME type.  Once done, press the “OK” button and you are good to go.

Now for the debugging. 

Load up UECIDE and open the preferences.  Switch to the “Compiler” tab, and turn on the “Compile the sketch in the sketch folder” option.  This will place the build folder inside your sketch folder rather than in your temporary directory. It also won’t delete the build folder when you exit UECIDE. You also want to ensure that “Remove old build folder before each build” is turned off.

Now load your program into UECIDE as per normal, ensure your board etc are all selected right.  Now comes the magic.  For the programmer, select “Pickit 2”.  It doesn’t matter that you’re not using a PICkit 2.  What this does is change the linker script that is used by the compiler to the “-nobootloader” version.  The sketch can then be run stand-alone without the need for the bootloader (in fact parts of it replace the bootloader completely, so you will want to replace the bootloader once you have finished debugging – I’d go grab the hex file for it now if I were you).

Hit the build button in UECIDE (not the program button, just the build button), and it should generate you, amongst other things, a .elf file within the build folder in your sketch.

Now back to MPLAB-X.  Create a new project in there, and select “Microchip Embedded” and “Prebuild (Hex, Loadable Image) Project”.  For the Prebuilt FIlename, browse to the .elf file that has just been generated.  Select the right chip in the Device drop-down, and your programmer in the list of programmers.  Hit finish, and it should load your program into MPLAB-X.

You can now use all the debugging tools in MPLAB-X to find out what has gone wrong with your program.

Any changes you want to make, just switch back to UECIDE, make the changes, hit compile, and MPLAB-X should see that new version of the .elf file automatically.


If MPLAB-X says the programmer can’t communicate with the board, or it’s not in debugging mode, etc, then it could be that the settings in the linker script for the chip on your board don’t exactly match the layout of your board. Unfortunately the linker scripts are set up by chip, not by board, and some boards which use the same chips have different layouts, especially as to which programming pins they use.  If that is the case, then you may want to create a new blank project in MPLAB-X for your chip type and use the Configuration editor (Window->PIC Memory Views->Configuration Bits) to create a configuration that is correct for your board.  Copy the HEX values for the configuration into the “config0” – “config3” settings in the -nobootloader.ld file for your chip (located in %UECIDE%/cores/chipKIT/api).

Creating a portable UECIDE bundle

Since the very beginnings of UECIDE there has been a little known feature that allows you to create your own portable bundle of UECIDE.  That is, your own copy of UECIDE that you can place on a USB memory stick, network drive, SD card – wherever you like – and wherever or however you access it you get all the same boards, cores, compilers, etc.

The most common platform for wanting to do this on is, of course, Windows, so we’ll detail doing it on that platform, but the principle is the same for all others.

Ok, so what do you need to get started with making your own portable bundle?  First, you need to download the latest version of UECIDE.  You need to ensure you get the “full” version, so it includes the Java Runtime Environment (JRE), and get it as a ZIP file, not an installer.

Step two is to just extract the ZIP as normal, (maybe onto your desktop?), and run UECIDE.  Once UECIDE is up and running, install your boards, compilers, cores, etc as per normal.  Make sure everything works.

Now comes the magic…

Close UECIDE – you won’t need it for a few moments.

All the things you have downloaded will have been placed into your own user’s “uecide” folder.  Assuming your username is “Bob”, (Hi, Bob…) that will be located in C:\Users\Bob\AppData\Roaming\uecide.  Open that location in an explorer window – you’ll see a preferences.txt file, and folders named “boards”, “cache”, “cores”, “compilers” and “plugins”.  You’re interested in, of course, the “boards”, “cache” and “cores” folders.

In a second window, open up the location you extracted your UECIDE ZIP file to.  One of the folders in there is called “hardware”.  Open that folder.  It should be completely empty.

Drag-and-drop the boards, cores and compilers folders out of your uecide folder and into the empty hardware folder.  It may take a moment or two to move all the files – compilers often have huge numbers of small files in them.

One that’s finished you are as good as done.  If you downloaded any plugins, such as the Grapher plugin, you will want to get those into the bundle too.  They go in a slightly different location.  Where you extracted the UECIDE ZIP, alongside the hardware folder you found earlier, there should be a “plugins” folder.  That should have some plugins (.jar files) in there already.  The plugins folder in your user’s uecide folder should also contain .jar files.  Just drag them from one to the other, as you did with the boards etc.

And that’s about it.

Fire up UECIDE again and make sure everything is still there and working right.  You can drag the whole extracted UECIDE zip folder onto wherever you want to keep it, and run it direct from there.  Try it out.  Plonk it onto a USB memory stick, plug it into your friend’s computer, and you should be able to run UECIDE direct from it, including all your boards and other downloads being there already.

Linking binary files

Have you ever had the need to add a binary file to your sketch?  You know, you are working on a project with a TFT screen, and you have a couple of nice icons you’d like to import into the sketch to then display them on the screen, or you’ve got some hardware attached for generating audio, and you’d like to embed a couple of small WAV files into your sketch.  It’s not the easiest thing to do, normally, is it?  It typically involves converting the binary file into source code, usually an array, and adding it into your sketch that way.  A bit clumsy really.

Well, with the release of the latest version of UECIDE (0.8.3b), there is a better way (compiler permitting):

You can now create a special folder inside your sketch called “objects”.  Any files placed in this folder will be gathered together at compile time, and converted (usually with objcopy) into object (.o) files.  These files are then linked with your sketch, and you get full access to the data in them.

No more messing with programs to convert the file into source code.

So how does it work?

Well, at this moment in time it’s only supported for PIC32 targets, but it will be rolled out to the other major compilers as soon as we are able, but the standard toolchain command “objcopy” has the ability to convert just about anything into an object file.  When it creates the object file it adds a couple of standard symbols into it as well, so you can access the data.  These symbols give you the start address of the data, the end address of the data, and the size of the data.  Each one is unique and is derived from the source file the object file is created from.

So let’s say you have a file “icon.565”, which is an icon file you have converted into 16-bit “565” format common to most TFT screens.  Placing that in the “objects” folder and compiling your sketch will create “icon.565.o” in the build folder, which is then linked to the sketch.  Now, unfortunately it’s not just a case of defining an “extern” to the symbols you want to use.  Instead you have to use a little tiny bit of assembly to reference the symbols.  Don’t worry, it’s pretty straight forward:

extern uint16_t icon[] asm(“_binary_objects_icon_565_start”);

You can then access the array “icon[]” and get at all your data.

The format of the symbols is: _binary_(munged filename)_start, _binary_(munged filename)_end and _binary_(munged filename)_size.  The munged filename is the path of the file you added, including the “objects” folder, with any slashes and dots replaced with underscores.  Thus, icon.565 becomes _binary_objects_icon_565_start etc.

Version 0.8.3a brings options and manuals!

optionsWith the release of version 0.8.3a we now have a facility for providing board-level compilation options.  These are options which can be defined at either the board, core or compiler level (or any combination of the three) and allow the enabling and disabling of various compiler flags.

That could be as simple as turning on/off compiler warnings, or as complex as changing the entire way the core compiles.

It’s great for such things as optionally enabling USB support for a board, or dynamically compiling for different clock speeds, etc.  Anywhere where you have multiple versions of the same board which differ from just a few compiler options (such as -D macros) you can now combine the boards into a single board and use options to configure it as you like when you like.

The option system is detailed in the wiki at

Another great addition is the ability to include a manual PDF file in with a board.  The board directive “manual=…” can point to a file (typically PDF, but doesn’t need to be) stored within the board definition folder somewhere, which is then linked to by an entry in the Help menu: “Manual for <board name>”.  I was basically fed up of googling the manual for a specific board every time I wanted to check a pin arrangement, etc, so I thought this would be a much better way to have the manuals at my fingertips without needing to download them every time or try and remember where I saved them before.

The menu entry changes as you select a different board, and if there is no manual for that board in the definition then the manual menu entry will be hidden.

Two new officially supported boards

Two new boards are now officially supported.  Thanks to the generosity of the guys at Microchip we now have a MAX32 and a WF32 board for testing and compatibility checking.


The WF32 board is a rather interesting one.  It’s a pretty well packed board.  The most prominent feature of course is the MRF24WG0MA 802.11g WiFi module.  Will full support for all the common authentication technologies (WPA2, etc) it’s a pretty nice module.

More subtle, though, is the triple USB connections.  Not only is there the traditional FT232 USB UART connection for programming, but the on-chip USB peripheral is also provided with a choice of both host (USB A) and device (Micro USB) connectors to choose from.

And top that off with a micro SD card slot as well and you’ve got yourself a fully featured WiFi connected system.

Getting everything to work right though was a bit tricky.  Some changes to the way UECIDE works were needed for the Digilent WiFi libraries to compile properly.  It turns out that they rely on different libraries being included in a specific order for some files to override others.  A neat trick, if a bit fragile…  Still, a few tweaks to the core of UECIDE’s compilation system and it works nicely.

My only gripe really with this board is that the SD card is connected to some plain GPIO pins rather than one of the 4 SPI peripherals available on the chip.  This means you can only use software SPI to communicate with it, which means things like RetroBSD won’t work on it without adding another SD card slot.

chipKIT-Max32-obl-500The MAX32 board is the chipKIT equivalent to the Arduino Mega, or I suppose more closely now matched by the Due.  IT has the same chip as the WF32 board, but lacks any of the bells and whistles that the WF32 has.  Instead it just has lots and lots and lots of IO pins in almost the same arrangement as the Mega and Due boards.  It has the same FT232 interface as the WF32 and Uno32 boards, and the same auto-switching power circuitry of the Uno32 (something the WF32 lacks – it’s a purely manual power source selection on that board), so it’s essentially an Uno32 with more pins, more flash, and more RAM.  It also has the more advanced peripherals available, such as an Ethernet controller (which is required for the chipKIT Ethernet shield) and a USB On-The-Go peripheral, but there are no connectors linked to it like the WF32 has.

It’s still a decent board though, and adding an SD card (maybe the one on the Ethernet shield, for example) allows it to run RetroBSD.

Both these boards are now fully supported by UECIDE, and you even get an extra bonus thrown into the mix:  Where MPIDE just gives you the default FT232 connection for serial, UECIDE also has the option to enable the USB peripheral as a CDC device as well, in the same way as the Fubarino boards.  Yes, MPIDE can be bent to give you USB serial if you know how, or you could fight with the Digilent USB device libraries, but why bother when it’s already all there for you?

Version 0.8.2a released

A new version of UECIDE – version 0.8.2a – is now available for download.

The major change in this update is the addition of what I am calling “SAR” files. These are “Sketch ARchives”, which are basically a JAR file (which itself is just a special ZIP file) which contains information about a sketch, the sketch folder itself, and any contributed libraries the sketch uses.

You can now export your sketch as a SAR file, email it to someone, post it on a forum, whatever, and someone else can then import that SAR file, and it should just compile straight off for them. No hunting around for the right libraries, etc – just one file with it all in.

You can also use it for archiving sketches. Because it bundles all the required libraries in with the sketch you won’t have the problem of hunting the internet for the right libraries when you dust off that old project you started two years ago.

And because it’s basically a ZIP file you can even unzip it manually to get at the data in it, so you’re not really restricted to using it with UECIDE. It’s just easier if you do.