XBee 3 BLU provides blocks of flash memory that an application can read and write to. This memory provides a non-volatile data storage area that an application uses for many purposes. Some common uses of this data storage include:

  • Storing logged sensor data

  • Buffering firmware update data for a host microcontroller

  • Storing and retrieving data tables needed for calculations performed by a host microcontroller

The General Purpose Memory (GPM) is also used to store a firmware update file for over-the-air firmware updates of the device itself.

The usage of sleep during a GPM update is unsupported. Users are recommended to turn off sleep on the target device, perform the update, and then switch sleep back on to avoid data loss and increase the update speed.

Access General Purpose Flash Memory

To access the GPM of a target node locally or over-the-air, send commands to the MEMORY_ACCESS cluster ID (0x23) on the DIGI_DEVICE endpoint (0xE6) of the target node using Explicit Addressing Command Request API frames. For more information about them, see Explicit Addressing Command Request - 0x11.

To issue a GPM command, format the payload of an explicit API frame as follows:

Byte offset in payload Number of bytes Field name General field description

0

1

GPM_CMD_ID

Specific GPM commands are described in detail in the topics that follow.

1

1

GPM_OPTIONS

Command-specific options.

2

2*

GPM_BLOCK_NUM

The block number addressed in the GPM.

4

2*

GPM_START_INDEX

The byte index within the addressed GPM block.

6

2*

GPM_NUM_BYTES

The number of bytes in the GPM_DATA field, or in the case of a READ, the number of bytes requested.

8

varies

GPM_DATA

 

* Specify multi-byte parameters with big-endian byte ordering.

When a device sends a GPM command to another device via a unicast, the receiving device sends a unicast response back to the requesting device’s source endpoint specified in the request packet. It does not send a response for broadcast requests. If the source endpoint is set to the DIGI_DEVICE endpoint (0xE6) or Explicit API mode is enabled on the requesting device, then the requesting node outputs a GPM response as an explicit API RX indicator frame (assuming it has API mode enabled).

The format of the response is similar to the request packet:

Byte offset in payload Number of bytes Field name General field description

0

1

GPM_CMD_ID

This field is the same as the request field.

1

1

GPM_STATUS

Status indicating whether the command was successful.

2

2*

GPM_BLOCK_NUM

The block number addressed in the GPM.

4

2*

GPM_START_INDEX

The byte index within the addressed GPM block.

6

2*

GPM_NUM_BYTES

The number of bytes in the GPM_DATA field.

8

varies

GPM_DATA

 

* Specify multi-byte parameters with big-endian byte ordering.

General Purpose Flash Memory commands

The following commands interact with GPM.

PLATORM_INFO_REQUEST (0x00)

A PLATFORM_INFO_REQUEST frame can be sent to query details of the GPM structure.

Field name Command-specific description

GPM_CMD_ID

Should be set to PLATFORM_INFO_REQUEST (0x00).

GPM_OPTIONS

This field is unused for this command. Set to 0.

GPM_BLOCK_NUM

This field is unused for this command. Set to 0.

GPM_START_INDEX

This field is unused for this command. Set to 0.

GPM_NUM_BYTES

This field is unused for this command. Set to 0.

GPM_DATA

No data bytes should be specified for this command.

PLATFORM_INFO (0x80)

When a PLATFORM_INFO_REQUEST command request has been unicast to a node, that node sends a response in the following format to the source endpoint specified in the requesting frame.

Field name Command-specific description

GPM_CMD_ID

Should be set to PLATFORM_INFO (0x80).

GPM_STATUS

Indicates success if 0. Otherwise, an error occurred (see Possible Errors Returned from GPM Commands).

GPM_BLOCK_NUM

Indicates the number of GPM blocks available.

GPM_START_INDEX

Indicates the size, in bytes, of a GPM block.

GPM_NUM_BYTES

The number of bytes in the GPM_DATA field. For this command, this field will be set to 0.

GPM_DATA

No data bytes are specified for this command.

Example

A PLATFORM_INFO_REQUEST sent to a device with a serial number of 0x0013a200407402AC should be formatted as follows (spaces added to delineate fields):

  • 7E 001C 11 01 0013A200407402AC FFFE E6 E6 0023 C105 00 00 00 00 0000 0000 0000 24

Assuming all transmissions were successful, the following API packets would be output the source node’s serial interface:

  • 7E 0007 8B 01 FFFE 00 00 00 76

  • 7E 001A 91 0013A200407402AC FFFE E6 E6 0023 C105 C1 80 00 0077 0200 0000 EB

ERASE (0x01)

The ERASE command erases (writes all bits to binary 1) one or all of the GPM flash blocks. You can also use the ERASE command to erase all blocks of the GPM by setting the GPM_NUM_BYTES field to 0.

Field name Command-specific description

GPM_CMD_ID

Should be set to ERASE (0x01).

GPM_OPTIONS

There are currently no options defined for the ERASE command. Set this field to 0.

GPM_BLOCK_NUM

Set to the index of the GPM block that should be erased. When erasing all GPM blocks, this field is ignored (set to 0).

GPM_START_INDEX

The ERASE command only works on complete GPM blocks. The command cannot be used to erase part of a GPM block. For this reason GPM_START_INDEX is unused (set to 0).

GPM_NUM_BYTES

Setting GPM_NUM_BYTES to 0 has a special meaning. It indicates that every flash block in the GPM should be erased (not just the one specified with GPM_BLOCK_NUM). In all other cases, the GPM_NUM_BYTES field should be set to the GPM flash block size.

GPM_DATA

No data bytes are specified for this command.

ERASE_RESPONSE (0x81)

When an ERASE command request has been unicast to a node, that node sends a response in the following format to the source endpoint specified in the requesting frame.

Field name Command-specific description

GPM_CMD_ID

Should be set to ERASE_RESPONSE (0x81).

GPM_STATUS

Indicates success if 0. Otherwise, an error occurred (see Possible Errors Returned from GPM Commands).

GPM_BLOCK_NUM

Matches the parameter passed in the request frame.

GPM_START_INDEX

Matches the parameter passed in the request frame.

GPM_NUM_BYTES

The number of bytes in the GPM_DATA field. For this command, this field will be set to 0.

GPM_DATA

No data bytes are specified for this command.

Example

To erase flash block 42 of a target radio with serial number of 0x0013a200407402ac format an ERASE packet as follows (spaces added to delineate fields):

  • 7E 001C 11 01 0013A200407402AC FFFE E6 E6 0023 C105 00 C0 01 00 002A 0000 0200 37

Assuming all transmissions were successful, the following API packets would be output the source node’s serial interface:

  • 7E 0007 8B 01 FFFE 00 00 00 76

  • 7E 001A 91 0013A200407402AC FFFE E6 E6 0023 C105 C1 81 00 002A 0000 0000 39

WRITE (0x02) and ERASE_THEN_WRITE (0x03)

The WRITE command writes the specified bytes to the GPM location specified. Before writing bytes to a GPM block it is important that the bytes have been erased previously. The ERASE_THEN_WRITE command performs an ERASE of the entire GPM block specified with the GPM_BLOCK_NUM field prior to doing a WRITE. WRITE commands cannot index past the end of a GPM block boundary.

Field name Command-specific description

GPM_CMD_ID

Should be set to WRITE (0x02) or ERASE_THEN_WRITE (0x03).

GPM_OPTIONS

There are currently no options defined for this command. Set this field to 0.

GPM_BLOCK_NUM

Set to the index of the GPM block that should be written.

GPM_START_INDEX

Set to the byte index within the GPM block where the given data should be written.

GPM_NUM_BYTES

Set to the number of bytes specified in the GPM_DATA field.

Only one GPM block can be operated on per command. For this reason, GPM_START_INDEX + GPM_NUM_BYTES cannot be greater than the GPM block size. The number of bytes sent in an explicit API frame (including the GPM command fields) cannot exceed the maximum payload size of the device. The maximum payload size can be queried with the NP (Maximum Packet Payload Bytes) command.

GPM_DATA

The data to be written.

WRITE_RESPONSE (0x82) and ERASE_THEN_WRITE_RESPONSE (0x83)

When a WRITE or ERASE_THEN_WRITE command request has been unicast to a node, that node sends a response in the following format to the source endpoint specified in the requesting frame.

Field name Command-specific description

GPM_CMD_ID

Should be set to WRITE_RESPONSE (0x82) or ERASE_THEN_WRITE_RESPONSE (0x83)

GPM_STATUS

Indicates success if 0. Otherwise, an error occurred (see Possible Errors Returned from GPM Commands).

GPM_BLOCK_NUM

Matches the parameter passed in the request frame

GPM_START_INDEX

Matches the parameter passed in the request frame

GPM_NUM_BYTES

The number of bytes in the GPM_DATA field. For this command, this field will be set to 0

GPM_DATA

No data bytes are specified for these commands

Example

To write 15 bytes of incrementing data to flash block 22 of a target radio with serial number of 0x0013a200407402ac a WRITE packet should be formatted as follows (spaces added to delineate fields):

  • 7E 002B 11 01 0013A200407402AC FFFE E6 E6 0023 C105 00 C0 02 00 0016 0000 000F 0102030405060708090A0B0C0D0E0F C5

Assuming all transmissions were successful and that flash block 22 was previously erased, the following API packets would be output the source node’s serial interface:

  • 7E 0007 8B 01 FFFE 00 00 00 76

  • 7E 001A 91 0013A200407402AC FFFE E6 E6 0023 C105 C1 82 00 0016 0000 0000 4C

READ (0x04)

You can use the READ command to read the specified number of bytes from the GPM location specified. Data can be queried from only one GPM block per command.

Field name Command-specific description

GPM_CMD_ID

Should be set to READ (0x04).

GPM_OPTIONS

There are currently no options defined for this command. Set this field to 0.

GPM_BLOCK_NUM

Set to the index of the GPM block that should be read.

GPM_START_INDEX

Set to the byte index within the GPM block where the given data should be read.

GPM_NUM_BYTES

Set to the number of data bytes to be read. Only one GPM block can be operated on per command. For this reason, GPM_START_INDEX + GPM_NUM_BYTES cannot be greater than the GPM block size. The number of bytes sent in an explicit API frame (including the GPM command fields) cannot exceed the maximum payload size of the device. You can query the maximum payload size with the NP (Maximum Packet Payload Bytes) AT command.

GPM_DATA

No data bytes should be specified for this command.

READ_RESPONSE (0x84)

When a READ command request has been unicast to a node, that node sends a response in the following format to the source endpoint specified in the requesting frame.

Field name Command-specific description

GPM_CMD_ID

Should be set to READ_RESPONSE (0x84).

GPM_STATUS

Indicates success if 0. Otherwise, an error occurred (see Possible Errors Returned from GPM Commands).

GPM_BLOCK_NUM

Matches the parameter passed in the request frame.

GPM_START_INDEX

Matches the parameter passed in the request frame.

GPM_NUM_BYTES

The number of bytes in the GPM_DATA field.

GPM_DATA

The bytes read from the GPM block specified.

Example

To read 15 bytes of previously written data from flash block 22 of a target radio with serial number of 0x0013a200407402ac a READ packet should be formatted as follows (spaces added to delineate fields):

  • 7E 001C 11 01 0013A200407402AC FFFE E6 E6 0023 C105 00 C0 04 00 0016 0000 000F 3B

Assuming all transmissions were successful and that flash block 22 was previously written with incrementing data, the following API packets would be output the source node’s serial interface:

  • 7E 0007 8B 01 FFFE 00 00 00 76

  • 7E 0029 91 0013A200407402AC FFFE E6 E6 0023 C105 C1 84 00 0016 0000 000F 0102030405060708090A0B0C0D0E0F C3

FIRMWARE_VERIFY (0x05) and FIRMWARE_VERIFY_AND_INSTALL (0x06)

Use the FIRMWARE_VERIFY and FIRMWARE_VERIFY_AND_INSTALL commands when remotely updating firmware on a device. For more information about firmware updates, see Update the firmware over-the-air. These commands check if the GPM contains a valid over-the-air update file. For the FIRMWARE_VERIFY_AND_INSTALL command, if the GPM contains a valid firmware image, it will send a GPM response and then the device resets and begins using the new firmware.

Field name Command-specific description

GPM_CMD_ID

Should be set to FIRMWARE_VERIFY (0x05) or FIRMWARE_VERIFY_AND_INSTALL (0x06)

GPM_OPTIONS

Reserved. Set to 0.

GPM_BLOCK_NUM

This field is unused for this command. Set to 0.

GPM_START_INDEX

This field is unused for this command. Set to 0.

GPM_NUM_BYTES

This field is unused for this command. Set to 0.

GPM_DATA

This field is unused for this command

FIRMWARE_VERIFY_RESPONSE (0x85)

When a FIRMWARE_VERIFY command request has been unicast to a node, that node sends a response in the following format to the source endpoint specified in the requesting frame.

Field name Command-specific description

GPM_CMD_ID

Should be set to FIRMWARE_VERIFY_RESPONSE (0x85)

GPM_STATUS

Indicates success if 0. Otherwise, an error occurred (see Possible Errors Returned from GPM Commands).

GPM_BLOCK_NUM

This field is unused for this command. Set to 0.

GPM_START_INDEX

This field is unused for this command. Set to 0.

GPM_NUM_BYTES

This field is unused for this command. Set to 0.

GPM_DATA

This field is unused for this command

FIRMWARE_VERIFY_AND_INSTALL_RESPONSE (0x86)

When a FIRMWARE_VERIFY_AND_INSTALL command request has been unicast to a node, that node sends a response in the following format to the source endpoint specified in the requesting frame.

If the firmware image is valid, after that node sends the response the device will reset and begin using the new firmware.
Field name Command-specific description

GPM_CMD_ID

Should be set to FIRMWARE_VERIFY_AND_INSTALL_RESPONSE (0x86).

GPM_STATUS

Indicates success if 0. Otherwise, an error occurred (see Possible Errors Returned from GPM Commands).

GPM_BLOCK_NUM

This field is unused for this command. Set to 0.

GPM_START_INDEX

This field is unused for this command. Set to 0.

GPM_NUM_BYTES

This field is unused for this command. Set to 0.

GPM_DATA

This field is unused for this command.

Example

To verify a firmware image previously loaded into the GPM on a target device with serial number 0x0013a200407402ac, format a FIRMWARE_VERIFY packet as follows (spaces added to delineate fields):

  • 7E 001C 11 01 0013A200407402AC FFFE E6 E6 0023 C105 00 00 05 00 0000 0000 0000 1F

Assuming all transmissions were successful and that the firmware image previously loaded into the GPM is valid, the following API packets would be output the source node’s serial interface:

  • 7E 0007 8B 01 FFFE 00 00 00 76

  • 7E 001A 91 0013A200407402AC FFFE E6 E6 0023 C105 C1 85 00 0000 0000 0000 5F