Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

RemoTI-1.4.0-Network Processor Developers Guide

From Texas Instruments Wiki
Jump to: navigation, search

Acronyms and Definitions

ADC 
Analog-to-Digital Converter
AES 
Advanced Encryption Standard
API 
Application Programming Interface
ARC 
Advance Remote Control
bps 
bits per second
CCM 
Counter with CBC-MAC (CCM), a mode of operation for cryptographic block ciphers
CDC 
Communications Device Class
CERC 
Consumer Electronics Remote Control, name of a profile of Zigbee RF4CE (now ZRC)
DCE 
Data Circuit-terminating Equipment
DMA 
Direct Memory Access
DTE 
Data Terminal Equipment
GPIO 
General Purpose Input Output
HAL 
Hardware Abstraction Layer
I2C 
Inter-Integrated Circuit
IAR 
IAR Systems, a software development tool vendor
IDATA 
Internal Data memory
IEEE 
Institute of Electrical & Electronics Engineers, Inc.
IO 
Input Output
ISR 
Interrupt Service Routine
LED 
Light Emitting Diode
NIB 
Network Information Base
NV 
Non-Volatile, or Non-volatile memory
NWK 
Network
OSAL 
Operating System Abstraction Layer
RXD 
Receive Data line
SOP 
Start Of Packet
SPI 
Serial Peripheral Interface
SRAM 
Static Random Access Memory
TI 
Texas Instruments Incorporated
TXD 
Transmit Data line
UART 
Universal Asynchronous Receiver-Transmitter
USB 
Universal Serial Bus
XDATA 
External Data Memory
Zigbee 
RF4CE An 802.15.4 based remote control protocol standard
ZRC 
Zigbee Remote Control, a name for a ZigBee RF4CE profile

References

  1. RemoTI Developer’s Guide, SWRU198, http://www.ti.com/lit/swru198
  2. RemoTI API, SWRA268, can be found in the installation folder of RemoTI
  3. HAL Drivers API, SWRA193, can be found in the installation folder of RemoTI
  4. OSAL API, SWRA194, can be found in the installation folder of RemoTI
  5. CC253X System-on-Chip Solution for 2.4-GHz IEEE 802.15.4/ZigBee/RF4CE User’s Guide, SWRU191, http://www.ti.com/lit/swru191
  6. RemoTI Sample Applications User’s Guide, SWRU201, can be found in the installation folder of RemoTI
  7. RemoTI Network Processor Interface Specification, SWRA271, can be found in the installation folder of RemoTI
  8. RemoTI Host Processor Sample Application and Porting Guide, SWRA259, http://www.ti.com/lit/swra259

Introduction

Purpose

This page explains the RemoTI network processor application and topics related to customizing the application to add custom command set.

Scope

This page describes concepts and settings for the Texas Instruments RemoTI Release with respect to network processor development.

As to the general concept of Zigbee RF4CE and RemoTI architecture, please refer to [1].

RemoTI Network Processor Application

The RemoTI development kit includes the network processor application. This chapter describes the features of the network processor application and the organization of the source code and project files.

Features

The following summarize the features of the RemoTI network processor application:

  • Compliance with Zigbee RF4CE network layer specification, a device can be configured either as an originator or as a recipient node.
  • Zigbee RF4CE network layer security
  • 115200bps baud rate UART connectivity with two pin configuration (TXD, RXD)
    • 57600bps and 230400bps alternative baud rate for UART connection with code modification instruction. Note that host processor emulation tools (PC tools) included in the development kit does not support the alternative baud rates.
  • Configurable to SPI (up to 4 Mhz). Note that host processor emulation tools (PC tools) included in the development kit does not support SPI.
  • Wakeup on UART protocol
  • Optional serial boot loader downloading demo
  • Full speed USB CDC support for CC2531 USB dongle

Build configurations

RemoTI network processor application project is located in the Projects\RemoTI\RNP\CC253x folder of the RemoTI software installation. There are 2 workspaces defined in this folder, please select the one corresponding to your target device type (CC2533 or CC2531).

When you open the workspace file (rnp_cc2533.eww as an example), you can select different project configurations as in Figure 1.

Figure 1: IAR project configuration selection

Each configuration is explained in Table 1:

CC253x Project configurations

Configuration Description
CC2533F64-Originator Configuration for CC2533F64 part, Originator Functionality, UART interface.
CC2533F64-Recipient Configuration for CC2533F64 part, Recipient Functionality, UART interface.
CC2533F64-Originator_HEX Configuration for CC2533F64 part, Originator Functionality, UART interface with serial boot loader – HEX file
CC2533F64-Originator_SBL Configuration for CC2533F64 part, Originator Functionality, UART interface for serial boot loader downloading
CC2533F64-Originator_SPI Configuration for CC2533F64 part, Originator Functionality, SPI interface.
CC2533F64-Recipient_SPI Configuration for CC2533F64 part, Recipient Functionality, SPI interface.
CC2533F64-Originator_SPI_HEX Configuration for CC2533F64 part, Originator Functionality, SPI interface with serial boot loader – HEX file
CC2533F64-Originator_SPI_SBL Configuration for CC2533F64 part, Originator Functionality, SPI interface for serial boot loader downloading
CC2533F96-Originator Configuration for CC2533F96 part, Originator Functionality, UART interface.
CC2533F96-Recipient Configuration for CC2533F96 part, Recipient Functionality, UART interface.
CC2533F96-Originator_HEX Configuration for CC2533F96 part, Originator Functionality, UART interface with serial boot loader – HEX file
CC2533F96- Recipient _HEX Configuration for CC2533F96 part, Recipient Functionality, UART interface with serial boot loader – HEX file
CC2533F96-Originator_SBL Configuration for CC2533F96 part, Originator Functionality, UART interface for serial boot loader downloading
CC2533F96- Recipient _SBL Configuration for CC2533F96 part, Recipient Functionality, UART interface for serial boot loader downloading
CC2533F96-Originator_SPI Configuration for CC2533F96 part, Originator Functionality, SPI interface.
CC2533F96-Recipient_SPI Configuration for CC2533F96 part, Recipient Functionality, SPI interface.
CC2533F96-Originator_SPI_HEX Configuration for CC2533F96 part, Originator Functionality, SPI interface with serial boot loader – HEX file
CC2533F96-Recipient_SPI_HEX Configuration for CC2533F96 part, Recipient Functionality, SPI interface with serial boot loader – HEX file
CC2533F96-Originator_SPI_SBL Configuration for CC2533F96 part, Originator Functionality, SPI interface for serial boot loader downloading
CC2533F96-Recipient_SPI_SBL Configuration for CC2533F96 part, Recipient Functionality, SPI interface for serial boot loader downloading

Configurations in rnp_cc2531.eww workspace

CC2531 Project configurations
Configuration Description
CC2531F256-Originator Configuration for CC2531F256 USB dongle platform – CDC interface, Originator Functionality
CC2531F256-Recipient Configuration for CC2531F256 USB dongle platform – CDC interface, Recipient Functionality
CC2531F256-Originator_HEX Configuration for CC2531F256 USB dongle platform hex file generation – CDC interface, Originator Functionality
CC2531F256-Recipient_HEX Configuration for CC2531F256 USB dongle platform hex file generation – CDC interface, Recipient Functionality
CC2531F256-Originator_SBL Configuration for CC2531F256 image for serial boot loader downloading – CDC interface, Originator Functionality
CC2531F256-Recipient_SBL Configuration for CC2531F256 image for serial boot loader downloading – CDC interface, Recipient Functionality

The project option settings for each configuration, such as defined symbols (also known as compile flags) preprocessor, are set to work for the particular configuration.

Table 2 explains compile flags (preprocessor defined symbols) used in the project configurations.

Compilation Options

Compile Flag Description
POWER_SAVING When defined, power-saving modes are enabled. Without the compile flag, CC2530 PM2 and PM3 are not exercised. The compile flag affects HAL sleep module, OSAL power management module, RemoTI application framework (RTI) and etwork processor module.
Power-saving modes are not compatible with CC2531 USB dongle and hence this compile flag must not be added to configurations for CC2531.
HAL_KEY HAL key module feature flag. RNP does not include HAL key module and hence this compile flag has to be set to FALSE either in the hal_board_cfg.h file as default or in preprocessor definition setting of a project onfiguration. hal_board_cfg.h file for CC2531 set this compile flag to TRUE since another project which shares this file uses HAL key module. Hence, the compile flag is set to FALSE in the preprocessor definition setting for the CC2531F256 configuration.
CC2533F64 Non-volatile memory configuration selection for CC2533F64.
CC2533F96 Non-volatile memory configuration selection for CC2533F96.
FEATURE_TEST_MODE RTI test mode API functions shall be enabled with this compile flag. The compile flag affects RTI and RTI surrogate.
FEATURE_CONTROLLER_ONLY This compile flag, when defined, reduces RTI code size when RTI is compiled for remote controller functionality only.
FEATURE_ORIGINATOR This compile flag, when defined, defines the node being built as having ZRC2.0 Originator functionality.
FEATURE_RECIPIENT This compile flag, when defined, defines the node being built as having ZRC2.0 Recipient functionality.
FEATURE_SBL This compile flag, when defined, enables serial boot loading feature in RTI surrogate for RemoTI network processor.
Note that defining this compile flag alone does not enable serial boot loader for the whole RemoTI network processor (RNP) sample application. Choose a proper configuration (with SB tag) in the provided project to enable the serial boot loading feature. Such a configuration includes this compile flag definition in the project settings.
This flag will enable a build of an image binary suitable for Serial Bootloader downloading.
FEATURE_HEX This compile flag, when defined, enables serial boot loading feature in RTI surrogate for RemoTI network processor.

This flag will enable a build of an image which will include the NV area.
Note that defining this compile flag alone does not enable serial boot loader for the whole RemoTI network processor (RNP) sample application. Choose a proper configuration (with HEX tag) in the provided project to enable the serial boot loading feature. Such a configuration includes this compile flag definition in the project settings.
All the configurations with the _HEX postfix will invoke a build of the proper configuration of the Serial Bootloader project in the pre build option. The post build option will invoke a post build tool which will combine the Serial Bootloader, built with the pre build option, with the image built by the _HEX configuration.

HAL_UART This flag is used when UART serial port is used. This is the default setting if no other serial interface is used
NPI_UART_WAKEUP_GPIO This flag enables the host UART NPI wakeup mechanism.
HAL_SPI This flag is used when SPI serial port is used. This must be defined when using SPI interface
GENERIC=__generic This compile flag shall always be defined as GENERIC=__generic to be compatible with the RemoTI library files. The compile flag was devised to add IAR specific compiler keyword to certain function parameters.
SPI_CONFIG_ON_PORT1 This flag needs to be defined if you want SRDY and MRDY to be mapped on Port 1:
SRDY: P1.2
MRDY: P1.3
If not defined SPI bus SRDY and MRDY are mapped on port 0:
SRDY: P0.4
MRDY: P0.3
Not that SPI bus is always mapped on Port 1, from P1.4 to P1.7. (see [5] for more details)
INT_HEAP_LEN Value assign to this flag will specify the size of the Heap.

Besides the compile flags, other settings such as code model were also set to fit the configuration. For instance, CC2533F64 configuration uses near code model while other configurations use banked code model.


Files

C source files and library files are explained in Table 3 in the order they appear in the IAR workspace window. Note that there are more files than those listed in the table, such as C header files that defines constants and function prototypes and that even workspace project does not list all header files referenced by the C files.

Note that certain driver modules are included although they are not actually used, just for potential use of the drivers by custom application.

Project Files

File name Description
Application
mac_rffrontend.c RF frontend chip (either CC2591 or CC2590) connection configuration module. This file is default set to fit the connection in a CC2530-CC2591EM 2.0 board.
np_main.c Application main entry routine. This module initializes OSAL tasks.
rcn_config.c Network layer configuration file. The file contains global variables with initial values which are used as configuration parameters by RemoTI network layer. The configuration parameters are explained in the Network Layer Configuration section.
HAL
hal_assert.c HAL assertion library
hal_drivers.c Entry point for congregation of HAL drivers, such as initialization for all HAL drivers, HAL task, as an OSAL task, entry point (event handler) and polling entry point.
hal_rpc.h Remote procedure call enumerations
hal_adc.c ADC device driver
hal_aes.c AES device driver
hal_batmon.c Battery monitor service driver
hal_board_cfg.h RemoTI hardware platform specific configuration parameters and macros used by HAL. Application may also use board definition literal (HAL_BOARD_CC2530RB) and HAL feature flags (HAL_KEY, HAL_LED, etc).
hal_ccm.c CCM implementation using AES device driver
hal_dma.c DMA device driver
hal_flash.c CC253x flash device driver
hal_led.c LED driver (not in use)
hal_sleep.c Sleep mode (PM1, PM2, PM3) control implementation
hal_spi.c SPI device driver
hal_startup.c Low level init.
hal_uart.c UART device driver
hal_vddmon.c VDD monitor driver
HAL / USB CDC class specific modules
usb_cdc_hooks.c hook functions for various USB request processing, specific to USB CDC class
usb_firmware_library_config.c USB library configuration
usb_RemoTICdcDescriptor.s51 USB descriptors specific to RemoTI USB network processor dongle
HAL / USB generic firmware library for CC2531
usb_board_cfg.h Collection of macros abstracting the hardware details for USB control.
usb_interrupt.c USB interrupt initialization routine and USB interrupt service routine
usb_suspend.c USB suspend mode related subroutines
usb_descriptor_parser.c Parser for USB descriptor structures
usb_framework.c Main interface routines for USB generic library
usb_standard_request.c Handlers for USB standard requests
Libraries
rcnsuper-CC253x-banked.lib RemoTI network layer library built for banked code model. This library will be selected for F96 configuration.
rcnsuper-CC253x.lib RemoTI network layer library built for near code model. This library will be selected for F64 configuration.
OSAL
OSAL.c OSAL implementation for messaging and main event handling loop
OSAL_Clock.c OSAL clock tick implementation
OSAL_Memory.c OSAL heap implementation
OSAL_PwrMgr.c OSAL power management scheme implementation
OSAL_Timers.c OSAL timer implementation
osal_snv.c OSAL Simplified Non-Volatile memory manager. This has better code size optimization than OSAL_Nv.c module.
OSAL_Math.s51 Optimized assembly code for mathematical function (division)
RPC
npi.c Network processor interface module. This module includes either npi_uart.c, npi_i2c.c or npi_spi.c file depending on configuration.
rcns.c RemoTI network layer surrogate module. This module is called by RTI surrogate module and it serializes and de-serializes RemoTI network layer function call interfaces (absent in the CC2533 configuration).
rtis_np.c RemoTI application framework (RTI) surrogate module. This module handles network processor interface packets and serializes and de-serializes RemoTI application framework (RTI) function call interfaces.
RTI
rti.c RemoTI stack API
rti_testmode.c RemoTI test mode API function implementation
PROFILES\GDP
gdp.c GDP2.0 profile implementation layer
gdp_binding_originator.c GDP2.0 binding originator state machine
gdp_binding_recipient.c GDP2.0 binding recipient state machine
gdp_common.c Functions used by both originator and recipient modules
gdp_configuration_originator.c GDP2.0 configuration phase of originator binding procedure
gdp_configuration_recipient.c GDP2.0 configuration phase of recipient binding procedure
gdp_discovery_originator.c GDP2.0 discovery phase of originator binding procedure
gdp_discovery_recipient.c GDP2.0 discovery phase of recipient binding procedure
gdp_enhanced_security.c GDP2.0 Enhanced Security procedure
gdp_identification_client.c GDP2.0 client Identification Announce procedure
gdp_null_recipient.c GDP2.0 recipient functionality available when recipient is in NULL state (i.e. not actively in binding procedure)
gdp_originator_task.c GDP2.0 Originator node OSAL task
gdp_pairing_originator.c GDP2.0 pairing phase of originator binding procedure
gdp_pairing_recipient.c GDP2.0 pairing phase of recipient binding procedure
gdp_poll_client.c GDP2.0 client polling procedures
gdp_recipient_task.c GDP2.0 Recipient node OSAL task
gdp_validation_originator.c GDP2.0 validation phase of originator binding procedure
gdp_validation_recipient.c GDP2.0 validation phase of recipient binding procedure
PROFILES\ZRC
zrc.c ZRC2.0 profile implementation layer
zrc_action_mapping_client.c ZRC2.0 Action Mapping Client procedures
zrc_binding_originator.c ZRC2.0 binding originator state machine
zrc_binding_recipient.c ZRC2.0 binding recipient state machine
zrc_configuration_originator.c ZRC2.0 configuration phase of originator binding procedure
zrc_configuration_recipient.c ZRC2.0 configuration phase of recipient binding procedure
zrc_home_automation_client.c ZRC2.0 HA Client procedures
zrc_null_recipient.c ZRC2.0 recipient functionality available when recipient is in NULL state (i.e. not actively in binding procedure)
SerialBoot
sb_target.c Image preamble definition for use by serial boot loader, and serial boot loading command packet handler.

Architecture

This section briefly explains the interactions and relationship among the modules represented by files described in previous section. See [7] for the architectural description of the network processor as a whole.

Figure 2: RemoTI Network Processor Software Architecture

Figure 2 illustrates inter-module interactions within RemoTI network processor on the right hand. On the left hand are the inter-module interactions of the PC tools as emulating host processor.

Each network processor module acronym is explained below:

  • RCN – RemoTI network layer
  • RCNS – RemoTI network layer surrogate
  • RTI – RemoTI application framework
  • RTIS – RemoTI application framework surrogate
  • NPI – Network Processor Interface
  • MAC – Medium Access Control layer (it is part of RemoTI network layer library in the file list)
  • HAL UART – Hardware Abstraction Layer UART driver
  • GDP – Generic Device Profile implementation co-layer
  • ZRC2.0 – ZRC2.0 profile implementation co-layer (Includes GDP profile)

Either RTI or RCN interface is selected dynamically using different path among the modules.

The following modules have their own OSAL tasks (which is different from the generic meaning of OS tasks: The OSAL tasks do not own its own thread context. It is merely an entity leveraging OSAL event, messaging and power management mechanism):

  • MAC module
  • RCN module
  • RTI module
  • ZRC2.0 module tasks (separate task for ZRC2.0 originator and recipient)
  • NPI module
  • HAL module
  • Application main entry module

Among the modules above, application main entry module does not use any OSAL services. However it creates an OSAL task for any custom extension, following usual sample application template.

Baud Rate

RemoTI network processor was tested with 115200bps baud rate. However, hal_uart.c module supports 57600bps, and 230400bps, as well and it is possible to modify network processor to work with this baud rate. Note that use of lower baud rate has to be compatible with the use cases. For instance, the average throughput over the UART must not be higher than selected baud rate and heap size has to be adjusted depending on how long peak data rate that is higher than selected baud rate lasts in the worst case. When data rate of network processor interface packets towards host processor is higher than that of UART transport, the data packets occupies heap space until they can be processed out to UART transport layer. Hence, the longer and the higher the peak data rate is, the more heap memory is used. The default heap size (1024 bytes) is set to fit Target Emulator use case (test mode operation from a single remote or CERC packets from multiple remotes). For more stressful use case (reception of more lasting contested traffic from multiple remotes), start with bigger heap size (for instance, 2048 bytes) at the beginning of development and optimize heap size down. See the Stack and Heap section for a method to profile and adjust heap size.

In order to switch baud rate, change the NPI_UART_BAUD_RATE macro value in Projects\RemoTI\common\npi\npi_np\npi_uart.c file.

The default setting is as follows:

#define NPI_UART_BAUD_RATE HAL_UART_BR_115200

To change the baud rate to 57600bps for instance, change the line as follows:

#define NPI_UART_BAUD_RATE HAL_UART_BR_57600

Note that the host processor UART baud rate has to be modified to match the changed baud rate of network processor.

Note that SPI baud rate is controlled by host processor, for host processor SPI is the master and the network processor SPI is the slave.

CC2531 uses USB as the underlying physical connection with the host processor and supports USB CDC interface. USB CDC interface baud rate is selectable from the USB host.


UART wake up mechanism

Network processor supports two-pin configuration for UART (RXD and TXD).

Hence, there is no difference whether network processor is DTE or DCE. When a PC is used as the host processor in use with the RemoTI Target Board provided with the development kit, the PC assumes the role of DTE, but the concept of DTE/DCE ends within PC application and USB virtual serial port driver.

CC253x does not support wakeup on UART receive line activity and hence network processor software dynamically configures UART receive pin as a generic IO pin to wake up on UART activity when the network processor is in sleep mode. In such a mechanism as this, more than one character may be lost till UART is fully functional exiting sleep mode. Hence, a handshake mechanism is added.

When waking up a network processor a null character (0x00) is sent to network processor and network processor responds with a null character (0x00) when it has set up UART.

Figure 3 and Figure 4 illustrate the sleep sequence and the wake up sequence each.

Note that the rti.c module changes its power management state to conserve power state during UART sleep sequence but it does not change its power management state back to hold power state during UART wakeup sequence. RTI power management state in network processor is used only upon boot up of the software till the first RTI_EnableSleepReq() and afterwards NPI power management state represents the latest sleep or wakeup command from host processor. The reason for having RTI power management state is to re-use the same RTI module implementation that is used by a CC2530 standalone application and also to have the consistent RTI API behavior.

For host processors that could wake up its UART block on UART receive line activity within one character duration, the wakeup mechanism could be simply adding a preamble null character preceding a transmit UART frame from network processor. For other host processors that require its own wakeup handshaking, the npi_uart.c module has to be modified to add such handshaking.

Note that UART wakeup mechanism does not apply to CC2531. CC2531 emulates the same interface as UART over USB CDC interface but the device does not operate in the power-saving mode when RTI_EnableSleepReq() is called.

Figure 3: UART Sleep Sequence
Figure 4: UART WakeUp Sequence

Host UART NPI wake up mechanism

Figure 5: Host UART WakeUp Sequence

Network processor also incorporates an example host processor wakeup mechanism. This can be enabled by adding the compile flag NPI_UART_WAKEUP_GPIO for the CC2530 or CC2533. This example allows a host processor to go to sleep and wake up if the network processor receives external RF data requiring the host’s attention.

To accomplish this, a third pin from the network processor is configured as a generic IO which will assert when it wants the host to wake up to handle UART traffic. By default this is set to be P2_1 on the CC2530 and CC2533 and can be edited in npi_uart.c.

When the host determines it is time to go to sleep. It will send RTI_EnableSleepReq() to the network processor. If the network processor UART is not busy this will cause it to change its npiSleepState to NPI_UART_SLEEPING. The network processor will send a confirmation to the host. As long as the network processor is in this state, it will assume the host processor must be woken up before sending any UART traffic to the host. As long as the npiSleepState is set to sleeping, any UART data bound for the host will be buffered into the OSAL heap until it is full.

UART traffic to the sleeping host from the network processor may occur if an external controller sends RF data to the network processor. If this happens, instead of immediately transmitting the information to the host via UART, the network processor will first assert on the GPIO assigned to wake up the host and change its npiSleepState to NPI_UART_WAITING_FOR_HOST. It will then proceed to wait for an RTI_PingReq() from the host over UART notifying the network processor that the host is awake and ready to handle UART data. The RTI_PingReq() can actually be any data sent over the UART Rx line to the network processor. The data will be thrown away. This action just lets the network processor know that the host is awake again and ready to start receiving buffered UART data. So the RTI_PingReq() and RTI_PingRsp() are just the shortest possible valid command to make this happen, a command subsystem id and command id with no payload. The network processor ping commands both use a single command id 0x10 for this example.

Finally once the ping is received from the host, the network processor will de-assert the GPIO, send a RTI_PingRsp(), and change its npiSleepState to NPI_UART_AWAKE. The network processor will empty its UART buffer and send all outstanding messages to the host. The host may then determine if it wishes to remain awake and handle the data or go back to sleep.


Adding New Network Processor Interface Commands

[7] Specifies all supported network processor interface commands. This chapter provides instructions on how to add additional commands which are not listed in [7].

Additional commands have to comply with the packet format specified in [7]. All network processor interface commands are forwarded to either NPI_AsynchMsgCback() function or NPI_SyncMsgCback() function depending on whether the command is an asynchronous request or a synchronous request (See [7] for the definition of asynchronous request and synchronous request). Both functions are defined in the rtis_np.c file.

A new command can be added using its own subsystem identifier and command identifier. NPI_AsynchMsgCback() function and NPI_SyncMsgCback() function simply decodes subsystem identifier and command identifier and performs proper actions accordingly.

Currently used subsystem identifier values are listed in hal_rpc.h file. The following is an example. Look at the hal_rpc.h file in the released software to find the correct subsystem identifier values in use.

// RPC Command Field Subsystem
#define RPC_SYS_RES0        0
#define RPC_SYS_SYS         1
#define RPC_SYS_MAC         2
#define RPC_SYS_NWK         3
#define RPC_SYS_AF          4
#define RPC_SYS_ZDO         5
#define RPC_SYS_SAPI        6    // Simple API
#define RPC_SYS_UTIL        7
#define RPC_SYS_DBG         8
#define RPC_SYS_APP         9
#define RPC_SYS_RCAF        10   // Remote Control Application Framework
#define RPC_SYS_RCN         11   // Remote Control Network Layer
#define RPC_SYS_RCN_CLIENT  12   // Remote Control Network
#define RPC_SYS_BOOT        13   // Serial Bootloader
#define RPC_SYS_MAX         14   // Maximum value, must be last

Note that NPI_SyncMsgCback() function has to store the response message into the same buffer where the request command is stored when the function is called. The buffer is de-referenced using the pMsg pointer argument.

The following code is an example of how a network processor interface command is processed.


void NPI_SynchMsgCback( npiMsgData_t *pMsg )
{
 if (pMsg->subSys == RPC_SYS_RCAF)
 {
   switch( pMsg->cmdId )
   {
   /* Other case statements precede this */
   case RTIS_CMD_ID_RTI_READ_ITEM_EX:
     pMsg->len = pMsg->pData[2] + 1;
     pMsg->pData[0] = RTI_ReadItemEx(pMsg->pData[0], pMsg->pData[1], pMsg->pData[2], pMsg->pData[1]);
     break;    /* Other case statements follow */
   }
 } 
#if !defined CC2533F64
 else if (pMsg->subSys == RPC_SYS_RCN)
 {
   // special case handling
   if (RCNS_HandleSyncMsg((uint8 *) pMsg))
   {
     rtisState = RTIS_STATE_NETWORK_LAYER_BRIDGE;
     RTI_SetBridgeMode((rtiRcnCbackFn_t) RCNS_SerializeCback);
   }
 }
#endif
}

UART vs. SPI

The network processor SW comes with a set of configurations defined as in [7] which specify the interface being used. Table 4 compares UART and SPI.

UART vs. SPI comparison

UART SPI
Highest peak baud rate 230400bps 4Mbps
Number of signal pin connections (including network processor reset line) 3 7
Host processor portability (See [8]) Generic UART drivers are available for most of the platforms (e.g. PC has serial port driver out of the box).
Network processor interface and RTI surrogate have to be ported.
Custom SPI driver has to be written per platform, as proprietary MRDY and SRDY line control is necessary.
Network processor interface and RTI surrogate have to be ported.

Flash page map and memory map

Each configuration of network processor has a unique flash page map. Figure 6 illustrates two distinctive flash page maps used by network processor. One flash page is 2048 bytes for CC2531 and 1024 for CC2533 as specified in [5]. OSAL used a system of virtual page, one virtual page is 2 physical page for CC2533.

For serial boot loading feature enabled configuration, the boot loader code occupies the first virtual flash page (page 0). The last virtual flash page is reserved for the flash lock bits and the commissioned IEEE address. OSAL non-volatile memory pages occupy configurable number of pages from the second last page down. Between the NV pages and the first page is the code space. The remainder of the last flash page cannot be used for code space because this page cannot be updated during serial boot loader execution. The details of serial boot loading feature enabled configuration are explained in the Serial Boot Loader section. Find more information about the last flash page and flash lock bits in [5].

Without serial boot loading feature, the code starts at the first page (lowest address page) up. OSAL non-volatile memory pages occupy configurable number of pages from the second last page down. The last flash page includes lock bits (last 16 bytes. See [5] for details) and commissioned IEEE address (8 bytes, prior to lock bits). IEEE address is explained more in the IEEE address section. The remainder of this last flash page can be used for additional code if the code fills up the rest of the space.

Figure 6: Flash Page Map

The number of virtual pages used for OSAL non-volatile memory system is defined in hal_board_cfg.h file. The constants and their values are listed in Table 5. This application is using the osal_snv.c, Simple NV, driver. There can only be 2 virtual pages defined with this drive.

NV configuration constants

Constant Name Description CC2533F64 CC2533F96
HAL_NV_PAGE_END HAL_FLASH_IEEE_PAGE
(i.e. relative to lock bits page)
Virtual Page Physical Pages Virtual Page Physical Pages
31 62,63 47 94,95
HAL_NV_PAGE_CNT Number of OSAL NV pages 2 2

The linker command file can be located from project option pop up window. For instance after selecting the CC2533F96 configuration, select Project->Options menu. In project option pop up window, select linker category and Config tab. The linker command file name and path is displayed in Figure 7.

In the linker command file, find _ZIGNV_ADDRESS_SPACE_START definition and change the starting address to match the number of pages defined. For instance, the default linker command file for CC2533F96 configuration has the following lines:


...
//_FLASH_BEG=0x2F400           // Address range for HAL_FLASH_PAGE_SIZE == 1024
-D_FLASH_BEG=0x2E800           // Address range for HAL_FLASH_PAGE_SIZE == 2048
//_FLASH_END=0x2FBFF           // Address range for HAL_FLASH_PAGE_SIZE == 1024
-D_FLASH_END=0x2F7FF           // Address range for HAL_FLASH_PAGE_SIZE == 2048
...

Figure 7: Linker File Selection

XDATA memory map and CODE memory space are described in [5].

CC2533F64 configuration uses near code model and bank area is always occupied with the same code, non-volatile memory pages and lock bit pages content as in flash page map.

Physical and Logical Addresses

The CC2533F96 and CC2531F256 configurations use banked code model and bank area is dynamically mapped to flash bank (comprised of 16 pages) in use. Code address space is represented in virtual code address. Virtual address for code bank is listed in Table 6.

Virtual address of banked code

Bank Absolute Address Logical Address
0 0x000000 - 0x007FFF 0x000000 - 0x007FFF
1 0x008000 - 0x00FFFF 0x008000 - 0x00FFFF
0x018000 - 0x01FFFF
2 0x010000 - 0x017FFF 0x028000 - 0x02FFFF
3 0x018000 - 0x01FFFF 0x038000 - 0x03FFFF
4 0x020000 - 0x027FFF 0x048000 - 0x04FFFF
5 0x028000 - 0x02FFFF 0x058000 - 0x05FFFF
6 0x030000 - 0x037FFF 0x068000 - 0x06FFFF
7 0x038000 - 0x03FFFF 0x078000 - 0x07FFFF

Bank 0 is constantly mapped to common area (0x0000 – 0x7FFF) and the other banks are mapped to bank area (0x8000 – 0xFFFF) dynamically. CC2533F96 has up to bank 2. Bank 3 to bank 7 applies only to the CC2531F256.

Such a bank set up is determined at link time and it is configured through linker configuration file. Linker configuration file can be found through Project->Options in IAR (Linker category and then Config tab) as illustrated in Figure 7.

Figure 8 shows where to find near code model or banked code model setting in an IAR project options window.

Figure 8: Code Model

The CC2533 actually has a physical flash page size of 1024 vice 2048 on the CC2531. The released, default configuration of OSAL NV is to combine two physical 1K pages into a virtual 2K page. If code space must be reclaimed from the OSAL NV module on the CC2533 part, it is possible to change the default setting from 2-2K pages to 2-1K pages. But if the OSAL NV page size is changed to be the physical page size of 1K, then writes to NV will cause more frequent page compactions and the lifetime endurance of the OSAL NV flash pages can be expected to be reduced. If such a reduction in lifetime can be tolerated and it is absolutely necessary to reclaim 2K of flash for code space, then one only need change a setting in the hal_board_cfg.h and corresponding linker .xcl file as follows.

In hal_board_cfg.h, change HAL_FLASH_PAGE_SIZE from 2048 to 1024 here:


#define HAL_FLASH_PAGE_PHYS        1024UL
//define HAL_FLASH_PAGE_SIZE       HAL_FLASH_PAGE_PHYS
#define HAL_FLASH_PAGE_SIZE       (HAL_FLASH_PAGE_PHYS * 2)

Stack and Heap

8051 micro-controller uses a variety of data memory access methods. Generic data memory (i.e. not one specific for register access) is the internal data memory with 8 bit address space (IDATA) and the external data memory with 16 bit address space (XDATA). CC253x maps both memory address space to the same internal SRAM. See [5] for details. IAR compiler generates code to use stack from both IDATA and XDATA. How a compiled code uses IDATA and XDATA for stack is highly dependent on compiler itself.

With IAR 8051 compiler version 9.20, RemoTI 1.4 CC2533 originator network processor uses about 187 bytes of XDATA stack and 90 bytes of IDATA stack. However, the depth of the used stacks could change with even slight modification of the code as how compiler generates code to use stack is unpredictable.

Hence, 384 bytes of XDATA stack and 192 bytes of IDATA stack were reserved in project settings for RemoTI 1.4 CC2533 originator network processor. Stack sizes can be adjusted after profiling the stack usage with the final application code, by browsing stack memory space through debugger.

For instance, XDATA stack is located between addresses 0x000 and 0x17F and IDATA stack is located between addresses 0x40 and 0xFF in case RemoTI 1.4 CC2533 originator network processor build, as can be found from generated map file.

IAR embedded workbench populates the value 0xFF to the entire XDATA stack and IDATA stack space when the code is freshly flashed to the CC253x prior to running initialization.

Figure 9: XDATA Stack Profiling

After running the application for the use cases picked for the deepest stack usage, the stack memory space can be browsed to determine how much stack was in use. In Figure 10, XDATA stack was used down to 0xCD (starting at 0x17F). Plus a there is some data used at the end of the stack down to 0x00 (starting at 0x07) which makes the stack depth in this use case to be 0x17F – 0xCD + 1 + 0x07-0x00 + 1 = 187 bytes

IDATA stack usage can be profiled likewise. Just select IData to browse IData memory.

Once stack usage is profiled, the stack size can be adjusted from project settings (General Options category, Stack/Heap tab).

Figure 10: Finding Stack Location

RemoTI software uses heap through OSAL memory management module. The default heap size is in np_main.cfg file or by setting the compilation flag INT_HEAP_LEN. Heap usage varies drastically per use case even with the same software image. In other words, heap size has to be determined based on the supported use cases of the products. See RemoTI Network Processor Application for correlation with baud rate.

In order to profile heap usage, some OSAL code has to be instrumented. Unlike stack memory space, heap memory space is not initialized with a certain pattern of data (0xCD). Hence, it is necessary to add code to initialize the heap memory space before the space is being used.

The best location is osal_mem_init() function in OSAL_Memory.c module.

At the beginning of the function, add memory initialization code as follows:


void osal_mem_init( void )
{
 osalMemHdr_t *tmp;
 MAX_HEAP_SRAM_SIZE(maxPossibleHeapSize);
 theHeap = (unit8 *)__segment_begin(“START_OF_HEAP”);
 HAL_ASSERT(maxPossibleHeapSize > MIN_HEAP_SIZE);
#if( OSALMEM_PROFILER )
 osal_memset( theHeap, OSALMEM_INIT, maxPossibleHeapSize);
#endif
// Add this code to initialize memory space
extern void *osal_memset( void *dest, uint8 value, int len );
osal_memset( theHeap, 0xCD, maxPossibleHeapSize);

Note that the OSALMEM_PROFILER compile flag is also supported. When the compile flag is defined as TRUE, the heap space is initialized with OSALMEM_INIT value. OSALMEM_PROFILE compile flag brings in more code than the heap initialization, which is not explained in this document.

By default the OSALMEM_INIT value is X (0x58). Value F (0x46) describes an area that has been allocated and freed.

With the new image, after running the use case with maximum heap usage, break the debugger and check the theHeap memory space.

Address range of theHeap variable can be found from map file.

Figure 11: Heap Usage Profiling

The theHeap variable occupies 0xC0C to 0x16FF address space for example. This range can be determined from checking the map value of theHeap variable and the maxPossibleHeapSize variable.

Note the heap is not used as the stack, memory can be allocated in several different places in the heap, and not always form the beginning of the Heap. You will need to go through the heap and count all value different than 0xCD.

In Figure 11, you can see memory used form 0xC0C to 0xC28. That amounts to 0xC0C - 0xC28 + 1 = 29 bytes of heap usage. Note that since this code simply initializes the heap values, it cannot necessarily tell you exactly how much of the heap is in use as it does not know about recently freed heap space. Turning on OSALMEM_PROFILER can provide more information about heap space that has been allocated, initialized and freed.

Note that the maxPossibleHeapSize varies based on the available memory. The project maximizes this value based on the space available. Also note that the maxPossibleHeapSize will always be at least equal to MIN_HEAP_SIZE. This is set to 1024 for the CC2533.

IEEE address

CC253x has its own IEEE address built into the chip (information page IEEE address). RemoTI network layer uses this IEEE address unless the IEEE address is overridden with a custom IEEE address by RCN_NlmeSetReq() call for RCN_NIB_IEEE_ADDRESS attribute. Once the IEEE address is overridden, network layer uses the custom IEEE address till this custom IEEE address is overwritten with another RCN_NlmeSetReq() call. If upper layer writes 0xFFFFFFFFFFFFFFFF as the custom IEEE address, network layer uses this null IEEE address till next power cycle. From next power cycle, network layer will start using the IEEE address built into the chip again.

RemoTI application framework, rti.c module, uses RCN_NlmeSetReq() to prioritize an IEEE address programmed to a specific last flash page location. See rtiProgramIeeeAddr() function for the source code. This function is called upon every system reset and the function reads the commissioned IEEE address in the special location and if it is valid (non-0xFFFFFFFFFFFFFFFF), this IEEE address is set to the network layer using RCN_NlmeSetReq() call. The special location is offset 0x7E8 of the last page stored in little-endian order, which neighbors lock bits which starts from offset 0x7F0. This is the location where SmartRF programmer will program the secondary IEEE address. The secondary location of IEEE address on the SmartRF Flash programmer window as in Figure 12 corresponds to the commissioned IEEE address while the primary location of IEEE address corresponds to the aforementioned information page IEEE address.

Figure 12: Using SmartRF Flash Programmer to Read Secondary IEEE Address

Hence, with RemoTI application framework, the hierarchy of IEEE address upon CC253x reset is as follows:

  • If the commissioned IEEE address is valid, use the commissioned IEEE address
  • Otherwise, use the information page IEEE address

Figure 13 illustrates the flow chart of selecting the network layer IEEE address, during startup of a device.

Figure 13: IEEE Selection on RemoTI Initialization

Network layer configuration

The standard NIB attributes can be configured and updated at run time through RTI_WriteItemEx() function or RCN_NlmeSetReq() function in case rti.c module is not used.

In rti.c module, rtiResetSA() function implementation shows example of RCN_NlmeSetReq() calls to set standard defined NIB attributes.

Network layer attributes that can be used with either RTI_WriteItemEx() or RCN_NlmeSetReq() are enumerated in rcn_attribs.h file. Note that several non-standard attributes are also provided.

The following Table 7 explains non-standard attributes.

Network layer custom attributes

Attribute identifier Description
RCN_NIB_NWK_NODE_CAPABILITIES This attribute corresponds to standard constant nwkcNodeCapabilities.
The value of this attribute should not change in product.
RCN_NIB_NWK_VENDOR_IDENTIFIER This attribute corresponds to standard constant nwkcVendorIdentifier.
The value of this attribute should not change in product.
RCN_NIB_NWK_VENDOR_STRING This attribute corresponds to standard constant nwkcVendorString.
The value of this attribute should not change in product.
RCN_NIB_STARTED It is an attribute to indicate whether network layer has started (‘1’) or not (‘0’). This attribute is useful for application to determine whether it has to perform cold boot procedure or warm boot procedure.
RTI module (rti.c) uses this attribute to determine cold boot or warm boot procedure.
RCN_NIB_IEEE_ADDRESS IEEE address attribute. By default, network layer will program IEEE address using chip IEEE addresss.
Application can override chip IEEE address with this attribute. Note that RTI module (rti.c) writes into this attribute upon system reset. Application should consider conflict with RTI module when writing this attribute. See the IEEE address section for details.
RCN_NIB_AGILITY_ENABLE Enable/disable frequency agility
RCN_NIB_TRANSMIT_POWER Set transmission power level in dBm.

Note that other non-standard attributes such as RCN_NIB_PAN_ID and RCN_NIB_SHORT_ADDRESS are not configurable items. Those attribute values can be read for debug purpose.

Certain set of network layer implementation parameters can also be modified at build time by changing rcn_config.c file. The file is configured with default recommended values.

Serial Boot Loader

Overview of the serial boot loader demo

Serial boot loading is a feature that enables a RemoTI network processor device to download its embedded software image from a host processor through serial interface, such as UART and SPI. It is out of scope of this document how the host processor gets a software image for a particular network processor.

Serial boot loader demo consists of a network processor image which is built in serial boot loading enabled configuration, a serial boot loader programmed network processor device and serial boot loader demo PC tool. See [6] for build, setup and execution instructions.

Serial boot loader code resides at the bottom of the flash memory map as in Figure 6. Upon power cycle, serial boot loader decides whether to start serial boot loading or to jump to the downloaded image area. How the decision is made is implementation specific. In the UART serial boot loader demo code, serial boot loader makes a decision by validity of the downloaded image. If the image in the downloaded image area is not a valid image, the serial boot loader starts in serial boot loading mode and waits for commands from host processor. If the image in the downloaded image area is valid, the boot loader jumps to the valid image area. A network processor application which supports this UART serial boot loader mechanism has to clear the image preamble area and triggers a watchdog reset, as a result of processing a command from host processor to trigger serial boot loading.

Once in serial boot loading mode, the serial boot loader receives commands from host processor and executes them. Host processor is the intelligent part of the protocol. Host processor chooses image sector to download, reads back downloaded image area sector to verify the written image and authorize the use of the image, etc.

In the demo, host processor is emulated by a PC demo tool.

Serial boot loading commands

Serial boot loading command packets follow the same format as regular network processor interface commands. However, they are not exactly the same as serial boot loading commands are accepted only by the serial boot loader in serial boot loading mode and underlying transport mechanism could be different from the one used by network processor image. For instance, serial boot loader might be running 115200bps baud rate while network processor interface could be running 230400bps baud rate.

The serial boot loading command is always triggered by host processor first and then the serial boot loader of the network processor sends a respond command. Each command is described in the subsections.

Handshake command

The Handshake is command ID 0x04. The handshake has no parameters. The handshake is sent by the host processor to determine if the boot loader is running on the network processor device.

Handshake Command

Number of Bytes 1 Byte 1 Byte 1 Byte 1 Byte
Field SOP Len Sys (13) CMD (0x04)

The network processor boot loader responds with a 1 byte status code containing SB_SUCCESS.

Handshake Response

Number of Bytes 1 Byte 1 Byte 1 Byte 1 Byte 1 Byte
Field SOP Len Sys (13) CMD (0x84) Status (0)

Write command

The Write command is command ID 0x01. The write is sent by the host processor to write image portion to the flash on the network processor device. The write command has the following parameters:

Write Command

Number of Bytes 1 Byte 1 Byte 1 Byte 1 Byte 2 Bytes 64 Bytes
Field SOP Len Sys (13) CMD (0x01) Address Data

The address contains a word aligned address of the image. The network processor boot loader must add the base address of the network processor program area to the address. The network processor boot loader responds to the write command with the status of the operation.

Write Response

Number of Bytes 1 Byte 1 Byte 1 Byte 1 Byte 1 Byte
Field SOP Len Sys (13) CMD (0x81) Status

Read command

The Read command is command ID 0x02. The read command is sent by the host processor to read from the flash on the network processor. The read command has the following parameters:

Read Command

Number of Bytes 1 Byte 1 Byte 1 Byte 1 Byte 2 Bytes
Field SOP Len Sys (13) CMD (0x2) Address

The address contains a word aligned address of the image. The network processor boot loader must add the base address of the network processor program area to the address. The network processor responds to the read command with the status of the operation, the address, and the data.

Read Response

Number of Bytes 1 Byte 1 Byte 1 Byte 1 Byte 1 Byte 2 Bytes 64 Bytes
Field SOP Len Sys (13) CMD (0x82) Status Address Data

Enable command

The Enable command is command ID 0x03. The enable command is sent by the host processor to indicate the image on the network processor is valid. When the network processor boot loader has received the enable, it writes SB_ENABLED_VALUE to the enabled parameter of the preamble in the application image. The boot loader uses the enabled parameter of the preamble at startup to determine if a valid image is present in the application memory space.

Enable Command

Number of Bytes 1 Byte 1 Byte 1 Byte 1 Byte
Field SOP Len Sys (13) CMD (0x3)

The network processor boot loader responds with a 1 byte status code containing SB_SUCCESS.

Enable Response

Number of Bytes 1 Byte 1 Byte 1 Byte 1 Byte 1 Byte
Field SOP Len Sys (13) CMD (0x83) Status (0)

Boot loading sequences

Figure 14 and Figure 15 illustrate boot loading sequences and application image downloading sequences performed during boot loading.

Note that validity of the image is determined by checking preamble of the application image area, which is updated only as the last transaction of image download sequence. If anything goes wrong during download of the image, such as power failure, the preamble of the image area is not updated and serial boot loader stays in boot loading mode waiting for boot loading command from host processor.

When the image is valid, the boot loader jumps to the image area.

Note that host processor reads back application image before enabling the image. The idea is to validate written image without having to impose CRC checking in the serial boot loader. It was done so to minimize code size of the serial boot loader. On the other hand, the time taken for serial downloading would take longer than using CRC validation mechanism since the entire image has to be read back.

Figure 14: Initial Application Image Download Sequence
Figure 15: Consequent Application Image Download Sequence

Checksum in preamble

As discussed in the boot loading sequence section, the image is validated when the enable command is sent. What determines validation is that the provided 16-bit checksum matches that of the generated, or set, 16-bit checksum. There are two different flavors of the boot loader. One will calculate the checksum, while the other will copy the checksum from the provided value. The latter is significantly faster, but places all responsibility for image integrity on the host.

Checksum Location
Device .bin .bin (for SBL) .hex .hex (with SBL)
CC253x (non-USB) 0x0090 0x0890* 0x0090 0x0890
CC2531 (USB) 0x0090 0x1894** 0x0090 0x1894

* SBL is not located in generated .bin, so the first 0x800 bytes are not present.
** SBL is not located in generated .bin, so the first 0x1800 bytes are not present.

Network processor configuration for serial boot loading

RemoTI network processor includes serial boot loading demo feature. When the serial boot loading enabling configuration is in use, the sb_target.c module is compiled together and serial boot loading specific linker command file is selected. Serial boot loader configuration also adds FEATURE_SERIAL_BOOT compile flag definition, which enables handling of serial boot loader mode command which triggers software reset to serial boot loading mode from normal network processor operation.

Lock bit page

When building network processor image for serial boot loading, lock bit page cannot be used to store the downloaded code image as lock bit page itself cannot be overwritten during execution of code. Lock bit page can be updated only though debug interface. That is why the lock bit page usage is reserved in Figure 6.

Locking Bootloader

It is highly recommended to lock the pages consumed by the SBL. Since these pages will never change during the life time of the device it is best to make them read-only. Although the SBL does not intentionally overwrite itself, it cannot protect the application that is downloaded from doing so. The only guaranteed protection is to lock the pages. There are several ways to do so.

SBL pages to lock

Description CC2533F64 CC2533F96 CC2531F256
Pages consumed by SBL that should be locked Virtual Page Physical Pages Virtual Page Physical Pages Virtual Page Physical Pages
0,31 0-1,62-63* 0,47 0-1,94-95* 0,127* 0,127*

* Note that the last page is implicitly read-only when not in debug mode. It is not necessary to explicitly lock it with lock bits.

LockingSBL CC2533F64.png LockingSBL CC2533F96.png LockingSBL CC2531F256.png

DMA, peripheral IO and timers

RemoTI network processor uses the following resources:

  • USART0 when configured for UART
  • USART1 when configured for SPI
  • Peripheral IO pins P0_2 and P0_3 when configured for UART
  • Peripheral IO pins P0_3, P0_4, P1_4, P1_5, P1_6 and P1_7 when configured for SPI
  • DMA channel 0 for non-volatile memory access
  • DMA channel 1 and 2 for AES encryption/decryption
  • DMA channel 3 and 4 for UART or SPI
  • Timer2 (MAC timer) and sleep timer
  • USB controller for CC2531
Other peripheral IO might be set up by default (for instance, IO pin connected to LEDs on RemoTI Target Board platform) by HAL but they are not used by the network processor application and they are free to use by custom code.
Retrieved from "http://processors.wiki.ti.com/index.php?title=RemoTI-1.4.0-Network_Processor_Developers_Guide&oldid=210831"