Overview
ZigBee for S2C firmware includes support to update module firmware over-the-air. This feature allows a single device to update firmware on all other devices in the network. Over-the-air updates require 2 or 3 devices to perform the update. In this document, these devices are named as follows:
- Target: Device in the network whose firmware image is being updated.
- Updater: This device is 1-hop away from the Target device. The Updater receives the firmware image, either serially or over-the-air in the mesh network, and sends the image to the Target. The Updater can be multiple hops away from the Source.
- Source: This device receives the firmware image serially and transmits it to the Updater.
The Updater and Source can be the same device when the source is 1-hop away from a Target. The Source device must operate in API mode. Each Updater can only update one Target at a time. To update ‘n’ remotes at once, ‘n’ different Updater devices would be required.
At a high level, the OTA firmware update algorithm consists of 4 steps:
- Determine the 64-bit address of the “Target” device (device whose firmware will be updated)
- Determine the 64-bit address of the best neighbor to update firmware on the Target (“Updater”).
- Activate the bootloader on the Target device by sending AT%P with value of 0x5441 to the Target. The value causes a token to be written on the Target so when F/W update is completed, the Target will use the customer AT settings (not F/W default settings).
- Get the image with the Updater device who will then update the Target.
Firmware updates are performed by sending the entire contents of an
.ebl file to a remote device in the network. This process requires many transmissions and can take a few minutes to update a single remote. Acknowledgments to firmware update packets are sent out the UART as an API frame.
Contents
- Overview
- OTA Firmware Update Algorithm
- Step 1 - Source Configuration
- Step 2 - Verify the Target has good links to one or more neighbors
- Step 3 - Obtain the Updater radio
- Step 4 - Qualify the Neighbors
- Step 5 - Configure Addressing for the Update
- Step 6 - Query Target
- Step 7 - Do the OTA Update
- Step 8 - Finishing the Update
- Conclusion
- OTA Recovery Algorithm
- Appendix A – Frame Types
The following algorithm was used to test the ZigBee over-the-air update functionality using ZB 4x55 firmware. This algorithm assumes the list of Target devices has already been determined.
This algorithm assumes that the Source, Updater and Target nodes are S2C modules with ZigBee protocol.
After the network has been formed with all the devices, the first thing that is required to be done is to set
BD on the Source radio to a fast baud rate (115200 recommended) to speed up the upload.
Later on, read the addressing values of the Source radio (
SH and
SL) to, after the following steps are completed, be able to determine whether the Source and the Updater are the same radio or not.
There are two methods for retrieving the neighbor table list. The first, and possibly most effective, is the ZDO LQI request command. The second is the “one hop” Node Discovery. One or both of these approaches can be used to identify neighbors of the Target and to construct a list of good potential Updaters for the Target.
Below is the table defining the advantages and disadvantages of each:
| |
Advantages |
Disadvantages |
| ZDO LQI Request Command |
Returns the neighbors in the Target's neighbor table along with link queality information (LQI) |
The table is of finite size and may not show all neighbors if more neighbors exist than can fit in the table |
| One-hop Node Discovery |
Live snap shot of all neighbors |
Does not include any link quality information for any of the neighbors |
Here is the explanation of each method:
The application should send one or more
ZDO Neighbor Table requests (ZDO Mgmt_LQI_Request) to the Target device to query the contents of the Target’s neighbor table (Each LQI request will obtain up to 2 or 3 neighbors from the table). Each LQI request should include a unique transaction sequence number in order to filter duplicate response frames.
- Build a ZDO LQI Request
- Source and Destination endPoints = 0x00.
- ClusterID = 0x0031 (LQI Request cluster).
- ProfileID = 0x0000.
- Destination address (Long) = SH + SL of Target device.
- Destination address (Short) = MY of Target device.
- RF Data = [Transaction Sequence Number] + [Start Index]
- Transaction Sequence Num: 1 byte sequence number that will be included in the LQI response. The application should use this value to monitor for duplicate packets.
- Start Index: The starting index in the neighbor table of the Target. The LQI response will only return up to 2 or 3 neighbors per query.
LQI responses should be converted into an array of neighbors of the Target (64-bit and 16-bit addresses, and LQI values). Sort the array based on LQI with the highest values at the beginning of the list (best links first).
Ensure AO=1 on the Source device in order to receive parsed explicit frames. These are needed to properly identify incoming ZDO frames.
Alternatively, the application can issue a
one-hop Node Discovery to find all of the current neighbors of the Target. This approach can allow the application to discover additional devices besides those contained in the neighbor table.
A one-hop Node Discovery can be accomplished by having the source device send a remote command to the Target to issue the ATBH1 command, and apply changes.
After configuring the BH register, the Source should send a remote ATND command to the Target. This will send a node discovery broadcast command only to 1-hop neighbors. These neighbors will send their node discovery response back to the Source device. Responses from the 1-hop node discovery contain the addresses of each neighbor. These addresses can be compiled into a list of potential updaters.
Once the application has discovered at least one good neighbor, the Source should send several loopback transmissions to the Target to ensure a bi-directional route is created.
- To send a loopback transmission...
To create a
Loopback Transmission Frame, here are the specifications to follow:
- Generate an Explicit Addressing Command Frame (0x11) that should be sent from the Source radio to the possible Updater.
- Source and Destination endPoints = 0xE8.
- ClusterID = 0x0012 (loopback cluster).
- ProfileID = 0xC105.
- Destination address (Long) = SH + SL of neighbor.
- Destination address (Short) = MY of neighbor.
- RF Data = This field can contain a random payload.
- Send this frame 10 times to the neighbor. At least 9 out of the 10 loopback transmissions should have been successful.
After sending each transmission, a TX_Status (0x8B) should be received indicating that everything went fine (Delivery Status of 0x00) and an
Explicit Rx Indicator frame (0x91) should also be received by the Source radio. This last packet contains the following data among other stuff:
- Source and Destination endPoints = 0xE8.
- ClusterID = 0x0011.
- ProfileID = 0xC105.
For the S2B module, the following conditions should be verified before continuing with the process.
- Extra conditions for S2B...
Then, send a remote ATHV to the Target to read its hardware version. If the Target is an XBee (ATHV = 0x19xx), a remote #P command should be sent to the Target to determine the output power of the Target's bootloader when activated. The #P command returns the bootloader power configuration setting. XBee units manufactured before February 2008 have an incorrect power setting that cause the bootloader to transmit at a reduced output power level which may result in a loss of acknowledgment messages during the update. The #P command returns 2 bytes. The lower byte should be read to determine if a given Target has the reduced power setting. See the table below for details. (For example, if #P returns a value with bit1 cleared (0xFD, 0xFC, etc), the module has low bootloader output power. If the module returns a value with bit1 set (0xFF, 0x02, etc), the module bootloader has adequate output power.
ATHV = 0x19xx (XBee)
| #P response bytes |
Bootloader output power |
| 0bxxxx xx0x |
Low bootloader output power. Module is configured to use the alternate transmit path. Bootloader acknowledgments may not be received (Bootloader output power level may be around -40dBm) |
| 0bxxxx xx1x |
Good output power. Module will use the correct transmit path |
These methods present a problem, and it is that there is no verification of the Target radio being part of the route between the Source and the Updater. The question here is, what would happen if the type of network that we have is linear and the Target radio is part of the route between the best neighbor and the Source?
- With this method, the Target radio would go into Bootloader mode and the Updater could render unavailable to communicate with the Source. This means the OTA process would have to start over to select a new neighbor. But this is not all, the Target device is in Bootloader mode at this point, so, to verify the links again, the Target should be taken out of that mode. This adds a lot of complexity and a very big time overhead to the process.
The process implemented by XCTU is the one that uses the ZDO LQI Request method to obtain the best neighbors of the Target device
Once this is all done, what is left to do is verify the Link between the Updater node and the Target.
To qualify the Target’s neighbors, send 10 packets to the first neighbor in the list. At least 9 out of the 10 transmissions should be successful. If this is not the case with the first neighbor, try this process with the second one and so on.
- To send a loopback transmission...
To create a
Loopback Transmission Frame, here are the specifications to follow:
- Generate an Explicit Addressing Command Frame (0x11) that should be sent from the Source radio to the possible Updater.
- Source and Destination endPoints = 0xE8.
- ClusterID = 0x0012 (loopback cluster).
- ProfileID = 0xC105.
- Destination address (Long) = SH + SL of neighbor.
- Destination address (Short) = MY of neighbor.
- RF Data = This field can contain a random payload.
- Send this frame 10 times to the neighbor. At least 9 out of the 10 loopback transmissions should have been successful.
After sending each transmission, a TX_Status (0x8B) should be received indicating that everything went fine (Delivery Status of 0x00) and an
Explicit Rx Indicator frame (0x91) should also be received by the Source radio. This last packet contains the following data among other stuff:
- Source and Destination endPoints = 0xE8.
- ClusterID = 0x0011.
- ProfileID = 0xC105.
After qualifying the Target, the Source should send an
AT%P5441 to the Target to invoke the bootloader. The application should receive an AT command response with an OK status. After sending the %P response, the Target requires about 3 seconds to launch the bootloader. An over-the-air updater application should delay for 3 seconds after receiving the %P response before attempting to update the Target.
Disable Explicit frames processing on the Source device. To do so, set
AO command to 0x00.
- If the Source is the Updater:
- Issue a %U command on the Target device remotely from the Source with the value 0x0 to get that device out of any other recovery process it is part of.
- Set the DH and DL commands on the Source to the 64-bit address of the Target.
- The Source should send the query and file upload to cluster ID 0x71FE (Steps 6-7).
- If the Source is not the Updater:
- Issue a %U command on the Target device remotely from the Source with the value 0x0 to get that device out of any other recovery process it is part of.
- Set the DH and DL commands on the Updater to the 64-bit address of the Target, using remote commands.
- The Source should send the query and file upload to cluster ID 0x71FF (Steps 6-7).
After configuring addressing on the Updater, changes must be applied (
AC command).
Send an XModem query to the Target. This way it will know the OTA process is about to start.
- Here is how an XModem query can be built:
The following parameters must be set in an Explicit API Transmit frame (0x11):
- Source and Destination endPoints = 0xE8.
- ClusterID = 0x71FE if Source is the same radio as the Updater and 0x71FF if not.
- ProfileID = 0xC105.
- Destination address (Long) = SH + SL of Updater device.
- Destination address (Short) = MY of Updater device.
- RF Data = 2 bytes formatted as (0x01, 0x51).
The Source device should receive an
Over-the-Air Firmware Update Status frame (0xA0) with a status of 0x52 (Success). The Block Number reported by this frame should be 0x00. This frame also includes the 64-bit address of the Target device, so it should also be verified.
At this point, the Target radio is in Bootloader mode, and there are only a few things that can be done with it:
- The Target radio can receive as many XModem Queries as the user wants. All of them are going to be responded with a 0xAO frame with 0x52 status, as commented in the line above.
- If the user chooses to send an End of Transmission (EOT) frame to the Target radio with the purpose of getting it out of Bootloader mode, that is not going to work. Every EOT frame received by the Target before having received any block of firmware will be responded with a 0xAO frame of 0x40 status (No MAC ACK). This means that the only way to return the Target radio to its original state (before the Update process started when it was using the previous firmware)is to hard reset it.
- If during the firmware transmission the process is stopped unexpectedly (communication is interrupted or simply the user decides the OTA process should stop), an EOT frame can be sent to the Target. The only thing this will do is make the Target wait for an XModem query again. The problem wit this situation is that, once the firmware transmission started, there is no way to go back to the previous version installed in the module. This step would only be used to restart the OTA process.
- If, after 60 seconds, the Target radio does not receive any frame, it will start waiting for the XModem query again.
If, by any chance, the process fails before sending any firmware blocks, try sending the XModem query a couple of times more, as said above. If it still continues failing, get the go back to Step 3 and select a new updater. Qualify it against the Source and Continue on Step 6 (It cannot be qualified against the Target because it is in Bootloader mode).
The time the Source device must wait for the responses of the Target radio while it is in Bootloader mode should not exceed 5 seconds. This is especially compulsory for the Recovery process,but should be applied to any OTA packet transmission as well.
Once the query has succeeded, the
ebl file must be sent in order, as
64-byte blocks.
The payload of the Explicit Transmit frames (0x11) sent in a firmware update process are formatted as follows:
[XModem SOH command value] + [Block Number] + [64-byte firmware image block]
- The XModem SOH command value is 0x01.
- The Block Number is a single byte that should start with 0x01 and be incremented for each consecutive 64- byte block (0x01 is the starting point because Block Number 0x00 was reserved for the XModem query of step 6).
- The 64-byte firmware image block consists of 64-bytes from the .ebl file. These must be sent in order, parsing the binary ebl file from start to finish.
Firmware updates are sent similar to the XModem query (same cluster ID, destination address, and endpoint), but the data payload always consists of 66 bytes as described above.
After sending a firmware update packet, the Source will receive an Over-the-Air Firmware Update Status frame (0xA0) with a status of 0x52 (Success). If a different status is received, the Source can resend the previous frame with the same Block Number. At this point, all the frames can be sent with frame ID of 0x0 so no API TX statuses are received and there is not so much congestion.
If multiple retries fail, the source could return to Step 3 to select a different updater. Once a new updater is selected, the Source can send the query message and update the Target again through the new Updater.
Once the entire ebl image has been sent, the Source must transmit an XModem
End of Transmission (EOT) frame to the Target (through the Updater). The EOT is sent similar to the XModem query (Step 6), using the same cluster ID, endpoint, and destination address (same Updater). The payload is 2 bytes formatted as (0x01, 0x04).
Again, an Over-the-Air Firmware Update Status frame (0xA0) with a status of 0x06 (ACK) should be received.
After sending the EOT, the Target should resume operation and rejoin the network. This is true in both secure (EE=1) and insecure(EE=0) networks.
A typical OTA update over 3-4 hops at 115.2 kbps baud rate can take anywhere from 3-5 minutes (possibly more) depending on the environment.
For starters, this will be very simple, as the process for triggering the OTA recovery is very basic. All it is needed to be done is perform a reset on the Target device during the OTA Firmware Update process.
To recreate an OTA Recovery process, start the OTA Update process normally. Once in Step 7 (Do the OTA Update), and when a certain percent of the update has taken place, do a hardware reset on the Target device (radio being updated). The block that was sent during this interruption will never get to the Target radio and no ACK will be received by the Source, so a new transmission with the same block will be sent again to the Target with unsuccessful results. After a total of 3 retries, as no successful transmission will have occurred because of the reset, the Target will default to recovery mode on it's own. The default channel for this operation will be channel 13 (0xD), and the Target will wait for a Query broadcast request.
The next step is that the Source device must send a
%U remote AT command (Query broadcast request) to the Updater node. The value this command must be set to is the 64-bit address of the Target device. Once the %U command has been sent, an Over-the-Air Firmware Update Status frame (0xA0) with a query response status of 0x52 (Success) must be received. Retry several times if this process fails.
Right after the response has been received the OTA Update process must start again (Step 7). This time, the XModem Query should not be sent as the %U acts as if query request had been sent with the Block Number 0x00.
After that, the whole OTA Update process should work correctly, and if it fails again, the Recovery process should be repeated.
Ensure AO=1 on the API device in order to receive explicit receive frames. These are needed to properly identify incoming ZDO frames.
Cluster ID: 0x0031
Endpoint: 0x00
Profile ID: 0x0000
API Data Payload: [Transaction Sequence Number] + [Start Index]
- Trans Sequence Num: 1 byte sequence number that will be included in the LQI response. The application should use this value to monitor for duplicate packets.
- Start Index: The starting index in the neighbor table of the Target. The LQI response will only return up to 2 or 3 neighbors per query.
Cluster ID: 0x8031
Endpoint: 0x00
Profile ID: 0x0000
API Data Payload: [Transaction Sequence Number] + [Status] + [Neighbor Table Entries] + [Start Index] + [Neighbor Table List Count] + [Neighbor Table List]
- Trans Seq Num: 1 byte sequence number that matches the transaction sequence number sent in the request.
- Status: 1 byte status value. 0=success, or NOT_SUPPORTED.
- Neighbor Table Entries: 1 byte - Total number of entries in the remote’s neighbor table.
- Start Index: 1 byte - Starting index within the NT to begin reporting neighbors.
- Neighbor Table List Count: 1 byte - Number of NT entries in the following list.
- Neighbor Table List: List of neighbors (see NT Record definition below).
[Extended PAN ID] + [Extended Address] + [Network Address] + [Bitmask 1] + [Bitmask 2] + [Depth] + [LQI]
- Extended PAN ID : 8 byte extended PAN ID value, little endian byte-order.
- Extended Address: 8 byte address, unique to each device.
- Network Address: 2 byte address, assigned during joining.
- Bitmask 1: [Reserved] + [Relationship] + [RxOnWhenIdle] + [Device Type]
- Reserved: most significant bit (0b1000 0000)
- Relationship: bits 4-6 (0b0111 0000)
- 0x0 – neighbor is parent
- 0x01 – neighbor is child
- 0x02 – neighbor is sibling
- 0x03 – none of the above
- 0x04 – previous child
- RxOnWhenIdle: bits 2-3 (0b0000 1100)
- 0x0 – Receiver is off when idle
- 0x1 – Receiver is on when idle
- 0x2 – Unknown
- Device Type: least significant bits 0-1 (0b0000 0011)
- 0x0 – ZigBee coordinator
- 0x1 – ZigBee router
- 0x2 – ZigBee end device
- 0x3 – Unknown
- Bitmask 2: [Reserved] + [Permit Joining]
- Reserved: most significant 6 bits (0b1111 1100)
- Permit Joining: least significant bits 0-1 (0b0000 0011)
- 0x0 – Neighbor not accepting join requests
- 0x1 – Neighbor accepting join requests
- 0x2 – Unknown
- Depth: 1 byte tree depth.
- LQI: Estimate link quality for RF transmissions from this device. Higher values indicate a better link (0xFF is better than 0xE0).
[0x01] + [0x51]
[0x01] + [0x04]
- See the original doc file...
XBee ZB Over-the-Air Firmware Updates
Overview
XBee ZB firmware includes support to update module firmware over-the-air. This feature allows a single device to update firmware on all other devices in the network. Over-the-air updates require 2 or 3 devices to perform the update. In this document, these devices are named as follows:
- Target: This is the device in the network whose firmware image is being updated.
- Uploader: This device is 1-hop away from the target device. The updater receives the firmware image, either serially or over-the-air in the mesh network, and sends the image to the target. The uploader can be multiple hops away from the source.
- Source: This device receives the firmware image serially and transmits it to the uploader.
The uploader and source can be the same device when the source is 1-hop away from a target. The source device must support the API (i.e. API coordinator, API router). Each updater can only update one target at a time. To update ‘n’ remotes at once, ‘n’ different updater devices would be required.
At a high level, the OTA firmware update algorithm consists of 4 steps:
- Determine the 64-bit address of the “target” device (device whose firmware will be updated)
- Determine the 64-bit address of the best neighbor to update firmware on the target (“updater”).
- Activate the bootloader on the target device
- Send the image to the updater device who will then update the image on the target.
Firmware updates are performed by sending the entire contents of an .ebl file to a remote device in the network. This process requires many transmissions and can require a few minutes to update a single remote. Acknowledgments to firmware update packets are sent out the UART as an API frame, in both AT and API firmware.
Over-the-Air Update Tools
Digi has developed over-the-air firmware update capability in some of its existing tools. Users are encouraged to use existing tools to perform firmware updates when possible. The following tools support over-the-air firmware updates.
-
X-CTU Modem Configuration and Test Utility (software)
-
Digi XBee Network Assistant
-
Digi Remote Manager (when used in conjunction with
Digi XBee® Industrial Gateway)
Firmware Update Algorithm
The following algorithm was used to test the ZB over-the-air update functionality using ZB 2x21 firmware. This algorithm assumes the list of target devices has already been determined.
Step 1 – Source Configuration
Set AO on the API source to 1 to enable explicit receive frames. Set BD on the source to a fast baud rate (115200 recommended) to speed up the upload. Read the SL value of the source. This will be used later to determine if the source is the same as the selected updater.
Step 2 – Verify the target has good links to one or more neighbors
There are two methods for retrieving the neighbor table list. The first, and possibly most effective, is the ZDO LQI request command. The second is the “one hop” Node Discovery. One or both of these approaches can be used to identify neighbors of the target and to construct a list of good potential updaters for the target.
Below is a table defining the advantages and disadvantages of each.
| |
Advantages |
Disadvantages |
| ZDO LQI Request Command |
Returns the neighbors in the target’s neighbor table along with link quality information (LQI) |
The table is of finite size and may not show all neighbors if more neighbors exist than can fit in the table. |
| One-hop Node Discovery |
Live snap shot of ALL neighbors |
Does not include any link quality information for any of the neighbors |
Neighbor Table Request -
The application should send one or more ZDO Neighbor Table requests (ZDO Mgmt_LQI_Request) to the target device to query the contents of the target’s neighbor table. (Each LQI request will obtain up to 2 or 3 neighbors from the table.) Each LQI request should include a unique transaction sequence number in order to filter duplicate response frames. (See Appendix A for frame construction of a ZDO LQI Request.)
LQI responses should be converted into an array of target neighbors (64-bit and 16-bit addresses, and LQI values). Sort the array based on LQI with the highest values at the beginning of the list (best links first).
One-hop Node Discovery
Alternatively, the application can issue a one-hop Node Discovery to find all of the target’s current neighbors. This approach can allow the application to discover additional devices besides those contained in the neighbor table.
A one-hop Node Discovery can be accomplished by having the source device send a remote command to the target to issue the ATBH1 command, and apply changes. After configuring the BH register, the source should send a remote ATND command to the target. This will send a node discovery broadcast command only to 1-hop neighbors. These neighbors will send their node discovery response back to the source device. Responses from the 1-hop node discovery contain the addresses of each neighbor. These addresses can be compiled into a list of potential updaters.
Step 3 – Qualify the Target
Once the application has discovered at least one good neighbor, the source should send several loopback transmissions to the target to ensure a bi-directional route is created. (Software loopback transmissions can be sent using the Explicit API transmit frame (0x11), setting the cluster ID to 0x0012 and the profile ID to 0xC105.)
Then, send a remote ATHV to the target to read its hardware version. If the target is an XBee (ATHV = 0x19xx), a remote #P command should be sent to the target to determine the output power of the target’s bootloader when activated. The #P command returns the bootloader power configuration setting. XBee units manufactured before February 2008 have an incorrect power setting that cause the bootloader to transmit at a reduced output power level which may result in a loss of acknowledgment messages during the update. The #P command returns 2 bytes. The lower byte should be read to determine if a given target has the reduced power setting. See the table below for details. (For example, if #P returns a value with bit1 cleared (0xFD, 0xFC, etc), the module has low bootloader output power. If the module returns a value with bit1 set (0xFF, 0x02, etc), the module bootloader has adequate output power.
ATHV = 0x19xx (XBee)
| #P response bytes |
Bootloader output power |
| 0bxxxx xx0x |
Low bootloader output power. Module is configured to use the alternate transmit path. Bootloader acknowledgments may not be received. (Bootloader output power level may be around -40dBm.) |
| 0bxxxx xx1x |
Good output power. Module will use the correct transmit path |
After qualifying the target, the source should send an AT%P5441 to the target to invoke the bootloader. The application should receive an AT command response with an OK status. After sending the %P response, the target requires about 3 seconds to launch the bootloader. An over-the-air updater application should delay for 3 seconds after receiving the %P response before attempting to update the target.
Step 4 – Qualify the Neighbors
To qualify the target’s neighbors, send 10 packets to the first neighbor in the list. These packets should be addressed to the loopback cluster ID (0x0012) in profile ID 0xC105. The loopback will be received on cluster ID (0x0011). Ensure at least 9 of 10 loopback responses are received. If less than 9 are received, assume a good route could not be established and repeat with the next neighbor in the list.
Step 5 – Configure Addressing for the Update
Determine if the selected updater is the source or not by comparing the updater’s 64-bit address with the SL value read from the source.
If the source is the updater :
- Set the DH and DL commands on the source to the 64-bit address of the target.
- The source should send the query and file upload to cluster ID 0x71FE. (Steps 6-7)
If the source is not the updater :
- Set the DH and DL commands on the updater to the 64-bit address of the target, using remote commands.
- The source should send the query and file upload to cluster ID 0x71FF. (Steps 6-7)
After configuring addressing on the updater, changes must be applied for the addressing changes to work. This can be done by sending a remote AC command to the updater after setting DH and DL.
Step 6 – Query Target
Send an XModem query to the target. To construct the query message, the Explicit API transmit frame (type 0x11) should be addressed to the 64-bit address of the updater. The Cluster ID should be 0x71FE if the source is the updater, or 0x71FF if the source is not the updater. The endpoint should be set to 0xE8, and the payload should contain 2 bytes (0x01 0x51).
The source should receive an API response in an Explicit Rx frame (0x91) with the cluster ID = 0xF1FF and the endpoint = 0xE8. (The AO command on the source should be set to 1 as described in step 1.) The data payload in the response should be parsed to determine if the query succeeded. A successful query returns a query response type (0x52). Once the target has sent a query response, if it receives additional queries before an upload begins, the target may respond with a NACK status (0x15).
If this fails (possibly retry), and if the bootloader output power is expected to be low (see Step 3, #P command), the XBee receiver should operate correctly and the update should work. However, the source may not receive any acknowledgments. If an application must update a target with low bootloader output power, since acknowledgments may not be received, the application might be written to transmit each over-the-air update packet twice, to ensure they are all received correctly. If possible, the updater should be placed a couple feet from the target to improve the link.
If the bootloader output power was determined to be good (from Step 3), and the query fails, the application could return to Step 4, this time selecingt the next router in the neighbor list. The application could try sending a query to the target through a couple different updaters. (Recall that once the target receives a query, it might send a NACK response to any other query messages received before the update begins. If a NACK status (0x15) is received in response to a query message, the application should continue as though a query response was received.)
Alternatively, if the query fails, the source could send an end of transmission frame to the target to launch the existing application. If there is any doubt about the successful delivery of the query message, or the reliability of the link, the application can send an end of transmission (EOT) frame to recover the target as long as the firmware image has not been sent. See step 8 for information on how to construct the EOT packet.
Step 7 – Do the OTA Update
Once the query has succeeded, the ebl file must be sent in order, as 64-byte blocks.
Firmware updates are formatted as:
[Bootloader Version] + [Block Number] + [64-byte firmware image block]
- The bootloader version is 0x01.
- The block number is a single byte that should start with 0x01 and be incremented for each consecutive 64- byte block.
- The 64-byte firmware image block consists of 64-bytes from the .ebl file. These must be sent in order, parsing the binary ebl file from start to finish.
Firmware updates are sent similar to the XModem query (same cluster ID, destination address, and endpoint), but the data payload always consists of 66 bytes as described above.
After sending a firmware update packet, the source will receive an API Rx Explicit indicator with the cluster ID = 0xF1FF and endpoint = 0xE8. The source should verify the status is set to 0x06 (Ack). If a different status is received, the source can resend the previous frame with the same block number.
If multiple retries fail, the source could return to Step 4 to select a different updater. Once a new updater is selected (Step 4 and 5), the source can send the query message and update the target again through the new updater.
Step 8 – Finishing the Update
Once the entire ebl image has been sent, the source must transmit an XModem end of transmission (EOT) frame to the target (through the updater). The EOT is sent similar to the query, using the same cluster ID, endpoint, and destination address (same updater). The payload is 2 bytes formatted as (0x01, 0x04).
Conclusion
After sending the EOT, the remote should resume operation and rejoin the network. This is true in both secure (EE=1) and unsecure (EE=0) networks.
A typical OTA update over 3-4 hops at 115.2 kbps baud rate can take anywhere from 3-5 minutes (possibly more) depending on the environment.
Appendix A – Frame Types
** Note: Ensure AO=1 on the API device in order to receive explicit receive frames. These are needed to properly identify incoming ZDO frames.
ZDO LQI Request Command (ZigBee spec r17, Section 2.4.3.3.2)
Cluster ID: 0x0031
Endpoint: 0x00
Profile ID: 0x0000
API Data Payload: [Transaction Sequence Number] + [Start Index]
- Trans Sequence Num: 1 byte sequence number that will be included in the LQI response. The application should use this value to monitor for duplicate packets.
- Start Index: The starting index in the neighbor table of the target. The LQI response will only return up to 2 or 3 neighbors per query.
ZDO LQI Response (ZigBee spec r17, Section 2.4.4.3.2)
Cluster ID: 0x8031
Endpoint: 0x00
Profile ID: 0x0000
API Data Payload: [Transaction Sequence Number] + [Status] + [Neighbor Table Entries] + [Start Index] + [Neighbor Table List Count] + [Neighbor Table List]
- Trans Seq Num: 1 byte sequence number that matches the transaction sequence number sent in the request.
- Status: 1 byte status value. 0=success, or NOT_SUPPORTED.
- Neighbor Table Entries: 1 byte - Total number of entries in the remote’s neighbor table.
- Start Index: 1 byte - Starting index within the NT to begin reporting neighbors.
- Neighbor Table List Count: 1 byte - Number of NT entries in the following list.
- Neighbor Table List: List of neighbors (see NT Record definition below).
Neighbor Table Record Type
[Extended PAN ID] + [Extended Address] + [Network Address] + [Bitmask 1] + [Bitmask 2] + [Depth] + [LQI]
- Extended PAN ID : 8 byte extended PAN ID value, little endian byte-order.
- Extended Address: 8 byte address, unique to each device.
- Network Address: 2 byte address, assigned during joining.
- Bitmask 1: [Reserved] + [Relationship] + [RxOnWhenIdle] + [Device Type]
- Reserved: most significant bit (0b1000 0000)
- Relationship: bits 4-6 (0b0111 0000)
- 0x0 – neighbor is parent
- 0x01 – neighbor is child
- 0x02 – neighbor is sibling
- 0x03 – none of the above
- 0x04 – previous child
- RxOnWhenIdle: bits 2-3 (0b0000 1100)
- 0x0 – Receiver is off when idle
- 0x1 – Receiver is on when idle
- 0x2 – Unknown
- Device Type: least significant bits 0-1 (0b0000 0011)
- 0x0 – ZigBee coordinator
- 0x1 – ZigBee router
- 0x2 – ZigBee end device
- 0x3 – Unknown
- Bitmask 2: [Reserved] + [Permit Joining]
- Reserved: most significant 6 bits (0b1111 1100)
- Permit Joining: least significant bits 0-1 (0b0000 0011)
- 0x0 – Neighbor not accepting join requests
- 0x1 – Neighbor accepting join requests
- 0x2 – Unknown
- Depth: 1 byte tree depth.
- LQI: Estimate link quality for RF transmissions from this device. Higher values indicate a better link (0xFF is better than 0xE0).
XModem Query Message
[0x01] + [0x51]
XModem End of Transmission Message
[0x01] + [0x04]
Last updated:
Jan 01, 2024