Application Note: JN-AN-1086

JenNet Over-Network Download

This Application Note provides a starting point for developing wireless networking applications featuring Over-Network Download (OND). This mechanism updates the software of nodes in a JenNet network by transmitting new software over the running network. OND provides a number of advantages over programming nodes individually: Only a physical connection to the Coordinator node is required, avoiding the need to physically connect to and program each node individually. The applications normal communications can continue even while nodes are downloading new software. The activation of new software can be scheduled so that all nodes in the network update to the new software together, avoiding protocol incompatibilities between different versions of the application and networking stack.

Application Overview
The application described in this Application Note downloads new software to nodes in a JenNet tree network, formed using the boards of a JN5148 or JN5139 evaluation kit (with the boards acting as standard Coordinator, Router and End Device nodes).

Device Types
JN5148 and JN5139 devices cannot run each others software binary (.bin) files. This Application Note assumes that the application is used in a network built from only JN5148 devices or only JN5139 devices. Various IDs used by the application are set differently between JN5148 and JN5139 devices to prevent mixed networks forming and the downloading of incompatible software binaries. The user will need to make considerable modifications to use this mechanism in a network built from a mixture of JN5148 and JN5139 devices.

Software IDs and Versions

Each software binary file (.bin) has a unique numeric ID embedded in the file. These software IDs are used to differentiate between software that performs different tasks. This application uses three different software IDs, one for each node type (Coordinator, Router and End Device). The software binary files also contain a numeric version number embedded in each file. This version number is used to differentiate between different versions of software with the same software ID. This Application Note uses a single version number shared across the three different software IDs. This ensures that a change in version number is reflected across the whole of the application.

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

JenNet Over-Network Download

Memory Usage
The following sections give details on the implications of memory and software sizes when developing Over-Network Download (OND) applications.

Memory Size
The JN5148 and JN5139 devices use their RAM to store both the software and data for the running application. The size of the RAM therefore limits the size of the software and its data. The JN5148 chip has 128 KB of RAM while the JN5139 chip has 96 KB of RAM. The software binary (.bin) files produced by the compiler contain the software and data that is not initialised to 0. The .bin file is loaded into the Flash memory attached to the chip upon booting the software, then data is transferred from Flash memory into RAM and the software is executed. Where modules are being used, a JN5148 module has 512 KB of Flash memory while a JN5139 module has 128 KB of Flash memory. Where JN5148/JN5139 chips are being used on custom boards/modules, the size of the Flash memory is determined by the system designer.

Software Size
During the software update process, each node holds two software images in its Flash memory: the active running software image and an inactive image to upgrade to. The size of the Flash memory can have implications for the maximum size of the software that can be supported: For JN5148 software, the maximum theoretical .bin file size is 128 KB (matching the RAM size). In order to support OND for software images of this maximum size, the Flash memory must be at least 256 KB. This is the case when using JN5148 modules, as they are fitted with 512 KB of Flash memory. For JN5139 software, the maximum theoretical .bin file size is 96 KB (matching the RAM size). In order to support OND for software images of this size, the Flash memory must be at least 192 KB. This is not the case when using JN5139 modules, as they are fitted with only 128 KB of Flash memory, reducing the maximum .bin file size to 64 KB when using these modules.

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Application Size
This Application Note implements the features required for Over-Network Download. It will also be necessary to add software and data to implement the user application. While a significant amount of code is used to implement the OND features, many of them can be re-used by the user application, including a simple task-based timer, and input/output routines for the Coordinator UART. For JN5148 designs with the standard 512 KB of Flash memory, there is plenty of free space available to add further features to the application, as shown in the following table:
JN5148 Coordinator Router End Device Used RAM (128 KB) 45.5 KB 42.7 KB 31.9 KB Flash (512 KB) 30.8 KB 29.1 KB 21.2 KB Unused RAM (128 KB) 82.5 KB 85.3 KB 96.1 KB Flash (512 KB) 97.2 KB 98.9 KB 106.8KB

For JN5139 designs with the standard 128 KB of Flash memory, the free space is more limited. If a custom design is used to increase the Flash memory to 192 KB or more, additional free space can be gained. Additionally, compiled software for JN5139 devices is not as efficient as that for JN5148 devices and so takes up more space.
JN5139 Coordinator Router End Device Used RAM (96 KB) 63.0 KB 59.4 KB 44.9 KB Flash (128 KB) 54.3 KB 51.9 KB 40.2 KB Unused RAM (96 KB) 33.0 KB 36.6 KB 51.1 KB Flash (128 KB) 9.7 KB 12.1 KB 23.8 KB Flash (192 KB) 41.7 KB 44.1 KB 55.8 KB

JenNet Save Context

This Application Note does not make use of the save context features of JenNet. Where these features are used, they require the use of a sector of Flash memory, potentially reducing the amount of Flash memory available for storing the inactive software image. When using JN5148 modules, the Flash memory is large enough to allow the use of save context features and also to allow full-sized software images to be downloaded. When using JN5139 modules, the Flash memory is not large enough to allow the use of save context features, as 32 KB of Flash memory would be required for saving the context, reducing the maximum possible inactive software image size to 32 KB.

Initial Programming
A set of pre-built application binary files can be found in the Build folders provided with this Application Note. To demonstrate the OND functionality, these binary files should initially be programmed directly into the boards (via physical connections) using the JN51xx Flash Programmer application. One node should be programmed with the Coordinator binary file, and the other nodes should be programmed with the Router and End Device binary files, as required. The device type (JN5148 or JN5139) with which the binary files are compatible are indicated in the filenames.

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

JenNet Over-Network Download

Starting the Network

Ensure that the Flash Programmer, if used, is closed or disconnected from the serial port on the PC. Connect the Coordinator nodes UART0 to the PC using a serial-to-USB cable provided with the evaluation kit. You should use a terminal emulator, such as HyperTerminal, to monitor and control the OND process from the Coordinator node. The serial connection is 115200bps, 8 data bits, no parity, 1 stop bit, no flow control, by default. When the Coordinator is switched on, LED0 will flash quickly while the network is started. When the Coordinator has created the network, it will output a report message to UART0 as follows:
000265 J 0x00000000 C 0 0x1500 0x0001 0xffff 0xffff

The other nodes can then be switched on. LED0 flashes on each node as the node tries to join the network (on an End Device, this will stop when sleeping between join attempts). On joining the network, each node sends a report message to the Coordinator, which will output the data from UART0 as follows:
003816 J 0x00000008 R 1 0x1501 0x0001 0xffff 0xffff 0xffff 0xffff 0x00000000

The values shown in the report messages are as follows (where the numbers indicate the positions of the values from the left): 1. 2. Timer this gives timing information for the event and is in 10-ms units Events a set of characters that indicate any special events that have caused the report: J The node has just joined or re-joined the network D The node has detected that its depth in the network has changed S The node has started downloading a software image F The node has finished downloading a software image X The node has downloaded a software image over its UART Address of the node that generated the report (only the least significant 32 bits of the address are reported) Type of node that generated the report: C Coordinator R Router E End Device Depth of node in the network Active software ID Active software version Inactive software ID Inactive software version

3. 4.

5. 6. 7. 8. 9.

10. Currently downloading software ID (not Coordinator) 11. Currently downloading software version (not Coordinator) 12. Parent address of the node (not Coordinator)

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Building New Software

To prepare new software to download to the nodes, it must first be built with a new version number. The version number is shared between all the applications and is specified in Application.h in the APP_VERSION define:
#define APP_VERSION 0x0002 /**< Application version */

Changing this value and building will create a new set of binaries for downloading. The Building and Downloading the Application section of this document details how to build the application.

Downloading and Activating New Software

When the network has formed and the new software is ready for download, the software can be downloaded to all network nodes and activated in the following stages:

Stage 1 Starting Point

The Stage 1 diagram shows the starting point for an Over-Network Download. The nodes in the network are shown as squares divided in two, the upper half representing the active software image and the lower half representing the inactive software image (left blank, as no software image is loaded at this stage). The software IDs are indicated by the letters: C for Coordinator, R for Router and E for End Device. Similarly, the software version is indicated by a number, 1 for all the nodes at this stage. The dotted lines indicate the parent/child relationships between the nodes and represent the applications network activity. A Personal Computer (PC) is also shown, which is connected to the Coordinator node via a UART. While in the network, each node will send a report message to the Coordinator every 5 minutes or whenever an event triggers the report. Each child node also requests the status of its parent every 30 seconds, to determine if there is new software to download or a timer to activate new software is running. LED0 is briefly illuminated whenever data is transmitted or received over the radio.

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

JenNet Over-Network Download

Stage 2 End Device Image to Coordinator

New software images for downloading are initially transferred into the Coordinators inactive software image using the standard XMODEM protocol over UART0. Child nodes regularly query their parent node to discover the software ID and version of their parents inactive software image. If the child needs to download the parents inactive image to become its own inactive image, it will begin the download process. As End Device nodes are always at the edge of the tree, new End Device software should be downloaded first, so it can then be downloaded through all the levels of the network tree to reach the End Device nodes located on the edge. The Stage 2 diagram shows the Coordinator node downloading the End Device version 2 software into its inactive image space. Pressing Ctrl-r in the terminal application will place the Coordinator into XMODEM receive mode and a message will be output to confirm this:
176826 XMODEM receive (Ctrl-x to cancel)...

The Coordinator supports standard XMODEM and also XMODEM 1K (which will run more quickly). The End Device binary should then be selected and sent to the Coordinator using the terminal applications interface. If using HyperTerminal, select the Transfer > Send File menu entry, find and select the binary file using the Browse button, select the appropriate protocol (XMODEM or XMODEM 1K) from the Protocol dropdown menu and finally press the Send button. The Coordinator only remains in XMODEM mode for a few minutes, so the transfer will need to be restarted if XMODEM mode is left. The transfer can also be cancelled by pressing Ctrl-x in the terminal application. LED1 is illuminated whenever the Flash memory is accessed while the new binary is being transferred. When the XMODEM transfer completes, the Coordinator outputs a message indicating whether the transfer was complete, together with the address and length of the downloaded image. The Coordinator will also output an updated report message, indicating the end of the XMODEM download and specifying the new software that has been downloaded into the inactive software image space:
178475 XMODEM end complete 0x10000 0xa800 178500 X 0x00000000 C 0 0x1500 0x0001 0x1502 0x0002

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Stage 3 End Device Image to Children (First Level)

The remainder of the download will then automatically proceed. The children of the Coordinator will discover the new image and begin to download it. Normal communications through the network can continue while the download is taking place, including communications between nodes participating in a download.

An End Device will download the inactive software image from its parent only if this new software has a different version from the active software ID running on the End Device. The Router node also downloads the new End Device image, as the Router may have End Device children of its own that may need to download the software image. If a node loses its parent during the download, it will attempt to re-join the network. Once rejoined, it will query its new parents inactive software image. If this is the same image that was being downloaded before the loss of the parent, the download will resume from the new parent. As nodes start, resume and finish downloading, the report message is sent to the Coordinator with the updated software IDs and versions. The Coordinator outputs this data on UART0 to allow tracking of software images being downloaded:
178505 197721 S F 0x0000000c R 1 0x1501 0x0001 0xffff 0xffff 0x1502 0x0002 0x00000000 0x0000000c R 1 0x1501 0x0001 0x1502 0x0002 0xffff 0xffff 0x00000000

LED0 will be flashed when data is transmitted or received, and LED1 flashed when the Flash memory is accessed.

Stage 4 End Device Image to Children (Remaining Levels)

The new End Device software image will be downloaded through the tree, one level at a time, until all nodes have the new End Device software. Router nodes without children will download new End Device software, so that it will be available if nodes orphaned elsewhere in the tree re-join with the childless Router as their new parent.

It is possible to support End Devices running different software by downloading additional images into the Coordinator and allowing them to download through the network. Each additional End Device software image must have its own unique software ID.

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

JenNet Over-Network Download

Stage 5 Router Image to Coordinator

When all End Devices have their new software, the new Router software should then be transferred to the Coordinator from the PC via the UART.

Stages 6 and 7 Router Image to Children

The new Router software image will be downloaded through the tree, one level at a time, to all the Routers. A Router will download the inactive software image from its parent only if this new software has a different version from the active software ID running on the Router. An End Device node will not download a Router image from its parent. As each Router must download the software image from its immediate parent Router, only one Router software image can be supported within the network using this mechanism.

Stage 8 Coordinator Image to Coordinator

When the Routers are all updated, the new Coordinator software image is simply transferred into the Coordinators inactive software image space. At this point, each node has a new version of the software it is running and is ready to upgrade.

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Stage 9 Schedule Activation

To upgrade the software, a command is issued from the PC to the Coordinator. This causes the Coordinator to schedule a timer around which the nodes in the network should synchronise the activation of their inactive software. The timer value is passed down the network, from parent to child, as each child node queries its parent.

The initial timer period is set to double the expected length of time that the timer value will take to reach the deepest nodes in the network, based on the network depth. To activate the new software throughout the network, press Ctrl-y in the terminal application. The Coordinator will output a message, indicating the time remaining (in 10-ms units) until the activation is scheduled:
344870 ACTIVATE SCHEDULED 12000

Stage 10 Leave Network and Activation

As the activation time approaches, the nodes will begin to leave the network, beginning with the deepest nodes and working back up the tree. When the activation time is reached, the Coordinator will output an activating message:
356880 ACTIVATING

All the nodes will then copy the inactive software image to the active image space (replacing the previous active image).

Stage 11 Reset and Rebuild Network

After activating the image, the nodes will perform a software reset in order to start running the newly upgraded software, beginning with the nodes at the top of the tree and working down. The leave-activate-reset sequence is managed in this way to avoid the excessive radio communications that might occur if the nodes were to activate and reset at the same time. Nodes that lose their parents during the process will not try to re-join the network before they themselves activate, and so will not interfere with nodes that are already activated and attempting to re-build the network with the new software.
JN-AN-1086 (v1.3) 20-Sep-2010 NXP Laboratories UK 2010 9

JenNet Over-Network Download

Resetting from the top down increases the likelihood that the tree will be rebuilt in a similar topology to the one which existed before the upgrade and also allows the communications required when rebuilding the network to be staggered in order to avoid radio conflicts. When the Coordinator has re-started the network, it will output its report message:
000265 J 0x00000000 C 0 0x1500 0x0002 0x1500 0x0002

The remaining nodes will also send their report messages to the Coordinator as they re-join the network:
001758 J 0x0000000c R 1 0x1501 0x0002 0x1501 0x0002 0xffff 0xffff 0x00000000

The network is then fully upgraded, with each node running the new version of its software.

Monitoring the Network and Downloads

The report messages output by the Coordinator allow the nodes in the network to be monitored based on a simple time-window. As each node is expected to report every 5 minutes, any node which has not reported could be considered as missing from the network. A similar approach can be applied to determine when all nodes requiring a software upgrade have been updated. This is done by examining the inactive software IDs and versions reported within a certain time-window. The Coordinators report message is shorter than the report message for other nodes. When monitoring using a terminal application, this makes each time-window easier to recognise in the display. It is beyond the scope of this Application Note to determine when it is safe to upgrade from one version of software to another. For some applications, it may be a requirement to ensure that all nodes which have previously been part of the network are ready to switch. For other applications, the regular joining and leaving of nodes may be a normal feature of the application, and nodes which are known to have permanently left could be ignored. The UART output could be monitored by an application running on the PC in order to provide more readable information about the nodes in the network, as well as to monitor other data unrelated to the OND.

10

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Software Design
This Application Note was created using the Jenie Application Programming Interfaces (APIs). These APIs provide an easy-to-use interface for developing wireless networking applications for the JN5148 and JN5139 devices. The Jenie APIs comprise C functions for controlling the wireless network and the on-chip hardware peripherals. A User Guide (JN-UG-3041) and other detailed information about JenNet and the Jenie APIs can be found in the Support section of the Jennic web site.

Module Overview
Code that is shared by more than one device type is located in the Common\Source folder. Code that is only used by a single device type is located in the Coordinator\Build, Router\Build and EndDevice\Build folders. The software is built from the following modules:

Application.h
This header file contains many defines used throughout the application, including defines for: Specifying the parameters of the network to join Addresses of the active and inactive software images in Flash memory UARTs to be used by the application Timing values for various functions

Coordinator.c/h
This is the main module for the Coordinator node, which in turn makes use of the Node, Task, Flash, Parent, Xmodem and UartIO modules. This module contains the standard set of Jenie callback functions. The module provides the following functionality: Outputs to the XMODEM UART report messages generated on the Coordinator node and received from other nodes Coordinates the activation of new software images throughout the network and handles the activation of its own inactive image

Router.c/h
This is the main module for the Router node, which in turn makes use of the Node, Task, Flash, Parent and Child modules. This module contains the standard set of Jenie callback functions. The module handles the activation of its inactive software image.

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

11

JenNet Over-Network Download

EndDevice.c/h
This is the main module for the End Device node, which in turn makes use of the Node, Task, Flash and Child modules. This module contains the standard set of Jenie callback functions. The module provides the following functionality: Initiates polling of the End Devices parent for data and pinging the parent as necessary in order to stay in the network Low-power sleep mode which allows the End Device to periodically sleep and wake Handles the activation of its inactive software image

Node.c/h
This module contains the code that is common to all the node types. It provides the following functionality: Tracks the status of the node in the network Handles the control of LED0 to indicate network activity Reads software image IDs and versions from Flash memory Activates the inactive software image Provides debugging functions when enabled This module also declares the public sNode structure which contains data about the node used throughout the application.

Task.c/h
This module contains code used by all node types. It provides the following functionality: Allows tasks to be scheduled on a single or repeating basis and also specifying retries and retry intervals for tasks Immediate activation of tasks for execution, over-riding the scheduled time Completion of tasks that are executing, in order to end the retry functionality Cancellation of tasks that no longer need to run Querying the status of tasks, including time remaining until scheduled to execute Timing functions to select the highest priority task to execute in a single timer period Timing of tasks across sleep periods on End Devices

12

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Flash.c/h
This module provides code to read and write to Flash memory. It provides the following functionality: Control of LED1 indicating access to Flash memory Reading data from Flash memory Writing data to Flash memory, automatically erasing a sector when the start address of the sector is written to, and preventing overwriting of the MAC address and licence stored in sector 0 Erasing Flash sectors, automatically preserving the MAC address and licence stored in sector 0

Xmodem.c/h
This module provides XMODEM support for the Coordinator node using the UartIO module. It provides the following functionality: Processes command key presses to initiate the reception of new software using XMODEM and the activation of new software XMODEM protocol support to transfer a binary file to Flash memory

UartIO.c/h
This module provides basic UART support for use by the Xmodem module, as well as debugging (when enabled). It provides the following functionality: GetChar functionality for reading from the UART PutChar functionality for writing to the UART

Parent.c/h
This module provides functionality required by the Coordinator and Router modules when acting as parents of other nodes. It provides the following features: Processes and replies to the query status message sent by child nodes Processes and replies to the download software message sent by child nodes

Child.c/h
This module provides functionality required by the Router and End Device nodes as children of other nodes. It provides the following features: Sends report messages to the Coordinator at regular intervals or whenever events occur Regularly sends a query message to its parent to determine if new software is available for download or if the network is preparing to activate new software. If new software is available, the download process is started Sends a series of download messages to its parent to request download of new software to its inactive software image space. The message replies containing the software image data are written to Flash memory

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

13

JenNet Over-Network Download

Functional Design
Software ID and Versions
The application needs to be able to determine the ID and version of the software images contained in the Flash memory and also whether they are valid OND software images. The 12 bytes of data in the software image at address offset 0x24 are reserved for data to control the Over-Air Download process built into all JN5148 and JN5139 chips (JN-AN-1057: Over Air Download provides examples of this alternative download process). The Over-Network Download uses the same block of data in a slightly different way to embed the software ID and version into the binary file. The structure of the header data is as follows: Offset 0x24 to 0x27 0x28 to 0x29 0x2A to 0x2B 0x2C to 0x2F Usage Unused this is always set to 0 to avoid confusion with Over-Air Download applications Software image version used to distinguish different versions of the same software image Software image ID identifies different software images Unused this is always set to 0xF0F0F0F0 to avoid confusion with Over-Air Download applications

The software image ID and software image version used by Over-Network Download are specified by the following variables in the Coordinator.c, Router.c and EndDevice.c modules, as follows:
/* Set uint16 /* Set uint16 OND software id and have linker place in .ondsoft section */ u16OndSoftwareId __attribute__((used, section(".ondsoft"))) = 0x1500; OND software version and have linker place in .ondver section */ u16OndSoftwareVersion __attribute__((used, section(".ondver"))) = APP_VERSION;

Each of the modules specifies a different software ID, but all share the same software version. The software ID values control which nodes will download a software image from their parent the End Device software IDs should be greater than the Router software ID, which in turn should be greater than the Coordinator software ID (this is covered in more detail in the Download Process section below). The custom linker files ONDAppBuild_JN5148.ld and ONDAppBuild_JN5139.ld, located in the Common\Build folder, are used by the linker in place of the standard linker files. These custom linker files must be specified by the Code::Blocks project file or makefile. The linker files ensure that the specified values are positioned at the correct address offsets in the compiled binary files and also that the fixed values are correctly set to avoid confusion with Over-Air Download applications. Finally any gaps in the compiled binary files are filled with 0xff bytes by specifying the --gapfill 0xff option for ba-elf-objcopy in the Code::Blocks project file or makefile.

14

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Dual Software Images

The system makes use of two software images for the following reasons: The protocols used by JenNet may change between different versions of JenNet. By having all nodes switch to new software at the same time, problems due to nodes running different JenNet protocols within a single network are avoided. This also applies to any protocols being used at the application layer. The download process may take a long time in total. By integrating the update into the actual application and leaving the network intact during the download process, the application can continue to run normally, resulting in minimal downtime during a download. If power is lost during the download, a node that regains power is able to re-join the network and resume the download.

Software Detection
The function vNode_Software() is able to read the binary header of an active or inactive image and determine which type of binary file, if any, is stored at the given location. For a valid OND image, this function calculates a checksum for the image. This function is called whenever a software image may have changed. The results are stored in the asSoftware member of the sNode structure, and are therefore available throughout the application.

UART Input and Output

The Coordinator node uses UART0 for input and output, and also for the XMODEM protocol support. These UART input and output routines can also be used by the user application. It is possible to add both UART and XMODEM support to the Router and End Device binaries. Where UART support is included in all the device types, a debugging option can be enabled to allow the application events to be observed through output to the UARTs.

Tasks
A simple task system is used to schedule activities within the application. The available tasks across the whole application are defined in Application.h, by means of the APP_TASK defines. A task is initially scheduled by calling the bTask_Schedule() function, specifying the delay to the first execution, the duration between repeats of the task (for regularly scheduled tasks), and the retry interval and number of retries (for retrying tasks). The vTask_Timer() function is called regularly to check if it is time to execute any scheduled tasks. Any tasks ready for execution are activated using the bTask_Activate() function, specifying the retry interval and count for the activation. This function can also be used by the application to over-ride the scheduled activation time for a task. The vTask_Timer() function then checks the activated tasks. If it is time to execute an active task then the task with the highest priority is flagged as the executing task for the current timer interval. Since most tasks result in the generation of a communication message, limiting the task execution to one task per timer period avoids many tasks attempting to send data at the same time and flooding the MAC layer transmit buffers.
JN-AN-1086 (v1.3) 20-Sep-2010 NXP Laboratories UK 2010 15

JenNet Over-Network Download

The modules which are responsible for executing the tasks query the currently executing task using the u8Task_Execute() function. A module takes the appropriate action if one of the modules tasks is returned by this function. The bTask_Complete() function cancels any remaining retries for an active task. The bTask_Cancel() function immediately cancels a task. Each time a task is activated or executed, a small random amount of time is added to the time to the next scheduled or retry period. This prevents different nodes (within range of each other) from experiencing radio conflicts due to use of identical timer intervals. It is possible to add additional tasks, allowing the user application to make use of the task functionality

Communications
The majority of communications are initiated from a node to its parent, with occasional communications to the Coordinator. Where data is present in a message, it is always current data from the application. If a previously sent message is not acknowledged then a new message of the same type is built from the current data and sent again to the destination. This scheme ensures that outstanding messages are received by the destination node without requiring a message queue. All the messages are initiated by a task being executed from the task system.

Protocol
All messages used within the application have a first character of tilde (~). The second character is used to indicate which module in the system the message is being sent to. The remaining data is then dependent upon the message type. Coordinator.c, Router.c and EndDevice.c initially receive all data messages which then call the destination modules receive message handler. The following characters are used to indicate destination modules for messages: c Child.c o Coordinator.c p Parent.c The third character indicates the message type for the module. The following characters are used for message types: d download q query r report The following combinations of protocol headers are used: ~or Report message, from child to Coordinator ~cr Report reply, from Coordinator to child ~pq Query software message, from child to parent ~cq Query software reply, from parent to child ~pd Download message, from child to parent ~cd Download reply, from parent to child The remaining data is then dependent upon the message destination and type.

16

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

This method of directing received messages to the appropriate module can be extended for other communications required by the application.

Status Monitoring
A child node monitors the status of its parent to discover if new code is available for downloading and if activation of the new software is scheduled. The Child module schedules the CHILD_QUERY task, which executes at regular intervals. When the task executes, a simple query message is transmitted to the nodes parent. The Parent modules acknowledgement contains the following information: The identifier, version, length and checksum of the inactive image (if one is stored in Flash memory). If the software image is suitable for download then the download process will be initiated. The report message is sent to the Coordinator when a download is started or resumed and the Coordinator outputs the relevant data to the UART. The initiation of a download is dependent upon the node type: End Devices will only download software images with different versions but the same ID as the software they are currently running. This allows multiple End Device software images to be used in the network. Routers will download different versions of software that they are already running or software with a higher ID than their own. Since an End Device software image has a higher ID than a Router software image, this allows the End Device software to pass down through the Routers to the End Devices. This also prevents Routers from downloading a Coordinator image, which has a lower ID. It does, however, only allow a single Router image to be used throughout the network.

If the parent is preparing to activate new software then the child also initiates this process. The depth of the parent node in the network may change if the parent, or any other node higher in the tree, loses its network and re-joins at a different depth. If the child determines that its own depth has changed, a report message is sent to the Coordinator, which outputs the data to the UART.

Download Process
The download process is initiated by noting the ID, version, size and checksum of the software image to be downloaded. If the download is not being resumed from an earlier attempt then the offset into the download is set to zero and the inactive software Flash sectors are erased. The CHILD_DOWNLOAD task is then started and the CHILD_QUERY task is cancelled. When the download task executes, a simple message is sent to the parent specifying the offset into the download of the requested block of data. The download task retries until the parent replies with the appropriate block of data. The download reply contains the software identifiers. If they correspond to the software being downloaded, the part of the image contained in the download is written to Flash memory and the offset into the image is updated for the next part of the image. The current download task is then completed and a new download task is scheduled a short time later for the next block of data.

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

17

JenNet Over-Network Download

Increasing the retry and start-time intervals for the download task causes more bandwidth to be available for the users part of the application and to cope with situations where there are many nodes within range of each other potentially downloading at the same time (though the overall download speed will be slowed). Similarly, decreasing these times will speed up the download if the application requires little bandwidth or nodes are more widely distributed. When the full image has downloaded, the checksum is checked and the query task is resumed. When a download has finished, the report message is sent to the Coordinator, which outputs the data to the UART. If the node loses its network connection while downloading and then re-joins the network, it will resume the download if it finds that its parent still has the image that was being downloaded.

Activation Process
The activation process is initiated by the Xmodem module in the Coordinator, as the result of a Ctrl-y key press. The activation of images is synchronised around a timer. The current value of the timer is passed down the network in the query reply messages. The timer is initialised in the Xmodem module to be double the time it is expected for the activation timer to filter down to the deepest nodes in the network (based on the maximum network depth reported to the Coordinator and the time interval between child nodes querying their parent). The nodes schedule a NODE_LEAVE task for execution a certain period of time before the synchronised timer reaches zero. This time-period is dependent on how deep the node is in the tree - the deeper the node, the sooner the leave task will execute. When the leave task is executed, the nodes leave the network. This ensures that as the activation time approaches, the nodes leave the network, working from the bottom up. The nodes also schedule a NODE_ACTIVATE task for execution a certain period of time after the synchronised timer reaches zero. Again, this time-period is dependent on how deep the node is in the tree - the deeper the node, the later the activate task will execute. When the activation task is executed, the inactive software image is copied over the active software image in Flash memory, and a software reset is issued to restart the node and run the new software. An End Device continues to sleep and wake normally while the leave task is waiting to execute, in order to allow normal application activity to continue. However, if the remaining time to the scheduled leave is less than the normal sleep time, the sleep period is set such that the End Device will wake at the correct time to execute the leave task. When the leave task executes and the STACK_RESET event is raised (indicating a successful leave), the End Device copies the inactive software image over the active image and then goes to sleep without holding RAM for the time remaining until the scheduled activation task. When the End Device wakes, it will then start to run the new software. If, for some reason, the leave process fails to work as expected, the activation task will be executed in the normal way at the scheduled time.

18

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

End Device
When the End Device wakes and finds that it is not in the network, it attempts to join the network by calling the Jenie_Start() function. When the End Device wakes and finds that it is in the network, Jenie_Start() is not immediately called - this keeps the radio domain powered down in the End Device in order to preserve power. The eNode_SendData() function will call the Jenie_Start() function if required to power up the radio domain and send data. This allows the End Device to wake and sleep without powering up the radio domain at all. The End Device sleeps and wakes regularly while in the network, under the control of the application. The time spent awake and asleep is configured by the defines APP_TIME_ENDDEV_AWAKE and APP_TIME_ENDDEV_SLEEP in Application.h. On waking, the nodes internal timer is updated by the period of time that the End Device was asleep. This allows task timings to take into account both the awake and sleep periods of the End Device. If an End Device wakes after the scheduled time for a task, the task is executed on waking. Since it is also possible to query the time remaining until a scheduled task, a sleep period can be changed to ensure that the End Device wakes at the exact time a task is scheduled. This feature is used to make sure the leave and activation tasks are executed as close as possible to their scheduled times. When live in the network (the stack has been started and the network is up), the End Device regularly executes the ENDDEV_POLL task, at a rate set by SCH_ENDDEV_POLL_REPEAT, to check for new data in the parent. When data is sent by the End Device, indicated by a PACKET_SENT event, a reply is likely to be returned to the End Device. The poll task is immediately activated with a number of retries in order to retrieve such replies in a timely manner. If a data message is received, the poll task is immediately activated again to check for additional messages buffered in the parent node. This activation specifies no retries and so effectively cancels any remaining retries from a poll task activated as the result of a PACKET_SENT. The End Device must regularly communicate with its parent node to stay in the network. This is largely achieved by the CHILD_QUERY task and message in this application. However, the End Device also runs an ENDDEV_PING task - if this task executes, an empty message is sent to the parent to keep the End Device in the network. Whenever a PACKET_SENT event occurs, the ping task is re-scheduled therefore, if other data is being regularly sent, the ping task will never execute.

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

19

JenNet Over-Network Download

Adapting the Application

This section details a number of ways in which the application can be adapted to meet different requirements.

Timings
As previously mentioned, many of the timings are controlled by defines in Application.h. In particular, adjusting the download timings to increase the time between download requests can provide more bandwidth for the applications data and cope with more nodes operating within range of each other. The default values provide a reasonably fast update for development purposes (approximately 5 minutes for each level of the network tree). In production use, updates should be few. Therefore, taking a longer period to download should not cause any problems, especially as the main application should be able to run and send its own data while the downloads are taking place. A parent node must have completed its own download of an image before its children can begin downloading. Where nodes are more spaced out, improved overall performance may result from allowing child nodes to begin downloads before their parents have completed the download themselves.

JN5139 Large Software Images

For JN5139 module designs, the 64 KB limit on image size when using modules can be quite restrictive, even if features of the OND application are being reused by the user application. It is possible to download directly into the active image space provided that there is high confidence that power will not be lost during the download - for example, with battery powered devices. The old software will continue to run from RAM until the nodes are reset. It is not unusual for the user application in the Coordinator node to contain a great deal of code. A compromise is to use the dual-image system in the End Devices and Routers, and to use a single image in the Coordinator. Another alternative is to download a compressed image and decompress it on activation. Binary files seem to compress to half their original size using LZMA compression. Dividing the Flash memory into three would allow an uncompressed image of 84 KB from a compressed image of 42 KB. However, code would need to be added for decompression, plus Flash routines would need to be written to more selectively erase sections of Flash memory, as sector 2 would potentially need to contain data from both the active and inactive images. Adding an extra or larger Flash component to the hardware of the device would allow the inactive image to be stored elsewhere during download, leaving the whole of the standard Flash memory free to be used in the normal way. Software images up to the standard maximum size could be used and the save/restore context features could be implemented. The downloading and activation routines would need to be adapted to read and write the inactive image to Flash memory added in this way.

20

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Multiple Router Images

Since the Router binary is downloaded, a single level at a time, only one can be supported across the network at a time. Alternative binaries for Routers that stay at the edge of the network (by never accepting children of their own) are quite easily catered for by allocating to them a software ID that is greater than the ID for the other Routers. Alternatively, Routers could be configured to download software from another device that is not their immediate parent, in order to hop different Router images over each other. This approach could also be employed in systems with a mix of JN5148 and JN5139 devices. This would require careful management to find or specify a suitable source for each Router node to use.

Communications Management
The communications in this application are managed from the bottom-up, with nodes lower down in the network initiating communications. This is convenient for a general-purpose Application Note, since it is not known how the final application will work and since End Devices could be waking and sleeping at different rates. Managing the communications from the top down can often result in a more efficient use of the radio bandwidth, with the Coordinator node initiating the communications. This should be considered when writing the user application, but once again the timings can be increased to reduce the demands of the OND on the overall bandwidth. The End Device code in this application only schedules the poll task to run when it is live in the network (the network is up and the stack has been started). For applications in which data is sent to End Devices unsolicited, it will be necessary to schedule the polling task to execute when the network is up, and also to ensure that the stack is started using eJenie_Start() within the eEndDevice_PollParent() function.

General
At its most basic level, this application is concerned with moving a large amount of data to numerous nodes, and writing it to and moving it around Flash memory. There are potentially many different ways to achieve such a result. For example, a network formed without any End Devices could make the whole process more efficient by using a broadcasting system, and avoid the repeated resending of each packet of data between every child and parent in the network tree. The principles and techniques used in this application should be used as the starting point for your own application.

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

21

JenNet Over-Network Download

Building and Loading the Application

The software provided with this Application Note can be built for the JN5148 or JN5139 device. However, the available build methods differ between these chip types: JN5148 applications can be built using the Eclipse IDE or makefiles JN5139 applications can be built using the Code::Blocks IDE or makefiles In order to build the supplied software, the applications folder must be placed in the Application folder of the SDK installation: For JN5148: <JN51xx_SDK_ROOT>\Application For JN5139: <JN51xx_SDK_ROOT>\cygwin\jennic\SDK\Application where <JN51xx_SDK_ROOT> is the path into which the SDK was installed (by default, this is C:\Jennic). The Application directory is automatically created when you install the SDK. Build the application as described in the appropriate section below, depending on whether you intend to use Eclipse, Code::Blocks or makefiles.

Using Eclipse (JN5148 Only)

To build the application and load it into JN5148 boards, follow the instructions below: 1. Ensure that the project directory is located in <JN51xx_SDK_ROOT>\Application where <JN51xx_SDK_ROOT> is the path into which the JN5148 SDK was installed. 2. Start the Eclipse platform and import the relevant project files (.project and .cproject) as follows: a) b) c) d) 3. In Eclipse, follow the menu path File>Import to display the Import dialogue box. In the dialogue box, expand General, select Existing Projects into Workspace and click Next. Enable Select root directory, browse to the Application directory and click OK. In the Projects box, select the project to be imported and click Finish.

Build the application. To do this, ensure that the project is highlighted in the left panel of in the Eclipse Eclipse and use the drop-down list associated with the hammer icon toolbar to select the relevant build configuration once selected, the application will automatically build. Repeat this to build the other applications. The binary files will be created in the relevant Build directories for the applications, the resulting filenames indicating both the chip type (JN5148) and networking stack for which they were built.

4.

Load the resulting binary files into the boards. You can do this using the JN51xx Flash Programmer, which can be launched from within Eclipse or used directly (and is described in the JN51xx Flash Programmer User Guide (JN-UG-3007)).

22

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Using Code::Blocks (JN5139 Only)

To build an application and load it into a JN5139 board, follow the instructions below: 1. Ensure that the project directory is located in <JN51xx_SDK_ROOT>\cygwin\jennic\SDK\Application where <JN51xx_SDK_ROOT> is the path into which the JN5139 SDK was installed. 2. Open the appropriate Code::Blocks project file (.cbp file in the CodeBlocksProjects directory) and build. Alternatively, the supplied Code::Blocks workspace file (.workspace file in the CodeBlocksProjects directory) can be used to open and build the group of project files. The binary files will be created in the relevant Build directories for the applications, the resulting filenames indicating the chip type (JN5139) for which they were built. 3. Load the resulting binary file into the board. You can do this using the JN51xx Flash Programmer, which can be launched from within Code::Blocks or used directly (and is described in the JN51xx Flash Programmer User Guide (JN-UG-3007)).

Caution: If problems occur when using your current Code::Blocks version, download the latest version along with the latest version of this Application Note from the Support area of the Jennic web site (www.jennic.com/support).

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

23

JenNet Over-Network Download

Using Makefiles
The application for each node type (e.g. Co-ordinator, Router, End Device) has its own Build directory, which contains the makefiles for the application. Different makefiles are provided for JN5148 and JN5139 a JN5148 makefile is simply called Makefile while a JN5139 makefile is called Makefile_JN5139.mk. To build an application and load it into a JN5148 or JN5139 board, follow the instructions below: 1. Ensure that the project directory is located in <JN51xx_SDK_ROOT>\Application for JN5148 <JN51xx_SDK_ROOT>\cygwin\jennic\SDK\Application for JN5139 where <JN51xx_SDK_ROOT> is the path into which the JN51xx SDK was installed. 2. Navigate to the Build directory for the application to be built and follow the instructions below for your chip type: For JN5148: At the command prompt, enter:
make clean all

Note that for the JN5148, you can alternatively enter the above command from the top level of the project directory, which will build the binaries for all the applications. For JN5139: At the command prompt, enter:
make -f Makefile_JN5139.mk clean all

In both the above cases, the binary file will be created in the relevant Build directory for the application, the resulting filename indicating both the chip type (JN5148 or JN5139) for which the application was built. 3. Load the resulting binary file into the board. To do this, use the JN51xx Flash Programmer, described in the JN51xx Flash Programmer User Guide (JN-UG-3007).

Compatibility
The software provided with this Application Note has been tested with the following evaluation kits and SDK (Software Developers Kit) versions:
Product Type Evaluation Kits Part Number JN5139-EK000 JN5139-EK010 JN5148-EK010 SDK Libraries SDK Toolchain JN-SW-4030 JN-SW-4040 JN-SW-4031 JN-SW-4041 Version v1.5 v1.4 v1.1 v1.1 Supported Chips JN5139 JN5139 JN5148 JN5139 JN5148 JN5139 JN5148

24

NXP Laboratories UK 2010

JN-AN-1086 (v1.3) 20-Sep-2010

JenNet Over-Network Download

Revision History
Version 1.0 1.1 1.2 1.3 Notes First release Updated for JN5148 Compatibility table updated with inclusion of Jenie in JN5148 SDK Libraries installer Terminology and logo changes made

Important Notice
Jennic reserves the right to make corrections, modifications, enhancements, improvements and other changes to its products and services at any time, and to discontinue any product or service without notice. Customers should obtain the latest relevant information before placing orders, and should verify that such information is current and complete. All products are sold subject to Jennics terms and conditions of sale, supplied at the time of order acknowledgment. Information relating to device applications, and the like, is intended as suggestion only and may be superseded by updates. It is the customers responsibility to ensure that their application meets their own specifications. Jennic makes no representation and gives no warranty relating to advice, support or customer product design. Jennic assumes no responsibility or liability for the use of any of its products, conveys no license or title under any patent, copyright or mask work rights to these products, and makes no representations or warranties that these products are free from patent, copyright or mask work infringement, unless otherwise specified. Jennic products are not intended for use in life support systems/appliances or any systems where product malfunction can reasonably be expected to result in personal injury, death, severe property damage or environmental damage. Jennic customers using or selling Jennic products for use in such applications do so at their own risk and agree to fully indemnify Jennic for any damages resulting from such use. All trademarks are the property of their respective owners.

NXP Laboratories UK Ltd Furnival Street Sheffield S1 4QT United Kingdom Tel: +44 (0)114 281 2655 Fax: +44 (0)114 281 2951 E-mail: info@jennic.com For the contact details of your local Jennic office or distributor, refer to the Jennic web site:

JN-AN-1086 (v1.3) 20-Sep-2010

NXP Laboratories UK 2010

25