ad-sm2400ap05a-pwrln application note · 27/07/2016 · 2.15 smp_man_node_add adds a node to the...

AD-SM2400AP05A-PWRLN

SMESH User Application API for SM2400 PLC Modem

Revision 1.0

Communication Technology by:Semitech Semiconductor

Application Note

Overview

This application note describes the API function calls for the SMESH User Application.

AD-SM2400AP05A-PWRLN–7/2016

Table of Contents

1. Application Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

2. API Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42.1 SysGetMs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2.2 hostCommsSetCommandCallback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.3 hostCommsSendCommand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.4 schedulerAddTask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.5 SMP_MAN_Task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

2.6 SMP_MAN_Init . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.7 SMP_MAN_UID_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

2.8 SMP_MAN_RegGet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.9 SMP_MAN_RegSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.10 SMP_MAN_RegRestore . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.11 SMP_MAN_RegCommit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.12 SMP_MAN_TX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.13 SMP_MAN_Node_Count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.14 SMP_MAN_GetNodeInfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.15 SMP_MAN_Node_Add . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.16 SMP_MAN_Node_Remove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.17 SMP_MAN_Node_Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.18 SMP_MAN_Reg_State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.19 SMP_MAN_Status_Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.20 SMP_MAN_Status_Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.21 SMESH_Config_XXR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

3. Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

4. Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

2SMESH User Application API AD-SM2400AP05A-PWRLN

1. Application Overview

The SMESH User Application is a configuration allowing customized control of the SMESH mesh networking protocol on the SM2400 modem controller. It makes use of an application programming interface (API) to an SMESH library. These, linked together, form a complete networking controller.

The library is built for either SPI or UART, using the same API calls for both interfaces.


2. API Calls

The API calls are listed in Table 2-1.

2.1 SysGetMs

Retrieves count from a free-running 32-bit millisecond counter.

Table 2-1. SMESH API function calls

Function Description

SysGetMs Reads a millisecond counter

hostCommsSetCommandCallback Sets a callback for incoming serial interface byte sequences

hostCommsSendCommand Sends a byte sequence to serial interface

schedulerAddTask Add task to task scheduler

SMP_MAN_Task SMESH timer task

SMP_MAN_Init Initialize SMESH protocol

SMP_MAN_UID_Get Read SMESH user ID

SMP_MAN_RegGet Read SMESH register

SMP_MAN_RegSet Write SMESH register

SMP_MAN_RegRestore Read SMESH registers from flash

SMP_MAN_RegCommit Write SMESH registers to flash

SMP_MAN_TX Transmit data with SMESH

SMP_MAN_Node_Count Get number of connected nodes (base node only)

SMP_MAN_GetNodeInfo Get node information (base node only)

SMP_MAN_Node_Add Manually add node to network (base node only)

SMP_MAN_Node_Remove Manually remove node from network (base node only)

SMP_MAN_Node_Update Force status update of node (base node only)

SMP_MAN_Reg_State Get registration state (service node only)

SMP_MAN_Status_Get Get node status string (service node only)

SMP_MAN_Status_Set Set node status string (service node only)

SMESH_Config_XXR Configure PHY parameters

Format: uint32_t SysGetMs(void)


2.2 hostCommsSetCommandCallback

Sets a callback for serial input. Byte strings received at the host SPI or UART interface are parsed for the SM2400 serial protocol and the resulting command and payload returned.

2.3 hostCommsSendCommand

Sends a command and payload to the serial interface (SPI or UART), where it first gets packaged according to the SM2400 serial protocol.

2.4 schedulerAddTask

Adds a task to the task scheduler. The task parameters include the task address, a parameter to pass, the number of system ticks between executions (in ms) and the status of the task (enabled or not).

The task structure is defined as follows: struct task{ void (*task)(void *);///< The function that is executed when the task is run. void *parameter; ///< The parameter to pass to the task function. uint16_t period; ///< The number of system ticks between task executions. uint16_t elapsed; ///< The number of system ticks since the last execution. uint8_t state; ///< The task state. Either #TASK_ENABLED or #TASK_DISABLED };

2.5 SMP_MAN_Task

The SMESH management task. This task is called by the task manager by default and the application normally does not need to call it.

Format:

void hostCommsSetCommandCall9back(SMP_Command_Input_FUNC cb)

void (*SMP_Command_Input_FUNC)(uint16_t cmd, uint8_t* payload, uint16_t length)

Format: bool hostCommsSendCommand(uint32_t cmd, uint8_t *data, uint16_t len)

Format: int schedulerAddTask(struct task *taskToAdd)

Format: void SMP_MAN_Task(void *p)


2.6 SMP_MAN_Init

Intializes the SMESH controller and starts the network in the case of a base node, or starts attempting to register in the case of a service node.

Parameters are passed through two structures, one with the configuration and the other with callback addresses. The two structures are defined as follows:

typedef struct SMP_CONFIG { uint32_t uid; /* The UID used for this instance */ uint16_t *registers; /* Ptr to the registers used (NULL uses defaults)*/ SMP_Error_FUNC errorHandler; /* function to handle unrecoverable errors */ SMP_GetMSTick_FUNC systemTicker; /* Ptr to System Tick Timer (ms) */ }SMP_CONFIG;

And for base node: typedef struct SMP_CALLBACKS { SMP_Data_Indication_CallBack_FUNC smeshDataInd;// Callback for transmit SMP_Data_Confirm_CallBack_FUNC smeshDataCon; // Callback to obtain TX State SMP_STATUS_TSK_FUNC statusUpdate; // Fn to provide the status info }SMP_CALLBACKS;

For service node: typedef struct SMP_CALLBACKS { SMP_Data_Indication_CallBack_FUNC smeshDataInd; // For data transmit SMP_Data_Confirm_CallBack_FUNC smeshDataCon; // To obtain TX State SMP_STATUS_TSK_FUNC statusUpdate; // To provide the status info SMP_Register_Indication_CallBack_FUNC smeshRegInd; // Indicate registration event SMP_Unregister_Indication_CallBack_FUNC smeshUnregInd; // Indicate de-registration }SMP_CALLBACKS;

2.7 SMP_MAN_UID_Get

Returns the UID being used. nodeID_t is defined as uint32_t.

Format: uint32_t SMP_MAN_Init(SMP_CONFIG* smpInitConfig, SMP_CALLBACKS* callBacks)

Format: nodeID_t SMP_MAN_UID_Get(void)


2.8 SMP_MAN_RegGet

Reads a register value.

2.9 SMP_MAN_RegSet

Sets a register value. Returns zero.

2.10 SMP_MAN_RegRestore

Restores register values from flash. Returns true if successful, false if it failed.

2.11 SMP_MAN_RegCommit

Writes current register values to flash. Returns true if successful, false if it failed.

2.12 SMP_MAN_TX

Transmits data using the SMESH protocol.

2.13 SMP_MAN_Node_Count

Returns the number of registered nodes.

This function is only available for the base node.

2.14 SMP_MAN_GetNodeInfo

Reads the connection information for a set of registered nodes. The data is read from up to 10 nodes at a time. The first byte of the returned data contains the batch number of the information (0 for first set of 10, 1 for second etc). Following are 8 bytes for each node, 4 for the node UID and 4 for the UID of its connection point.

Returns the number of bytes returned.


Format: uint16_t SMP_MAN_RegGet(uint8_t reg)

Format: uint32_t SMP_MAN_RegSet(uint8_t reg, uint16_t value)

Format: bool SMP_MAN_RegRestore()

Format: bool SMP_MAN_RegCommit()

Format: uint32_t SMP_MAN_TX (nodeID_t address, uint8_t *data, uint16_t len)

Format: uint8_t SMP_MAN_Node_Count(void)

Format: uint32_t SMP_MAN_GetNodeInfo(uint8_t groupOffset, uint8_t* dstBuffer)


2.15 SMP_MAN_Node_Add

Adds a node to the network. Returns 0 for success, nonzero for error.


2.16 SMP_MAN_Node_Remove

Removes a node from the network. Returns 0 for success, nonzero for error.


2.17 SMP_MAN_Node_Update

Forces a status update on a node. Returns 0 for success, nonzero for error.


2.18 SMP_MAN_Reg_State

Returns the registration state of a node. If it is registered it returns the UID of the gateway it is registered with. If it is not registered it returns 0.

This function is only available for service nodes.

2.19 SMP_MAN_Status_Get

Retrieves the status string of the node.


2.20 SMP_MAN_Status_Set

Sets the status string of the node.


Format: uint32_t SMP_MAN_Node_Add(nodeID_t nodeID, nodeID_t nextHopUID)

Format: uint32_t SMP_MAN_Node_Remove(nodeID_t nodeID)

Format: uint32_t SMP_MAN_Node_Update(nodeID_t nodeID)

Format: nodeID_t SMP_MAN_Reg_State(void)

Format: void SMP_MAN_Status_Get(uint8_t *data, uint8_t *len)

Format: void SMP_MAN_Status_Set(uint8_t *data, uint8_t len)


2.21 SMESH_Config_XXR

Sets the PHY configuration of a node. The parameters are defined in Table 2-2.

Format:bool SMESH_Config_XXR(uint8_t config, uint8_t subCar0, uint8_t subCar1, uint8_t subCar2, uint8_t subCar3)

Table 2-2. Parameters for SMESH_Config_XXR

Parameter Description

config

bits 0:3 Redundancy

bit 4 Band in use, 0: 250kHz, 1: 500 kHz

bit 5 Sequence number enabled

bit 6 Forward error correction enabled

bit 7 Long cyclic prefix enabled

subCar0 First subcarrier ID

subCar1 Second subcarrier ID, 0 if not used

subCar2 Third subcarrier ID, 0 if not used

subCar3 Fourth subcarrier ID, 0 if not used


3. Contact Information

For more information regarding the SM2400EVK1 including application notes, product samples, demonstration modules, pricing and ordering please contact:

Adesto Technologieshttp://www.adestotech.com

Communication technology by:Semitech Semiconductor

4. Revision History

Table 4-1. Revision history

Version Description Date

1.0 First publication 7/27/2016


This page intentionally blank

Corporate Office

©2016 Adesto Technologies. All rights reserved. / Rev.: PB2480A–PWRLN–5/2016

Disclaimer: Adesto Technologies Corporation makes no warranty for the use of its products, other than those expressly contained in the Company's standard warranty which is detailed in Adesto's Terms and Conditions located on the Company's web site. The Company assumes no responsibility for any errors which may appear in this document, reserves the right to change devices or specifications detailed herein at any time without notice, and does not make any commitment to update the information contained herein. No licenses to patents or other intellectual property of Adesto are granted by the Company in connection with the sale of Adesto products, expressly or by implication. Adesto's products are not authorized for use as critical components in life support devices or systems.

California | USA

Adesto Headquarters

3600 Peterson WaySanta Clara, CA 95054

Phone: (+1) 408.400.0578

Email: [email protected]

ad-sm2400ap05a-pwrln application note · 27/07/2016 · 2.15 smp_man_node_add adds a node to the...

Documents