[Customization HowTo]

Preparation

In order to make use of a custom configuration directory, you will need to be able to compile the source development package uracoli-devel-<version>.zip.

Beside a working AVR toolchain, a installed version of SCons and Python is needed.

In the next step, download the latest development package from http://www.uracoli.de/download.html and unpack it in a working directory. Alternatively you can als checkout the source tree from the repository.

cvs -z3 \
  -d:pserver:anonymous@cvs.savannah.nongnu.org:/sources/uracoli \
  co -duracoli-devel uracoli

To verify, if your build environment is installed correctly, change to the development directory (uracoli-devel or uracoli-devel-<version>) and run the command scons rdk230. This will build the libraries and binaries for the RCB230. In case of any errors, try to fix them before proceeding with the next steps.

Setup the Custom Configuration Directory

The final structure of your working directory with the custom configuration directory and development directory could look like this:

work
|-- uracoli-devel     <1>
|   |-- build
|   |-- Contrib
|   |-- CVS
|   |-- Doc
|   |-- install
|   |-- Src
|   |-- Templates
|   `-- Tools
`-- customboard        <2>
    |-- boards.cfg     <3>
    `-- boards
        `-- myboard.h  <3>

development directory
custom configuration directory
The creation of these files is explained below.

The custom configuration directory holds your local board.cfg file and optionally a directory boards, where the customized board header files are located.

Create boards.cfg

The file customboard/boards.cfg contains the configuration sections of the boards that you will need. Simply copy the interesting configurations from the file uracoli-devel/Src/Lib/Inc/boards/board.cfg.

An example boards.cfg with a RZUSB stick and a ZigBit A2 module is given here.

#
# Custom Board Configuration
#

[rzusb]
comment    = Atmel Raven USB Stick with AT86RF230 Rev. B
image      = rzusbstick.jpg
include    = boards/board_rzusb.h
cpu        = at90usb1287
bootoffset = 0x1e000
ccflags    =
f_cpu      = 8000000UL
no_app     = albo
no_xmpl    = xmpl_keys xmpl_key_events


[zgbt1281a2uart1]
comment    = Meshnetics Zigbit A2, using UART1
image      = zigbit.jpg
include    = boards/board_zgbta2.h
cpu        = atmega1281
bootoffset = 0x1e000
ccflags    =
f_cpu      = 8000000UL
no_app     =
no_xmpl    = xmpl_leds xmpl_keys xmpl_key_events

To check the correctness of this file, use the command scons -h boards=../customboard/boards.cfg. In difference to a plain scons -h in the development directory, only the selected two boards should be listed in the help message.

work/uracoli-devel$scons -h boards=../customboard/boards.cfg

Running with optimization --max-drift=1,--implicit-deps-unchanged, MD5-timestamp and selective rules
scons: done reading SConscript files.

Build System for uracoli project

Usage:

---8<---[SNIP]---8<---

The follwing <BoardType>s are defined in ../customboard/boards.cfg:

    rzusb:
      Atmel Raven USB Stick with AT86RF230 Rev. B
    zgbt1281a2uart1:
      Meshnetics Zigbit A2, using UART1

The libraries and binaries for those two boards can be build with the command scons boards=../customboard/boards.cfg all. This should altough work without any errors.

Creating and using myboard.h

In order to modify the ZigBit configuration, the file uracoli-devel/Src/Lib/Inc/boards/board_zgbta2.h is copied to customboard/boards/myboard.h

Now we modify the section zgbt1281a2uart1 as follows (the original lines are commented out).

#[zgbt1281a2uart1]
[myboard]
#comment    = Meshnetics Zigbit A2, using UART1
comment    = My approach to a ZigBit breakboard.
image      = zigbit.jpg
#include    = boards/board_zgbta2.h
include    = boards/myboard.h
cpu        = atmega1281
bootoffset = 0x1e000
ccflags    =
f_cpu      = 8000000UL
no_app     =
no_xmpl    = xmpl_leds xmpl_keys xmpl_key_events

The command scons -h boards=../customboard/boards.cfg will show now "myboard" in the list of boards, but the initial compile run with the command scons boards=../customboard/boards.cfg myboard will fail with an error.

...
...
In file included from install/inc/board_cfg.h:16,
                 from Src/Lib/Inc/board.h:54,
                 from Src/Lib/Inc/transceiver.h:44,
                 from Src/Lib/Rf230/radio_rfa.c:42:
install/inc/boards/myboard.h:183:4: error: #error "Don't know which UART to use."
scons: *** [build/myboard/lib/Rf230/radio_rfa.o] Error 1
scons: building terminated because of errors.

The following patch will cure the error and the above command will succeed:

--- ../uracoli/install/inc/boards/board_zgbta2.h        2011-02-23 21:32:50.612399000 +0100
+++ ../customboard/boards/myboard.h     2011-04-29 22:14:18.787599009 +0200
@@ -152,6 +152,11 @@
 # define BOARD_NAME "zgbt1281a2nouart"
 # define RADIO_TYPE (RADIO_AT86RF230)
 #endif
+#if defined(myboard)
+# define BOARD_TYPE BOARD_MYBOARD
+# define BOARD_NAME "myboard_zgbt1281a2uart1"
+# define RADIO_TYPE (RADIO_AT86RF230)
+#endif

 #ifndef BOARD_ZGBTA2_H
 #define BOARD_ZGBTA2_H
@@ -175,7 +180,7 @@
  */
 #if defined(zgbt1281a2uart0)
 #  define HIF_TYPE (HIF_UART_0)
-#elif defined(zgbt1281a2uart1)
+#elif defined(zgbt1281a2uart1) || defined(myboard)
 #  define HIF_TYPE (HIF_UART_1)
 #elif defined(zgbt1281a2nouart)
 #  define HIF_TYPE HIF_NONE

Now the libaries and binaries for "myboard" will be build correctly, you will find them in the directory uracoli-devel/install:

work/uracoli-devel$ ls -l install/*/*myboard*
install/bin/albo_myboard.elf*
install/bin/albo_myboard.hex
install/bin/diag_myboard.elf*
install/bin/diag_myboard.hex
install/bin/rdiag_myboard.elf*
install/bin/rdiag_myboard.hex
install/bin/sniffer_myboard.elf*
install/bin/sniffer_myboard.hex
...
install/lib/libio_myboard.a
install/lib/libradio_myboard.a
install/lib/libwibohost_myboard.a

Build a source code package

To give away a software package together with your hardware, just run the command:

scons  boards=../customboard/boards.cfg version=customhw-1.0 psrc
...
...
Zip install/uracoli-src-customhw-1.0.zip

NOTE: You need to run the command twice, the first run will fail, something is wrong with the dependencies.

Customization HowTo

Preparation

Setup the Custom Configuration Directory

Create boards.cfg

Creating and using myboard.h

Build a source code package

Further Steps

more topics