Serial Number In Intel Hex - Bash Edition

When creating USB devices having an unique serial number for each is quite important. Yes, stuff will work with duplicate (or missing) serial number but you might notice Windows will get confused. With the serial devices the most noticeable effect will be a different port assignment on each plug. Not a breaking deal but a bit annoying.

The easiest way to deal with this is having a dummy serial number in code and then using post-build action to change it in the final Intel hex file. For TmpUsb project I even created a script to do exactly this. However, that script was written in PowerShell which until recently (March 2020) didn’t work on Linux and it definitely doesn’t come installed there by default. This and a few other reasons were why I decided to rewrite this in Bash for my CyberCard project.

The first step is setting up the serial number. The most crucial step here is __at macro that will ensure serial number is always at a predictable location. For my example, I selected location close to the end of addressable space (0x1F00). One could use special characters here but I would highly advise to have a valid USB serial number just in case script fails. That means at least 12 alphanumeric characters but I always go for numbers-only as it makes script a bit easier.

//Serial string descriptor
const struct{uint8_t bLength;uint8_t bDscType;uint16_t string[13];}sd003 ^^__at(0x1F00)^^={
    sizeof(sd003),USB_DESCRIPTOR_STRING, {
        '1','9','7','9','0','1','2','8','1','8','1','5','0'
    }};

The final Intel hex file location will end up multiplied by 2 and thus at offset 0x3E00 further shifted by 4 hexadecimal characters. Script then needs to replace every 4th hexadecimal byte up to the count of 13 in my case (as my serial number is 13 digits long).

The only task remaining is calling it once project is done building. Previously I would do this using project properties dialog (Project Properties, Conf, Building, Execute this line after build) but that proved to be an issue if you want to compile on both Windows and Linux. While Linux setup was quite straightforward, on Windows it would get confused if you have any Linux-based toolset installed (e.g. Git Bash) and throw an error:

"User defined post-build step: [update-serial.sh]"
nbproject/Makefile-default.mk:105: recipe for target '.build-conf' failed
make[1]: Leaving directory 'Q:/Projects/Electronics/CyberCard/Firmware/Source'
nbproject/Makefile-impl.mk:39: recipe for target '.build-impl' failed
process_begin: CreateProcess(NULL, bash Q:\Projects\Electronics\CyberCard\Firmware\Source\update-serial.sh, ...) failed.
make (e=2): The system cannot find the file specified.

One workaround was to simply wrap call to this script in .cmd (or .bat) file but that would cause issues when compiling under Linux. Only if there was a way to execute one command for Windows and another one when running on Linux… Cue the Makefile.

While you cannot differentiate OS from GUI, you can go and edit MPLAB project Makefile directly. There we can point toward .cmd on Windows and toward .sh when running on Linux.

.build-post: .build-impl
# Add your post 'build' code here...
ifeq ($(OS),Windows_NT)
        update-serial.cmd
else
        ./update-serial.sh
endif

All that is left is actually placing the script(s) in the same directory the Makefile is situated (download here) and you’re good assuming you defined serial number as I did. If you didn’t, just adjust LOCATIONS variable inside.

PS: This assumes you have Git (or some other bash-capable environment) installed in Windows.

PPS: Don’t forget to use <Tab> in Makefile for indentation. Spaces won’t do here.