3 Microchip PRIME Network Manager Application

The PRIME Network Manager application example explained in this application note is included in the usi-host-v2.2.2 package. It implements a basic Command Line Interface (CLI) for managing and monitoring a PRIME Network running over the Base Node Modem project present on PRIME 1.4 Firmware Stack package.

The PRIME Network Manager can be used for:
  • PIB management: get counters and modify PRIME standard and manufacturer stack settings
  • Testing embedded firmware: check the correct behavior of the embedded PRIME Base Node modem project
  • Firmware upgrade of the network
It includes other capabilities like:
  • Trace Logging: to debug and trace the program execution
  • Configuration based on a file: to save and restore configurations without recompilation
  • Local (file) / Remote (proxy) sniffing capabilities: to monitor the PRIME network in real time or save the information for further analysis.
  • Network Events saved on SQLite database: to save network events (registrations, promotions...) for further analysis
  • Simple CLI update: to add new commands in a simple way

This application uses the USI Host API to interact with the Base Node Modem; therefore, before continuing, read the documentation carefully for the PRIME Base Stack and USI Host for further information on the PRIME Serialization protocols and USI interface.

The application is structured according to the USI Host serialization, so, the first step requires you to consider the following points:

  • USI Project Configuration (PrjCfg.h file): definitions required to enable PROTOCOL_PRIME_API, PROTOCOL_PRIME_SNIFFER and PROTOCOL_PRIME_MNG and serial port configuration to especific serial port with speed 115200 bps. Serial port selection will be overwritten with a specific command.
  • USI user functions: implement the functions addUsi_Open(), addUsi_TxMsg() and addUsi_RxChar(), which are required for the USI implementation.
  • Call the USI host processing periodically (addUsi_Process() function). In this example, an independent thread in the Linux operating system calls “usi_process_thread()” every 1 millisecond. It could be improved using a select on serial port file descriptor.
  • Synchronous mechanism implementation for PRIME API requests defining the addUsi_WaitProcessing() function with a “while loop” with timeout. This is not a problem working in Linux running a multi-process environment but could be improved using events.
The second step working with USI Host serialization is to identify which files are involved in the interface of the application:
  • The src\ifacePrime_api.c supports the serialization of the PRIME API primitives for interacting with the PRIME Base Node Modem embedded project; it contains the functions and callbacks available for the USI protocol PROTOCOL_PRIME_API. This protocol includes the full functionalities needed to handle the Microchip PRIME Stack.
  • The src\ifaceMngLayer.c refers to the different protocols defined in the Serial Communication Profile of the Management Plane described in the PRIME Specification and corresponds with the USI protocols PROTOCOL_MNGP_PRIME_XXX.
  • The src\ifacePrimeSniffer.c supports the serialization of the PRIME FW Stack in terms of received PLC traffic from the PRIME Network.

The third step is to implement additional features for the board support package (BSP):

  • Use of the Linux SYS Filesystem to act over microprocessor GPIOs (primeBN_linux\source\port\common\gpio.c) and LEDs (primeBN_linux\source\port\common\led.c)

Finally, the structure of the example itself includes these files:

  • userFnc.c: specific implementation of user USI functions for this application
  • primeBN_linux\base_node_dlmsotcp.[c,h]: DLMS over TCP functionality
  • primeBN_linux\prime_sniffer.[c,h]: Sniffer capabilities in the Base Node, they include:
    • Logging to a file: on ATPL format, can be imported on the PLC Sniffer Tool
    • Logging to a TCP Server: for a connection from the PLC Sniffer Tool (only accepts 1 connection)
  • primeBN_linux\prime_log.[c,h]: Logging capabilities on a file (the default filepath is /tmp/prime.log). There are four levels of messages depending on the relevance:
    • LOG_INFO: Information messages about normal execution of the application
    • LOG_ERR: Information about errors on application execution
    • LOG_DBG: Debugging information for greater knowledge of application execution
    • LOG_WARN: Warning messages
  • primeBN_linux\return_codes.h: Common return values
  • primeBN_linux\prime_utils.[c,h]: useful functions common to the whole application
  • primeBN_linux\base_node_network.[c,h]: functions for saving information about what is happening on the PRIME network:
    • Registered device information
    • MAC connections information
    • 4-32 CL connections information
  • primeBN_linux\prime_bmng_network_events.[c,h]: network events callback to save them in a SQLITE3 database (the default filepath is /etc/config/prime_network_events.sql)
  • primeBN_linux\base_node_mng_fw_upgrade.[c,h]: functions related to the network firmware upgrade
  • primeBN_linux\base_node_mng.[c,h]: callback functions definitions
  • primeBN_linux\base_node_vty.[c,h]: specific commands for this application