1.3.4 Using The PRIME Library
The following code shows a basic example on how to use the PRIME Library in a Service Node. For more complete examples, follow the code in the provided example applications.
Example application for a PRIME Service Node
const PRIME_API *gPrimeApi;
SRV_USI_HANDLE gUsiHandle=0;
APP_MODEM_STATES modemState;
void APP_Modem_Initialize(void)
{
SRV_STORAGE_PRIME_MODE_INFO_CONFIG boardInfo;
/* Reset node state */
sAppNodeState = APP_MODEM_NODE_UNREGISTERED;
(void) memset(&boardInfo, 0, sizeof(boardInfo));
/* Get the PRIME version */
SRV_STORAGE_GetConfigInfo(SRV_STORAGE_TYPE_MODE_PRIME, (uint8_t)sizeof(boardInfo),
(void *)&boardInfo);
/* Get PRIME API pointer */
switch (boardInfo.primeVersion)
{
case PRIME_VERSION_1_3:
PRIME_API_GetPrime13API(&gPrimeApi);
break;
case PRIME_VERSION_1_4:
default:
PRIME_API_GetPrime14API(&gPrimeApi);
break;
}
/* Set state */
modemState = APP_MODEM_STATE_CONFIGURE;
}
void APP_Modem_Tasks(void)
{
switch (modemState)
{
case APP_MODEM_STATE_CONFIGURE:
/* Check if PRIME stack is ready */
if (gPrimeApi->Status() == SYS_STATUS_READY)
{
/* Set callback functions */
APP_Modem_SetCallbacks();
modemState = APP_MODEM_STATE_TASKS;
}
break;
case APP_MODEM_STATE_TASKS:
/* Check data reception */
while(sAppModemMsgRecv[outputMsgRecvIndex].len)
{
APP_MODEM_PRIME_API_CMD apiCmd;
uint8_t *recvBuf;
/* Extract command */
recvBuf = sAppModemMsgRecv[outputMsgRecvIndex].dataBuf;
apiCmd = (APP_MODEM_PRIME_API_CMD)*recvBuf++;
switch (apiCmd)
{
case APP_MODEM_CL_NULL_MLME_REGISTER_REQUEST_CMD:
APP_Modem_MLME_RegisterRequestCmd(recvBuf);
break;
case APP_MODEM_CL_NULL_MLME_UNREGISTER_REQUEST_CMD:
gPrimeApi->MlmeUnregisterRequest();
break;
case APP_MODEM_CL_NULL_MLME_GET_REQUEST_CMD:
APP_Modem_MLME_GetRequestCmd(recvBuf);
break;
case APP_MODEM_CL_432_ESTABLISH_REQUEST_CMD:
APP_Modem_CL432EstablishRequestCmd(recvBuf);
break;
case APP_MODEM_CL_432_RELEASE_REQUEST_CMD:
APP_Modem_CL432ReleaseRequestCmd(recvBuf);
break;
case APP_MODEM_CL_432_DL_DATA_REQUEST_CMD:
APP_Modem_CL432DataRequestCmd(recvBuf);
break;
default:
SRV_LOG_REPORT_Message_With_Code(SRV_LOG_REPORT_INFO,
APP_MODEM_ERR_UNKNOWN_CMD, "ERROR: unknown command\r\n" );
break;
}
break;
default:
break;
}
}
Certification PIBs
In a Base Node, only when the certification mode is set to MAC certification, the
following standard PIB attributes are enabled and operative:
- 0x0067 (PIB_MAC_ACTION_REJECT)
- 0x0068 (PIB_MAC_ACTION_ALIVE_TIME)
- 0x006A (PIB_MAC_ACTION_BROADCAST_DATA_BURST)
- 0x006B (PIB_MAC_ACTION_MGMT_CON)
- 0x006C (PIB_MAC_ACTION_MGMT_MUL)
- 0x006F (PIB_MAC_ACTION_SEGMENTED_432)
- 0x0080 (PIB_MAC_ACTION_APPEMU_DATA_BURST)
- 0x0081 (PIB_MAC_ACTION_MGMT_DATA_BURST) (only in PRIME v1.4)
In a PRIME v1.4 Base Node, the following PIB attributes change the conditions
used to to build the network. They can be updated any time but the change will
only take place after rebooting so that the network is forced to be rebuilt.
- 0x001D (PIB_MAC_SAR_SIZE)
- 0x004A (PIB_MAC_ACTION_ROBUSTNESS_MGMT)
- 0x8133 (PIB_MAC_ACTION_CFG_BCN_TX_SCHEME)
- 0x8136 (PIB_MAC_ACTION_CFG_BCN_SWITCH_RATE)
- 0x8137 (PIB_MAC_ACTION_CFG_SEC_PROF)
Other coding requirements
The following requirements must be taken into account for a proper system
performance:
- Avoid invoking a request function inside a callback function. This increases the call stack size and may provoke endless loops. For example, do not request to send data in the same callback function that handles the confirm of a data request.
- In a Base Node, avoid invoking a request to a node if the previous confirm has not been received yet, if the connection is being closed or if there has been a reset.
- Set to NULL all unused callback function pointers.
- Provide the callback function pointers again after an MLME_RESET.confirm primitive.
- Do not modify the functions and parameters in the PRIME API and the HAL API.
- Give a MAC address to the board. If the PRIME Library cannot find a MAC address, it enters into MTP mode.
- Give a DUK to the Service Node when security has been configured. If the PRIME Library cannot find a DUK, it enters into MTP mode.
- In a Service Node, do not reset the software in the function that receives the result of the FU process. The reset must take place in a user task.
- In a Service Node, do not reset the software or change the PRIME API pointer in the function that requests a swap of the PRIME Library versions. The reset or pointer change must take place in a user task.
- Define an exclusive serial port number for the Serial Communication Profile of the Management Plane (only required for PRIME certification of a Service Node). In PRIME v1.3, the baud rate must be set to 57600 bauds.
- Initialize and refresh the watchdog to avoid hangings of any application during execution.
- Use the supply monitor controller, if available in the board, to avoid malfunctions.