1.3.3 How the PRIME Library works

The PRIME Library is the access point to the PRIME Stack. It contains the MAC layer, the Convergence Layer and the Management Plane as described in the PRIME specification. In a Base Node, it also includes a proprietary Base Management module to handle the interface between the Base Node and the DCU user application and enhance it with additional functionalities.

The PRIME library has two interfaces: one towards the user application and another towards the H3 ecosystem.

PRIME API

The PRIME API is the only interface that the user application must use to interact with the PRIME Stack. It is stored in the prime_api pointer and contains the interfaces defined in the PRIME specification as well as stack control functions.

The PRIME API is based on a request/confirm mechanism, which is a particular instance of an event-driven programming model. A request is an asynchronous call to the underlying stack to perform some action on behalf of the user application; a confirm is the callback that executes when that action has been completed and the result of that action is available.

Apart from request/confirm pairs, there are cases when the application needs to be notified of an external event that is not a reply to any specific request. For this, there are a number of user-defined callbacks named indications that are invoked by the stack asynchronously. Note that during the execution of an indication callback, it is not permitted to invoke any requestas this could lead to the generation of a callback chain.

Callback functions must be registered in the PRIME Library by the user application upon initialization.

This pointer must be obtained by the user application at initialization.

HAL API

The HAL (Hardware Abstraction Layer) API manages the interface to the required drivers and services in the Harmony 3 ecosystem as well as to the PRIME PAL module. The functions in the HAL API are based on the definitions of the functions in the drivers, services and PRIME PAL module which are required by the PRIME Library. For more information see HAL API.

This pointer must be passed to the PRIME Library at initialization.

One of the most important features of the PRIME implementation is its ability to manage the PRIME Library and the user application as separate software modules. The corresponding binary images can be allocated to any memory addresses configured by the user, thus providing a highly flexible and versatile implementation. The PL360 firmware also requires a separate memory section. There is no need to allocate space for the RF firmware as it is already stored in the AT86RF215 mode.

The PRIME Library for PRIME v1.4 requires a minimum size of 136kB for its memory sector in ROM and a minimum size of 44kB of RAM. The PRIME Library for PRIME v1.3.6 requires a minimum size of 128kB for its memory sector in ROM and a minimum size of 32kB of RAM. Additionally, the PL360 firmware with single channels requires a minimum size of 64kB for its memory sector in ROM, while the PL360 firmware with double channels requires a minimum size of 96kB for its memory sector in ROM.

The allocation address of the PRIME Library is defined and managed by the user application as well as the addresses of other modules, as described in Configuring The PRIME Stack. The memory addresses and sizes are defined in the linker scripts that go with the application examples, which also include the RAM allocation.

The default memory allocation and RAM allocation are shown in the following figures:

First of all, the PRIME Library has to be initialized at System level by calling PRIME_Initialize to get an object identifier of the library instance. As stated, this function is called at System level, so the user does not need to take care of it. Note that this initialization function provides the HAL API pointer to the PRIME Library. Within this function and through the HAL API, the PRIME Library triggers the initialization of the PAL.

The first step a customer has to take is to get the PRIME API pointer. This is done by means of function PRIME_API_GetPrimeAPI in a Base Node application. In a Service Node, depending on the PRIME version stored in non-volatile memory, the function to use is either PRIME_API_GetPrime13API or PRIME_API_GetPrime14API. Through this pointer the user can invoke the functions defined in the PRIME API and handled in the PRIME Library.

Secondly, the user has to ensure the PRIME Library is ready (i.e. has finished its initialization duties). This is done by means of the Status function in the PRIME API, which returns the internal Status of the PRIME Library. When Status is equal to SYS_STATUS_READY, the module is ready to be used.

Finally, the user has to set the callback functions to receive events from the PRIME Library. This is done be means of the following functions in the PRIME API: MacSetCallbacks, Cl432SetCallbacks and BmngSetCallbacks (only Base Node), which take pointers to such callback handlers as parameter.

The PRIME Library State Machine is called periodically by System though the PRIME_Tasks function. As it is called at System level, client does not need to take care of maintaining the PRIME Library State Machine. Within this function and through the HAL API, the PRIME Library also triggers the state machine maintenance of the PAL.

Every PRIME process is done inside this state machine. Request primitives trigger State Machine changes, and then internal processes trigger in turn the callbacks to report different events to the PRIME user.

Parameter Information Base (PIB) is a set of parameters that can be accessed for reading and/or writing. They serve mainly two purposes: PRIME Library configuration through PIB writing, and information retrieval through PIB reading.

The reading of parameters is made by means of PRIME API functions PlmeGetRequest and MlmeGetRequest, while the writing is made through PRIME API functions PlmeSetRequest and MlmeSetRequest. The reading of lists takes place with PRIME API function MlmeListGetRequest.

The result of these operations is provided by means of the callback functions plme_get_cfm, mlme_get_cfm, plme_set_cfm, mlme_set_cfm, and mlme_list_get_cfm, respectively.

A list of available parameters is provided in file mac_pib.h. For description of proprietary PIBs see Proprietary PIB Attributes.

Users are free to use the provided specific convergence sublayers or access the MAC layer directly to establish a MAC connection to exchange data between application peers. Such connections can be made between a Base Node and a Service Node or between two Service Nodes (i.e. a direct connection). Refer to PRIME specification for detailed information about the semantics of the primitives available in the MAC service access point.

All requests to exchange data are followed by a confirm and the user application must always wait for it before performing a new request. The confirm can be immediate or be delayed for a considerable amount of time. For communications with ARQ, the invocation of the confirm callback could take up to several minutes.

The user can directly access the MAC layer though the Null SSCS signalling and data primitives. In PRIME v1.4, the data exchange with MAC primitives can be enhanced by using a time reference. Microchip recommends obtaining the local time with function PAL_GetTimer. Note that the time units returned by this function are microseconds, whereas the time units of the time reference must be tenths of microsecond.

The user can also make use of the IEC 61334-4-34 primitives to access the IEC-61334-4-32 compliant SSCS.

Regarding ARQ, the PRIME Library only supports windowed ARQ with a window size fixed to 4.

When a Service Node detects traffic from a different stack version, the PRIME Library uses the HAL API to notify it with function SRV_FU_RequestSwapVersion in the Firmware Upgrade service, indicating the type of the detected traffic. If a user wants to be notified about this in the application, it must set a callback in the Firmware Upgrade service with function SRV_FU_RegisterCallbackSwapVersion.

The PRIME Library implements the PRIME FU process as described in the PRIME specification. However, the handling of system requirements and hardware resources belongs entirely to the user application.

In order to upgrade any binary (new image of the PRIME Library, new image of the PL360 firmware, new image of the user application), Microchip provides an example where it is only needed to reserve one memory region, which will first store the new image and, after the restart, the previous binary. The PRIME Library is only responsible for managing the FU process as described in the PRIME specification, whereas the user application is responsible for handling the pointers to these regions and managing the indications received in the Firmware Upgrade service. Additionally, a complete system restart is required when the FU process finishes so that the bootloader application moves the received binary to its right location and keeps the previous binary for a possible revert.

Moreover, since the PRIME Library does not control what kind of file is being received, the user application can also use the PRIME FU process to transfer files. In this case, users need to define a memory area to store the received file. Later, when the FU process finishes, the user application decides what to do with this file.

According to the PRIME specification, where it is assumed that the FU process is only used to upgrade the PRIME stack, the FU process does not end until the sent file is confirmed, i.e. regardless of the type of received file, the PRIME Library must always be restarted so that the FU process finishes properly.

The FU process in the PRIME Library only checks the integrity and authentication of the received file using the file CRC and signature (only in PRIME v1.4). It does not perform any check on the validity of this file for a potential upgrade. It is recommended that the user application performs its own validation by means of checking any metadata contents in the received file. It is up to the users to define how to check them. For instance, in the PRIME Library binary file, the first 20 bytes contain the Vendor, Model and Version information. It is recommended to only accept binary files with matching Vendor and Model (as set in during configuration, see PRIME FW version information). The Firmware Upgrade service is performing such check. Furthermore, in the provided examples, the last 16 bytes of any binary file (before the signature) are expected to include an identifier of the file being upgraded or transferred (identifiers set during configuration, see PRIME Firmware Upgrade Configuration).

The FUP defines the steps required to set up and initiate a firmware upgrade in a PRIME network and also monitor the upgrade process from the Base Node. The PRIME Library implements the PRIME FU process as described in the PRIME specification.

The FUP is divided into the following stages:

• Setup: The DCU user application indicates to the PRIME Library which Service Nodes must be upgraded and configures the upgrade options.
• File transfer: The DCU user application sends the binary file to the PRIME Library.
• Firmware upgrade: The PRIME Library proceeds with the firmware upgrade as defined in the PRIME specification.

Setup Stage

The DCU user application must execute the next sequence of actions:

1. Configure the FUP options: ARQ, Multicast, Page Size, Delay Restart and Safety Timer.
2. Clear the BN’s target list.
3. Add device targets from the list of registered devices in the BN. Devices are added one-by-one.
4. Configure the upgrade rule: select which nodes will be upgraded based on their Vendor/Model.
5. Set the new firmware version information: Vendor, Model and Version.
6. Set the signature information: used algorithm and signature length (only PRIME v1.4).

Unregistered Service Nodes that have been registered previously can also be added to the FU list. When they register again, they will be automatically added to the FU process by the Base Node.

File Transfer Stage

After the initialization request, the file is sent to the Base Node in fragments of fixed length, the indicated frame size. Each fragment contains part of the file and must be acknowledged by the Base Node before sending the next fragment. A fragment of smaller size than the frame size signals the termination of the file transfer. If the last fragment has the same length as the fragment size, the DCU user application must send a fragment of size zero, as indicated in the TFTP protocol.

After the file transfer is completed, the Base Node computes the PRIME CRC-32 of the received file through the PCRC service. This CRC-32 is compared to the value received in the initialization message. The DCU user application must ask the Base Node for the result. If it is not correct, the upgrade is cancelled by the Base Node.

Users are responsible for reserving a memory area with enough space to store the firmware file.

Firmware Upgrade Stage

If the previous stages have been completed correctly, it is safe to trigger the FU process with function BMNG_FUP_StartFuRequest. During this stage, the Base Node follows the process defined by the PRIME specification to upgrade the firmware in the Service Nodes.

Once the FU stage has started, the DCU user application can cancel the FU process any time with function BMNG_FUP_AbortFuRequest. The cancellation can apply to all Service Nodes or just to a certain Service Node. New Service Nodes can also be added to the FU process any time with the function BMNG_FUP_AddTargetRequest described in the setup stage. All these requests are acknowledged by the function fup_ack.

Furthermore, the DCU user application can also request the version (BMNG_FUP_GetVersionRequest) and FU state (BMNG_FUP_GetStateRequest) of any Service Node. The response to these functions is received in the corresponding indication callback functions: fup_version_ind and fup_status_ind.

The Base Node notifies about asynchronous events related to the Service Nodes whenever the corresponding callback function in the PRIME API (network_event_ind, defined in the Base Management) has been set up by the user application. The events indicated by the Base Node are the following:

• State changes in the Service Node:
  • registration (BMNG_NET_EVENT_REGISTER)
  • unregistration (BMNG_NET_EVENT_UNREGISTER)
  • promotion (BMNG_NET_EVENT_PROMOTE)
  • demotion (BMNG_NET_EVENT_DEMOTE)
• Alive events (BMNG_NET_EVENT_ALIVE): whenever the Base Node receives an alive message from a Service Node.
• Reboot events (BMNG_NET_EVENT_REBOOT): whenever the PRIME Library is started in the Base Node.
• No DUK events (BMNG_NET_EVENT_NO_DUK): whenever the Base Node receives a registration message from a Service Node of which it does not have its corresponding DUK. This only applies when the security profile is 1 or 2 (in PRIME v1.4).
• Unknown Service Node (BMNG_NET_EVENT_UNKNOWN_NODE): whenever the Base Node receives a registration message from a Service Node which is not included in the whitelist. This only applies when the whitelist mechanism is enabled.

The PRIME Profile is a communication protocol in the Management Plane that permits the DCU user application to manage a remote Service Node through PRIME standard and Microchip-defined PIBs. This communication profile is defined in the PRIME specification, but the interface to the DCU user application is not. Therefore, Microchip has defined a proprietary API to allow access to the PRIME Profile in the Management Plane. This API with its corresponding primitives and callback functions is defined in Base Management Functions.

This API has been enhanced with a request to calculate the difference between the zero cross times in the Base Node and a Service Node, which is useful in a phase detection algorithm.

When the user application has enabled the use of the whitelist mechanism via the Microchip defined PIB PIB_MAC_WHITELIST_ENABLED (0x8151), the whitelist management interface of the Base Management allows addition and removal of Service Nodes to the whitelist. This API with its corresponding primitives and callback functions is included in the PRIME API.

By default, the use of the whitelist is disabled. When it is enabled by the user application, all Service Nodes that were already registered are automatically added to the whitelist.

When a Service Node is removed from the whitelist, it is also unregistered from the network.

In PRIME v1.4, when the security profile is 1 or 2, apart from the whitelist, the Base Node also needs to have the DUK of the Service Node that wants to register. If the Service Node has been added to the whitelist but it has not been assigned a DUK, it will not register. When a DUK is added via the Microchip defined PIB PIB_MAC_SEC_DUK_BN (0x8140), the MAC address corresponding to that DUK is automatically added to the whitelist. When a Service Node is removed from the whitelist, its DUK is automatically removed, too.