Beruflich Dokumente
Kultur Dokumente
120-5022-000F
Application Bootloader
This document describes how to program applications for and use the application
bootloader. It is intended for application developers who:
Contents
About the Application The application bootloader is a tool that enables you to load stacks and applications
Bootloader onto nodes in an EmberZNet network. The application bootloader is an Ember
Developer Kit tool that is bundled as an API in the release software. The application
bootloader can be used to load files onto the following processors
• TI MSP4301612
• AVR ATmega128
Ember provides a sample bootload application, which you need to use the over-the-air
bootloading capability with the application bootloader. You can use this sample
application as a starting point for your application or integrate it into your existing
software to perform bootload functions. To perform serial bootload operations, you can
use any terminal application, such as the HyperTerminal utility supplied with Microsoft
Windows.
The application bootloader handles .ebl (Ember bootloader) image files. If you start
your development using a supplied project file, the conversion to an .ebl file is done
automatically within the IAR Embedded Workbench Integrated Development
Environment.
Choosing a Ember offers two bootloaders for use with your application: the application bootloader
Bootloader and the standalone bootloader.
• The Ember Developer Kit nodes come with a certain bootloader pre-installed,
depending on the microprocessor. The TI MSP4301612 kits come with the
application bootloader pre-installed. The AVR kits come with the standalone
bootloader pre-installed.
The application bootloader has a much smaller flash footprint than the standalone
bootloader (about 2kb vs. about 8kb), as it only has to support flash operations.
The application bootloader does not know how to drive the radio; it depends upon the
current application to handle transmitting the new application to the node. In this way,
it can easily support multi-hop bootloading by using the stack’s ability to multi-hop.
Normal network traffic can continue during this time as well.
To support the full stack application running during the bootload process, the
application bootloader requires enough program memory to simultaneously hold both
the current application and the application being uploaded. In the TI MSP430 reference
design, this second application is stored in external EEPROM. In the ATmega128
reference design, this second application is stored in the upper half of internal flash.
The application bootloader also does not know how to drive the serial ports. Therefore,
a recovery image is also included. The bootloader can be put into a special mode where
it will copy the recovery image into place, so that you can serially upload a new image.
For example, if you upload and run an invalid image over the air, your device will no
longer be able to bootload images over the air. Using the recovery image over a serial
port is one way to recover your device without an ISP (In System Programmer).
The standalone bootloader, on the other hand, does know how to run the radio at the
MAC level, which accounts for the larger flash footprint of this bootloader. MAC-level
radio support means that this bootloader can only function across one hop. For the
gateway node supporting the bootload, as well as the node being bootloaded, the
Standalone bootloader cannot support normal application traffic, only MAC-level
bootload packets.
The standalone bootloader does not require the application to do anything other than
initiate the handshake with the gateway node (including any security checks as to
whether or not this node should be allowed to initiate the bootload). The standalone
bootloader also knows how to operate the serial port for serial uploading.
Note: The full flash requirements entries assume that “application size” is fixed.
This is only a rough guide.
Understanding the Before bootloading with the application bootloader, the following must be installed on
Application all nodes involved in the bootload:
Bootloader
• The EmberZNet stack containing the application bootloader API
You will also find the recovery image in the above directory location, which may also
need to be installed depending on your hardware. Both the bootloader and recovery
images are provided in hex format.
An API provided in the HAL (hardware abstraction layer) interacts with the application
bootloader to support code developed to perform various bootload operations. The
Ember sample code is an example of these bootload operations. Alternatively, you can
write an application that performs the functionality described in this document to more
closely match your own requirements.
The actual performance of the bootload functionality depends on the code that
performs the bootloads. For example, there is enough flexibility in the API so that the
application can choose to halt normal application network traffic and send all of the
bootload packets as fast as possible. Alternatively, the application can send one packet
every few seconds, so that normal network operation can continue with little impact.
However, the full bootload transmission time would take over several hours.
Processor memory
Each Atmel or TI processor has memory organized as illustrated in Figure 1 and as listed
and described below. The areas may not be in this same order, or even in the same
device, but all of the areas are necessary.
• Program space: Stores the stack and application images that are executed.
• Recovery image space: Stores the recovery image that is used to restore a node
whose application failed. This recovery image is copied into the program space
when you need to download an application over the serial port. The stock recovery
image provided only supports serial communication.
• Download space: Stores images temporarily that the node has received and writes
them to the program space.
Program Space
Download Space
Power ON
Boot
Is the image a
recovery image? No
Yes
1. When a node powers on, the node boots. While the node boots, it checks for a
recovery signal which can arise for any of the following reasons:
To put an RCM on an Ember Developer Kit carrier board into recovery mode, press
and hold the RFUP_BOOTLOAD button, then press and release the RFUP_RESET
button, and then release the RFUP_BOOTLOAD button.
2. If the recovery signal is asserted, the node overwrites the application with the
image from the recovery image space that is located on the node. The stock
recovery image only supports serial communication.
Any time the recovery image is run your application, program space is
overwritten, so you will need to copy the application down again.
3. The node reboots, and assuming that the recovery signal is cleared, executes the
recovery image.
4. When the recovery image runs, it checks BUTTON1 to determine whether to load a
normal image to the download space on the microprocessor, or to load a new
recovery image into the recovery image area.
To load a new recovery image, press and hold the BUTTON1 button, then press and
release RFUP_RESET, and then release the BUTTON1 button.
5. When the download of the image completes, the recovery image verifies that the
image downloaded successfully. If this was a recovery image, return to step 4,
because you still don’t have a valid application image.
If this was a normal application image, the image in the download area is copied into
place in the program space. The node is reset again, and then execution of the newly
downloaded program is begun.
2. Start HyperTerminal, and connect to the appropriate serial port using the settings
19200, 8, N, 1, no flow control.
3. Press and hold the RFUP_BOOTLOAD button on the carrier board, then press and
release the RFUP_RESET button, and then release the RFUP_BOOTLOAD button to
copy the image stored in the recovery image spaceinto the program space. If you
have the stock recovery image stored in the Recovery Image Space, you should see
a pound symbol (#) printed on the serial port of the node on reset, followed by a
“C” character every few seconds.
4. Send the application bootload sample application to the node. To do this using
HyperTerminal:
c. Browse to where you have the EmberZNet stack installed and where your new
application .ebl file is stored.
f. Click Send.
The .ebl file has a four-byte integrity check included in it. When the upload is done,
the application bootloader will use these bytes to check the integrity of the uploaded
data. If it is successful, an exclamation mark (!) will be printed on the serial port, the
application will be copied to the program space, and the node will be reset, running
your new application. If it fails, it will continue to print “C” on the terminal and wait
for another resend of the file.
2. Start HyperTerminal, and connect to the appropriate serial port using the settings
19200, 8, N, 1, no flow control.
3. Press and hold the RFUP_Bootload button on the carrier board, then press and
release the RFUP_Reset button, and then release the RFUP_Bootload button. This
will copy the image stored in the recovery image spaceinto the program space. If
you have the stock recovery image stored in the Recovery Image Space, you should
see a pound sign (#) printed on the serial port of the node on reset, followed by a
“C” character every few seconds.
4. You are now in the application bootloader’s recovery image. To tell the bootloader
you wish to install an image into the recovery image spaceinstead of the download
space, press and hold BUTTON1, then press and release the RFUP_Reset button,
and then release BUTTON1. You should see “R#” on the serial port instead of just
“#”. This will be followed by a “C” character every few seconds. Any image you
send now will go to the recovery image spaceand will overwrite the recovery image
there.
5. Send the recovery image to the node. If you are using HyperTerminal:
c. Browse to where you have the EmberZNet stack installed, and browse to
tool/app-bootloader/app-bootloader-recovery-target.ebl, where
target is the appropriate microcontroller and possibly board type. If you
have your own recovery image, use that file instead.
f. Click Send.
When the upload is done, the application bootloader will check the CRC of the upload.
If it is successful, an exclamation mark (!) will be printed on the serial port and the
node will be rebooted. You will still need to upload a working application image, as
described earlier in “Updating or installing an application image over a serial port.”
1. A PC or some controlling application sends the new application for the target node
to the gateway node using serial link.
2. The gateway node sends the application, packet by packet, over the air to the
target node, using EmberZNet APS or transport-level packets. See the EmberZNet
Application Developer's Guide for information on sending packets in your
application. The target node writes these packets to the download space in
memory.
3. The application checks the new image’s CRC in download space to make sure it
matches the CRC that the gateway node provides. If it does not match, the process
can be started over by the gateway node.
4. If the CRC matches, the application can tell the application bootloader to copy the
new image from the download space to the program space.
This scenario also assumes that there was one node being bootloaded at one time. If
your application has a lot of one type of node, you can bootload them all at the same
time, possibly even with multicast nodes.
The following API calls are used to complete the steps illustrated in Figure 3:
1. On the target node, after the packets for the new images have been received,
write the application to the download space using
halBootloaderWriteDownloadSpace().
4. If all nodes in a network are being updated, make sure that steps 1 and 2 have
been completed on all nodes and then load the application into program space
using halBootloaderInstallNewImage(). This function overwrites the currently
running application and reboots.
Using Application To use the application bootloader to bootload a node over the air, you need to have an
Bootloader Sample EmberZNet stack application in place that supports the application bootloader API. The
Code sample code provided with the EmberZNet stack meets this criteria. You can find this
sample code in EmberStack/app/app-bootloader-demo/. Before you can use this
over the air, you must serially bootload this application to all of the nodes the first
time, because the application bootloader by itself cannot operate the radio.
The sample application will need to be built using the appropriate IAR Embedded
Workbench for the microcontroller of your choice. The two applications in the project
are the gateway image and the target node to be bootloaded. There can be as many of
these target nodes as you wish. Once you build the two targets, they will be in
EmberStack/build/ under the appropriate target directory.
Follow the earlier instructions on page 7 to install at least one of each of these types of
targets: a gateway image, which is connected to your PC, and a node image, which is
the target. After you serially install the node image, you can unplug the serial
connection.
Over-the-air bootloading
Now that you have at least two nodes—one running the application bootloader sample
gateway image, and at least one other running the application bootloader sample
target node image—you can bootload the target nodes over the air.
1. Form the network. On the gateway, which is the coordinator, press BUTTON0,
which will allow joining for 60 seconds. On the target nodes, press BUTTON0,
which will try and join the network. The network is now up.
2. If you connect to the gateway node with a serial cable and the HyperTerminal
settings 19200, 8, N, 1, no flow control, you can press “A” and then Enter to
advertise the gateway service, which will set all necessary bindings.
3. Press “X” and then Enter to erase any old images in the download space, and set
the node up to receive the new image for bootloading.
5. In the Send File dialog, click Browse, and browse to the target node image. (The
example will only continue to work if you upload another image that has
application bootloader support. The only sample file that does is this target node
image. You may want to do something noticeable, like change the serial input
prompt).
6. Click Send. This will load the target node image to the download space on the
gateway node.
The application will then check the timestamp on the image in the download space,
and ask the target node for the timestamp of the image running there. If the timestamp
on the image in the download area is more recent than the timestamp of the image on
the target node, it will initiate an over-the-air bootload to upgrade the image.
The target node will receive the new image, check the CRC, and then reset into the
new image.
Writing an As you can see, this is just one way of performing an over-the-air bootload. The
Application with mechanism provided can perform many different methods. In particular, you could
Application create a user interface on a PC application, which can fully interpret your network
Bootloader Support traffic and understand the timestamp/versions of the node images on your network
devices. This application could also manage all of the new versions of this software,
and handle sending these different images to the gateway node (and then send them to
the specific target nodes) one by one.
• For API information, see the EmberZNet Stack API Guide and the Hardware
Abstraction Layer (HAL) API Guide for your microcontroller. Also refer to the
application bootloader sample code for examples of how to call these functions.
• Separating the update operation from the download operation makes it easier to
avoid the island problem—where one or more nodes are not updated before the
network switches to a new application. If the application has changed a lot, island
nodes may no longer be accessible through the wireless network and are difficult
to restore.
• When the node boots, the processor begins execution at the beginning of the
bootload area as controlled by the fuses. The application bootloader software
checks for a recovery signal. On the development board, this recovery signal is the
bootloader button. If the recovery signal exists during a reset, the bootloader
overwrites the original application with the Recovery Image. If the recovery signal
is not asserted, control passes to the application.
• The flash write routine minimizes memory wear by erasing each memory page only
one time, even though multiple segment writes are needed per page.
• There is some room for optimization, but be careful when trying to increase the
image transfer rate. For example, if you choose to have multiple segments in
flight, plan for page-based retries whenever a segment is lost. In addition, some
message types do not guarantee in-order delivery, so the destination node must
cache out-of-order segments.
Timing considerations
Bootloading using normal ZigBee messaging takes longer than the standalone
bootloader, which uses non-standard MAC timing and effectively precludes all other
traffic. Application bootloading permits other traffic to flow, and the separation of the
image transfer operation from the image update operation means that bootloading can
occur at the same time as normal network traffic.
Because the parent node must buffer messages for a sleeping child, it is important to
limit the rate of transfer for the new image so that the parent does not run out of
memory.
Obviously, this can negatively impact the performance of the bootload process, and it
may be just as easy to ensure that the node is stationary during bootload.
Sample Applications The application bootloader is an API for flash access. To use it, create an application
that receives the image and uses the API to save, validate, and install the image. For
examples of these steps, please see the following sample applications in
EmberStack/app/app-bootloader-demo/:
• bootloader-demo-node
• bootloader-demo-gateway
Setting Up the The Atmel ATmega processor, by default, is bootloaded using the standalone
Application bootloader. However, you can use the application bootloader to load software onto
Bootloader on an ATmega128 processors, but first you must set up the application bootloader and the
Atmel ATmega128 recovery image on the ATmega128 processors.
To set up the application bootloader on ATmega 128 processors, you need the following
components:
• An ISP device, such as the Kanda programmer or the JTAG ICE mkII.
• A program to drive the ISP that lets you disable auto-erase before programming.
• A development board, power supply, and RCM that already has its tokens set.
The application bootloader target image is one monolithic .hex file, and it includes the
entire contents you will need in flash in one file. This is the application bootloader
itself, as well as the stock recovery image. The .hex file contains the locations so that
these components go to the right places.
For older Ember Developer Kit nodes, you will need to use the dev0221 version.
Caution: Save your tokens in a safe place, or you might lose them.
3. Set the fuses that control Boot flash Section Size to 2048 bytes (set BOOTSZ=01).
After Reading This If you have questions or require assistance with the procedures described in this
Document document, please contact an Ember support representative at support@ember.com.
The information in this document is subject to change without notice. The statements,
configurations, technical data, and recommendations in this document are believed to be
accurate and reliable but are presented without express or implied warranty. Users must
take full responsibility for their applications of any products specified in this document. The
information in this document is the property of Ember Corporation.
Title, ownership, and all rights in copyrights, patents, trademarks, trade secrets and other
intellectual property rights in the Ember Proprietary Products and any copy, portion, or
modification thereof, shall not transfer to Purchaser or its customers and shall remain in
Ember and its licensors.
No source code rights are granted to Purchaser or its customers with respect to all Ember
Application Software. Purchaser agrees not to copy, modify, alter, translate, decompile,
disassemble, or reverse engineer the Ember Hardware (including without limitation any
embedded software) or attempt to disable any security devices or codes incorporated in the
Ember Hardware. Purchaser shall not alter, remove, or obscure any printed or displayed legal
notices contained on or in the Ember Hardware.
Ember, Ember Enabled, EmberZNet, InSight, and the Ember logo are trademarks of Ember
Corporation.