Reducing RAM usage in EmberZNet PRO

How to reduce the RAM used by EmberZNet by reducing the memory available to the stack for certain functions. In some applications not all functions are necessary, or necessary to the same degree -- this how-to discusses which reductions are possible and what network behavior they affect.

Overview

This FAQ has been updated in respect to the EmberZNet 3.3 stack. However, most concepts should be application to future and past stacks as well. Also, although the configuration names here reference symbols in the EmberZNet API itself (used on the EM250), EZSP users can still benefit from this FAQ, since EZSP allows SetConfigurationValue overrides for these values. (Simply substitute EZSP_CONFIG_xxx in place of the EMBER_xxx name to get the EZSP configuration ID for that parameter.)

Configuration Header

The CONFIGURATION_HEADER preprocessor variable (modifying) points to a file that allows each application to reconfigure the behavior of the stack, especially as it relates to memory usage. The #define constants in this file override the default configurations at compile-time. We can learn about all available configuration options by reading the default configuration header file. The default configuration file can be found at:

<stack_home>/stack/config/ember-configuration-defaults.h

The rest of this article will discuss variables found in this file -- at this stage you may find it useful to browse the file yourself. All changes that you make should be made in the CONFIGURATION_HEADER file for your application and not in the default configuration file itself.

Options and RAM Usage

The values that will yield the biggest savings are: packet buffer count, neighbor table size, unicast message count, and discovery table size.

Packet Buffers : EMBER_PACKET_BUFFER_COUNT

This controls the number of packet buffers (represented in the code as EmberMessageBuffer structures). Packet Buffers are used by the stack to manage in-transit (routed), incoming, and outgoing messages, including messages being held for sleepy end device children and fragments of a fragmented message. It is important to have enough packet buffers to send and receive messages from the specific device and also to hold messages that are being relayed by the device. Packet buffers are also used to store temporary data used by the stack, such as information about currently joined mobile end devices, stored beacons being considered during a join/rejoin event, listings of conflicted node IDs, scan results, and matches for a ZDO End Device Bind request. In EZSP, packet buffers are also used to hold pending callback data that has not yet been conveyed to the host.

Please read the packet buffers how-to for a better understanding of packet buffers before you attempt to modify the number used in your application: while they do represent the largest savings opportunity, they are also one of the more complicated pieces of the network, so we recommend that you consider changing the other options first. Also, since packet buffers are used for other things besides message storage, the effects of running out of buffers during operation can manifest as more than just lost messages.

The default value of 24 is not significant; it's simply a moderately sized quantity of data that will store several messages and still fit comfortably in most of Ember's sample applications, since any spare RAM might as well be packet buffers. Each packet buffer eliminated recovers 40 bytes of RAM. Depending on the application and the network, you might well be able to reduce the number of buffers and not see any negative effects.

Neighbor Table : EMBER_NEIGHBOR_TABLE_SIZE

The neighbor table stores recent one-hop neighbors and is used in route formation. The default value of the neighbor table is 16, which means that each device is capable of remembering up to 16 of its neighbors. The stack will also handle high density networks where each node has more neighbors than will fit in the table, making intelligent judgments about which neighbors to keep in the table and which to discard. Note that the neighbor table entries are used as a list of potential next hops for routes being established, so routes to nodes not in the neighbor table require relaying through some other device; consequently, if the neighbor table size is reduced, it could lead to longer routes (and potentially higher latency as a result).

It is often easy for an application developer to specify or estimate the maximum number of neighbors that each device is likely to see in a deployed network, and the neighbor table size can be reduced accordingly. Each neighbor table entry eliminated will recover 18 bytes of RAM. We recommend that this value be at least 8. 16 is the maximum supported size. Note that end device children are tracked in the child table, not the neighbor table, so they do not impact this value.

Unicast Message Count: EMBER_UNICAST_MESSAGE_COUNT

The maximum number of APS unicast messages this device can have pending a MessageSentHandler callback.

This does not include routed messages, so this can often be safely reduced in applications that have low outgoing traffic requirements.

The default is 10 messages. Each item eliminated recovers 13 bytes of RAM.

Discovery Table : EMBER_DISCOVERY_TABLE_SIZE

The number of simultaneous route discoveries that a device will support. In many applications this can be well understood and its value can be reduced safely. In the case of a sensor device that only sends messages to the gateway, for example, this could be reduced all the way to 1.

The default is 8 and each item eliminated recovers 9 bytes of RAM.

Other considerations

End Device Children: EMBER_MAX_END_DEVICE_CHILDREN

In addition to the items above, it is also worthwhile to consider reducing the number of end device children supported, as this value impacts other RAM allocations in the system, such as:

• Unicast alarm data - EMBER_UNICAST_ALARM_DATA_SIZE bytes per child
• Child table - 4 bytes per child

Address Table Size: EMBER_ADDRESS_TABLE_SIZE

Each address table entry consumes 10 bytes of RAM. For applications relying primarily on the Binding Table (rather than the Address Table) to remember persistent destinations, reducing the address table size may be worthwhile.

Key Table Size: EMBER_KEY_TABLE_SIZE

Although the Link Key table is stored in non-volatile memory (tokens), each key entry requires maintaining an associated 32-bit frame counter value, which is 4 bytes apiece.

Summary

In general, the only reason to change default values is to INCREASE them. However, if your application requires more memory you can apply the information in this article //to get a better understanding of what memory is being used by the stack and what tradeoffs you might make by modifying these values.