Jump to main content

# 1.2.6.2 Using the Library

USI is a service that allows to send/receive messages to/from an external tool. It is used in conjunction with another Smart Energy libraries to serialize different protocol layers.

Following example illustrate how to use the USI library along with PLC PHY driver and PLC PHY Serial service to serialize the PLC PHY API.

Example implementation of a PLC PHY API Serialization

    APP_DATA appData;

    static uint8_t pPLCDataTxBuffer[APP_PLC_DATA_BUFFER_SIZE];
    static uint8_t pPLCDataRxBuffer[APP_PLC_DATA_BUFFER_SIZE];
    static uint8_t pPLCDataPIBBuffer[APP_PLC_PIB_BUFFER_SIZE];
    static uint8_t pSerialDataBuffer[APP_SERIAL_DATA_BUFFER_SIZE];

    /* PLC Data Indication Callback */
    static void APP_PLCDataIndCb(DRV_PLC_PHY_RECEPTION_OBJ *indObj, uintptr_t context)
    {
        /* Send Received PLC message through USI */
        if (indObj->dataLength)
        {
            size_t length;

            /* Serialize received message */
            length = SRV_PSERIAL_SerialRxMessage(appData.pSerialData, indObj);
            /* Send through USI */
            SRV_USI_Send_Message(appData.srvUSIHandle, SRV_USI_PROT_ID_PHY,
                    appData.pSerialData, length);
        }
    }

    /* PLC Data Confirm Callback */
    static void APP_PLCDataCfmCb(DRV_PLC_PHY_TRANSMISSION_CFM_OBJ *cfmObj, uintptr_t context)
    {
        size_t length;

        appData.plcTxState = APP_PLC_TX_STATE_IDLE;

        /* Serialize received message */
        length = SRV_PSERIAL_SerialCfmMessage(appData.pSerialData, cfmObj);
        /* Send through USI */
        SRV_USI_Send_Message(appData.srvUSIHandle, SRV_USI_PROT_ID_PHY,
                appData.pSerialData, length);

    }

    /* USI packet received Callback */
    void APP_USIPhyProtocolEventHandler(uint8_t *pData, size_t length)
    {
        /* Message received from PLC Tool - USART */
        SRV_PSERIAL_COMMAND command;

        /* Process received message */
        command = SRV_PSERIAL_GetCommand(pData);

        switch (command) {
            case SRV_PSERIAL_CMD_PHY_GET_CFG:
            {
                /* Extract PIB information */
                SRV_PSERIAL_ParseGetPIB(&appData.plcPIB, pData);

                if (DRV_PLC_PHY_PIBGet(appData.drvPl360Handle, &appData.plcPIB))
                {
                    size_t len;

                    /* Serialize PIB data */
                    len = SRV_PSERIAL_SerialGetPIB(appData.pSerialData, &appData.plcPIB);
                    /* Send through USI */
                    SRV_USI_Send_Message(appData.srvUSIHandle, SRV_USI_PROT_ID_PHY,
                            appData.pSerialData, len);
                }
            }
            break;

            case SRV_PSERIAL_CMD_PHY_SET_CFG:
            {
                /* Extract PIB information */
                SRV_PSERIAL_ParseSetPIB(&appData.plcPIB, pData);

                if (DRV_PLC_PHY_PIBSet(appData.drvPl360Handle, &appData.plcPIB))
                {
                    size_t len;

                    /* Serialize PIB data */
                    len = SRV_PSERIAL_SerialSetPIB(&appData.pSerialData[1], &appData.plcPIB);
                    /* Send through USI */
                    SRV_USI_Send_Message(appData.srvUSIHandle, SRV_USI_PROT_ID_PHY,
                            appData.pSerialData, len);
                }
            }
            break;

            case SRV_PSERIAL_CMD_PHY_SEND_MSG:
            {
                /* Set PLC TX State to wait Tx confirmation */
                appData.plcTxState = APP_PLC_TX_STATE_WAIT_TX_CFM;

                /* Capture and parse data from USI */
                SRV_PSERIAL_ParseTxMessage(&appData.plcTxObj, pData);

                /* Send Message through PLC */
                DRV_PLC_PHY_Send(appData.drvPl360Handle, &appData.plcTxObj);
            }
            break;

            default:
                break;
        }
    }

    void APP_Initialize(void)
    {
        /* Place the App state machine in its initial state. */
        appData.state = APP_STATE_INIT;

        /* Initialize PLC buffers */
        appData.plcTxObj.pTransmitData = pPLCDataTxBuffer;
        appData.plcRxObj.pReceivedData = pPLCDataRxBuffer;
        appData.plcPIB.pData = pPLCDataPIBBuffer;
        appData.pSerialData = pSerialDataBuffer;

        /* Init PLC TX status */
        appData.plcTxState = APP_PLC_TX_STATE_IDLE;
    }

    void APP_Tasks(void)
    {
        /* Check the application's current state. */
        switch(appData.state)
        {
            /* Application's initial state. */
            case APP_STATE_INIT:
            {
                /* Open PLC driver : Start uploading process */
                appData.drvPl360Handle = DRV_PLC_PHY_Open(DRV_PLC_PHY_INDEX, NULL);

                if (appData.drvPl360Handle != DRV_HANDLE_INVALID)
                {
                    /* Set Application to next state */
                    appData.state = APP_STATE_REGISTER;
                }
                else
                {
                    /* Set Application to ERROR state */
                    appData.state = APP_STATE_ERROR;
                }
                break;
            }

            /* Waiting to PLC transceiver be opened and register callback functions */
            case APP_STATE_REGISTER:
            {
                /* Check PLC transceiver */
                if (DRV_PLC_PHY_Status(DRV_PLC_PHY_INDEX) == SYS_STATUS_READY)
                {
                    /* Register PLC callback */
                    DRV_PLC_PHY_ExceptionCallbackRegister(appData.drvPl360Handle,
                            APP_PLCExceptionCb, DRV_PLC_PHY_INDEX);
                    DRV_PLC_PHY_DataIndCallbackRegister(appData.drvPl360Handle,
                            APP_PLCDataIndCb, DRV_PLC_PHY_INDEX);
                    DRV_PLC_PHY_DataCfmCallbackRegister(appData.drvPl360Handle,
                            APP_PLCDataCfmCb, DRV_PLC_PHY_INDEX);

                    /* Open USI Service */
                    appData.srvUSIHandle = SRV_USI_Open(SRV_USI_INDEX_0);

                    if (appData.srvUSIHandle != DRV_HANDLE_INVALID)
                    {
                        /* Set Application to next state */
                        appData.state = APP_STATE_CONFIG_USI;
                    }
                    else
                    {
                        /* Set Application to ERROR state */
                        appData.state = APP_STATE_ERROR;
                    }
                }
                break;
            }

            case APP_STATE_CONFIG_USI:
            {
                if (SRV_USI_Status(appData.srvUSIHandle) == SRV_USI_STATUS_CONFIGURED)
                {
                    /* Register USI callback */
                    SRV_USI_CallbackRegister(appData.srvUSIHandle,
                            SRV_USI_PROT_ID_PHY, APP_USIPhyProtocolEventHandler);

                    /* Set Application to next state */
                    appData.state = APP_STATE_CONFIG_PLC;
                }
                break;
            }

            case APP_STATE_CONFIG_PLC:
            {
                /* Set PLC configuration (differs from G3 to PRIME) */
                /* ... */
                /* Set Application to next state */
                appData.state = APP_STATE_READY;
                break;
            }

            case APP_STATE_READY:
            {
                /* Check USI status in case of USI device has been reset */
                if (SRV_USI_Status(appData.srvUSIHandle) == SRV_USI_STATUS_NOT_CONFIGURED)
                {
                    /* Set Application to next state */
                    appData.state = APP_STATE_CONFIG_USI;
                }

                /* Else just wait for events to trigger callbacks */

                break;
            }

            case APP_STATE_ERROR:
            {
                /* Handle error in application's state machine */
                break;
            }

            /* The default state should never be executed. */
            default:
            {
                break;
            }
        }
    }

Rev: G