Store docs in the microcontroller’s flash

When starting out as an engineer, building electronic circuits of many kinds, my mentor advised me to always leave a copy of the schematics within the box. This is a wise proposition, the schematics in the box will probably be up to date and readily available. On the other hand, external documentation may be displaced and even lost during a period of time. This is equivalent to program documentation: Comments within the source file are easier to keep up to date than some external documentation, like flow sheets.

Now I use a board with a micro controller which  flash memory is much larger than what I need for the application. So why not use that spare flash to embed  some docs?

What kind of documentation would I like to store in the controller? Perhaps the information needed to compile the sources, like compiler switches, source version etc, or even the complete source and makefile. The schematics if  small enough to fit, perhaps a hook up drawing and a terse user manual.

The bash script listed below combines the micro controller program program.hex and a tar archive in a to_flash.hex file which can be programmed into the flash of the controller. The script can also do the reverse operation of reading a from_flash.hex file and extract the tar archive.

The two hex-files is in this case Intel hex formatted, a format often used by micro controller programmers. But objcopy allows for other formats too. The compressed tar archive is  password protected in case I don’t want a competitor to gain insight.

The script name is construct. Give it executable permissions and link  deconstruct to it

(ln -s construct deconstruct). In that way the script may be invoked either as construct or deconstruct.

I have not tested this script with any version of Windows.

#!/bin/sh
# The program may be invoked either as construct or
# deconstruct, no optinos.  

# construct: Combine micro controller program code and documentation
# files to an image to be flashed into the controller.

# deconstruct: extract the documentation from a microcontroller flash
# image

# License: GPLv3 

# Copyright 2010 Odd Arild Olsen
# email:echo oa*oa:|sed s/*/o@/|sed  s/:/o.no/ 

PROGFILE=program.hex    # the microcontroller program name
SRCDIR=.		# where the files to tar live
TAR=docs.tar            # the tar archive we will produce
TARFILES="$SRCDIR/*.c $SRCDIR/*.h $SRCDIR/Makefile" # what to tar
MARK=HERE_I_AM		# A unique string
PASSWD=MyJollyPassword  

name=${0##*/}		#isolate invocation name

if [ $name = construct ]
then
	#collect all files in the tar file
    tar cf $TAR $TARFILES
	#compress and encrypt the file
    zip --encrypt -P $PASSWD $TAR.zip $TAR
	#make a binary file from program, mark and zipped tar
    objcopy -I ihex -O binary $PROGFILE to_flash.bin
    echo $MARK >> to_flash.bin
    cat $TAR.zip >> to_flash.bin
	# convert to a intel hex file
    objcopy -I binary -O ihex to_flash.bin to_flash.hex
fi

if [ $name = deconstruct ]
then
	#convert from intel hex to binary
    objcopy -I ihex -O binary from_flash.hex from_flash.bin
	#find the mark position in the file
    mark=` grep -o -b -a $MARK from_flash.bin|head -n1|cut -f1 -d':'`
	#add the length of the mark
    start=$(( $mark + ${#MARK} + 1 ))
	#copy from end of mark to end of file
    dd ibs=$start skip=1 if=from_flash.bin of=from_flash.zip
	# decrypt and uncompress
    unzip -b -p -P $PASSWD from_flash.zip >from_flash.tar
fi