XBee for Wi-SUN 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 can use 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.
Concurrent use of GPM and the filesystem (if supported) is prohibited as both methods share the same flash memory.

Access General Purpose Flash Memory

To access the GPM of a target node locally or over-the-air, send commands to the GPM_MEMORY_ACCESS cluster ID (0x23) of the target node using IPv6 XBee Services Request API frame. For more information, see IPv6 XBee Services Request - 0x19.

GPM frame operations can be initiated over RF, serially, or Bluetooth® Low Energy (if supported). The response will be routed back over the requesting interface.

To issue a GPM command, format the payload of the requesting 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_REQUEST, the number of bytes requested.

8

varies

GPM_DATA

The data to be written if applicable. Unused otherwise.

* 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. A transmission status frame should be output to indicate success or failure of the initial transmission request. If successful, a GPM response is sent back to the requesting device and output the requesting interface. It does not send a response for broadcast requests.

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

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

The data to be read if applicable. Unused otherwise.

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

General Purpose Flash Memory commands

The following commands interact with GPM.

[[0x00]] === 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.

[[0x08]] === PLATFORM_INFO_RESPONSE (0x80)

When a PLATFORM_INFO_REQUEST command 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_RESPONSE (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 transmitted to a device with an IPv6 address of fd:12::55:91:af:1a:f2:6d:dc:dc should be formatted as follows (spaces added to delineate fields):

  • 7E 001d 19 01 fd120000000000005591af1af26ddcdc 0023 00 00 00 0000 0000 0000 ed

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

  • 7E 0003 89 01 00 75

  • 7E 002f 9a fd120000000000009539994b4f714f00 fd120000000000005591af1af26ddcdc 0bee 0bee 00 00 80 00 0068 2000 0000 c6

[[0x01]] === ERASE_REQUEST (0x01)

The ERASE_REQUEST command erases (writes all bits to binary 1) one or all of the GPM flash blocks. You can also use the ERASE_REQUEST 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_REQUEST (0x01).

GPM_OPTIONS

There are currently no options defined for the ERASE_REQUEST 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_REQUEST 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.

[[0x81]] === ERASE_RESPONSE (0x81)

When an ERASE_REQUEST command 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 37 of a target radio with an IPv6 address of fd:12::55:91:af:1a:f2:6d:dc:dc, format an ERASE_REQUEST frame as follows (spaces added to delineate fields):

  • 7E 001d 19 01 fd120000000000005591af1af26ddcdc 0023 00 01 00 0025 0000 2000 a7

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

  • 7E 0003 89 01 00 75

  • 7E 002f 9a fd120000000000009539994b4f714f00 fd120000000000005591af1af26ddcdc 0bee 0bee 00 00 81 00 0025 0000 0000 28

[[0x02-0x03]] === WRITE_REQUEST (0x02) and ERASE_THEN_WRITE_REQUEST (0x03)

The WRITE_REQUEST 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_REQUEST command performs an ERASE_REQUEST of the entire GPM block specified with the GPM_BLOCK_NUM field prior to doing a WRITE_REQUEST. WRITE_REQUEST commands cannot index past the end of a GPM block boundary.

Field name Command-specific description

GPM_CMD_ID

Should be set to WRITE_REQUEST (0x02) or ERASE_THEN_WRITE_REQUEST (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 a request 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 (Max Packet Payload Bytes) command.

GPM_DATA

The data to be written.

[[0x82-0x83]] === WRITE_RESPONSE (0x82) and ERASE_THEN_WRITE_RESPONSE (0x83)

When a WRITE_REQUEST or ERASE_THEN_WRITE_REQUEST command 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 34 of a target radio with an IPv6 address of fd:12::55:91:af:1a:f2:6d:dc:dc, a WRITE_REQUEST frame should be formatted as follows (spaces added to delineate fields):

  • 7E 002c 19 01 fd120000000000005591af1af26ddcdc 0023 00 02 00 0022 007c 000f 010203040506070809101112131415 a2

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

  • 7E 0003 89 01 00 75

  • 7E 002f 9a fd120000000000009539994b4f714f00 fd120000000000005591af1af26ddcdc 0bee 0bee 00 00 82 00 0022 007c 0000 ae

[[0x04]] === READ_REQUEST (0x04)

You can use the READ_REQUEST 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_REQUEST (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 a response 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 (Max Packet Payload Bytes) AT command.

GPM_DATA

No data bytes should be specified for this command.

[[0x84]] === READ_RESPONSE (0x84)

When a READ_REQUEST command 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 34 of a target radio with an IPv6 address of fd:12::55:91:af:1a:f2:6d:dc:dc, a READ_REQUEST frame should be formatted as follows (spaces added to delineate fields):

  • 7E 001d 19 01 fd120000000000005591af1af26ddcdc 0023 00 04 00 0022 007c 000f 3c

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

  • 7E 0003 89 01 00 75

  • 7E 003e 9a fd120000000000009539994b4f714f00 fd120000000000005591af1af26ddcdc 0bee 0bee 00 00 84 00 0022 007c 000f 010203040506070809101112131415 01

[[0x05-0x06]] === FIRMWARE_VERIFY_REQUEST (0x05) and FIRMWARE_VERIFY_AND_INSTALL_REQUEST (0x06)

Use the FIRMWARE_VERIFY_REQUEST and FIRMWARE_VERIFY_AND_INSTALL_REQUEST 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 GPM contains a valid over-the-air update file. For the FIRMWARE_VERIFY_AND_INSTALL_REQUEST command, if 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_REQUEST (0x05) or FIRMWARE_VERIFY_AND_INSTALL_REQUEST (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

[[0x85]] === FIRMWARE_VERIFY_RESPONSE (0x85)

When a FIRMWARE_VERIFY_REQUEST command 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

[[0x86]] === FIRMWARE_VERIFY_AND_INSTALL_RESPONSE (0x86) When a FIRMWARE_VERIFY_AND_INSTALL_REQUEST command 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 an IPv6 address of fd:12::55:91:af:1a:f2:6d:dc:dc, format a FIRMWARE_VERIFY_REQUEST frame as follows (spaces added to delineate fields):

  • 7E 001d 19 01 fd120000000000005591af1af26ddcdc 0023 00 05 00 0000 0000 0000 e8

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

  • 7E 0003 89 01 00 75

  • 7E 002f 9a fd120000000000009539994b4f714f00 fd120000000000005591af1af26ddcdc 0bee 0bee 00 00 85 00 0000 0000 0000 49