embeNET Node API

Table of contents Table of contents

Detailed Description

This page documents the embeNET Node C API. The API consists of the following parts:

Stack management
EMBENET_NODE_Init Initializes the node network process.
EMBENET_NODE_Deinit Deinitializes the node network process.
EMBENET_NODE_Proc Advances (runs) the node network process.
Network management
EMBENET_NODE_Join Makes the node join the network.
EMBENET_NODE_QuickJoin Makes the join the network using previously negotiated credentials for quicker join.
EMBENET_NODE_Leave Makes the node leave the network.
EMBENET_NODE_GetUID Gets own unique identifier.
EMBENET_NODE_SetUID Sets own unique identifier.
EMBENET_NODE_GetBorderRouterAddress Gets the IPv6 address of the border router.
EMBENET_NODE_GetParentAddress Gets the IPv6 link-local address of the parent node.
EMBENET_NODE_ForceParentChange Forces parent change.
EMBENET_NODE_RootStart Starts operation as a root node.
Group management
EMBENET_NODE_JoinGroup Makes the node join a specific group.
EMBENET_NODE_LeaveGroup Makes the node leave a specific group.
EMBENET_NODE_GetGroupCount Gets the number of groups the node belongs to.
EMBENET_NODE_GetGroupByIndex Gets the group number by index.
Task management
EMBENET_NODE_TaskCreate Creates a task that can be scheduled.
EMBENET_NODE_TaskDestroy Destroys a previously created task.
EMBENET_NODE_TaskSchedule Schedules a task.
EMBENET_NODE_TaskCancel Cancels a scheduled task.
EMBENET_NODE_GetLocalTime Gets current local node time.
EMBENET_NODE_GetNetworkTime Gets current network time.
EMBENET_NODE_GetNetworkAsn Gets current Absolute Slot Offset
Utility functions
EMBENET_NODE_GetRandomValue Gets a random value

Refer to embeNET Node User Guide for information on how to use the API.

Data Structures

struct  EMBENET_NODE_Config
 
struct  EMBENET_NODE_EventHandlers
 Structure holding embeNET Node stack event handlers. More...
 

Macro Definition Documentation

◆ EMBENET_TASKID_INVALID

#define EMBENET_TASKID_INVALID   SIZE_MAX

Typedef Documentation

◆ EMBENET_TaskId

typedef size_t EMBENET_TaskId

Identifier of an application-level task running within the stack.

◆ EMBENET_NODE_TaskFunction

typedef void(* EMBENET_NODE_TaskFunction) (EMBENET_TaskId taskId, EMBENET_NODE_TimeSource timeSource, uint64_t t, void *context)

Prototype of user task function that can be scheduled in either local, or network time.

Parameters
[in]taskIdid of the running task
[in]timeSourcetime source for the scheduled task
[in]ttime at which the task was expected to run
[in]contextcontext as provided when the task was created

◆ EMBENET_NODE_OnJoined

typedef void(* EMBENET_NODE_OnJoined) (EMBENET_PANID panId, const EMBENET_NODE_QuickJoinCredentials *quickJoinCredentials)

Event hander that is called when the node joins a given network.

This event handler is called when the node joins a network. The joining process could have been started by either a call to EMBENET_NODE_Join or EMBENET_NODE_QuickJoin. Once this event handler is called, the node is connected to the network identified by the given PANID (Personal Area Network IDentifier). This handler also provides a set of credentials that can be used for quick join (see Quick join).

Parameters
[in]panIdPAN ID of network to which the node has joined.
[in]quickJoinCredentialscredentials negotiated with the border router that can be used for quick rejoin next time

◆ EMBENET_NODE_OnLeft

typedef void(* EMBENET_NODE_OnLeft) (void)

Event hander that is called when the node leaves the network.

This event handler is called when the node leaves a network. This may happen due to the EMBENET_NODE_Leave being called or due to the fact that the network was lost. Either way, if the node wishes to join the network again, it should go through the join or quick join procedure.

◆ EMBENET_NODE_OnJoinAttempt

typedef void(* EMBENET_NODE_OnJoinAttempt) (EMBENET_PANID panId, const void *panData, size_t panDataSize)

Event hander that is called when the node tries to join a network.

This event handler is called when an attempt is made in the stack to join a particular network, identified by the PAN ID identifier. This is mostly for information purposes.

Parameters
[in]panIdPAN ID of network to which the node tries to join.
[in]panDatadata that is propagated by root node in the network, may be NULL
[in]panDataSizesize of that data (0 if data pointer is NULL)

◆ EMBENET_NODE_OnQuickJoinCredentialsObsolete

typedef void(* EMBENET_NODE_OnQuickJoinCredentialsObsolete) (void)

Event hander that is called when the quick join credentials become obsolete.

This event handler is called when the stack detects that the credentials used in the quick join procedure became obsolete. This indicates that these credentials should probably be forgotten and not used anymore.

◆ EMBENET_NODE_DataOnUnregisteredPort

typedef void(* EMBENET_NODE_DataOnUnregisteredPort) (uint16_t port)

Event hander that is called when a UDP datagram was received on an unregistered port.

This event handler is called when a UDP datagram is received but there was no socket associated with the incident port.

Parameters
[in]portport number on which the unexpected datagram was received

Enumeration Type Documentation

◆ EMBENET_NODE_TimeSource

Possible time sources for task scheduling

Enumerator
EMBENET_NODE_TIME_SOURCE_LOCAL 

Local node time.

EMBENET_NODE_TIME_SOURCE_NETWORK 

Network time.

Function Documentation

◆ EMBENET_NODE_Init()

EMBENET_Result EMBENET_NODE_Init ( const EMBENET_NODE_EventHandlers eventHandlers)

Initializes the embeNET networking stack for node.

This function initializes the embeNET networking stack in the node. It reserves and initializes the resources needed for the stack operation. It also initializes the required hardware (BSP). This call starts the local clock in node so that the time returned through a call to EMBENET_NODE_GetLocalTime starts to flow.

Note
After initialization EMBENET_NODE_Proc should be called periodically.

For more information refer to Stack handling

Parameters
[in]eventHandlersstructure, desired handlers may be set
Return values
EMBENET_RESULT_OKif initialization completed successfully
EMBENET_RESULT_INVALID_ARGUMENTif at least one of the input arguments was invalid

◆ EMBENET_NODE_Deinit()

void EMBENET_NODE_Deinit ( void  )

Deinitializes the embeNET networking stack.

This function deinitializes the embeNET networking stack. Once called, all activities within the stack are stopped and all dynamically allocated resources (if any) are freed. In order to use the stack again, one must call EMBENET_NODE_Init.

For more information refer to Stack handling

◆ EMBENET_NODE_Proc()

void EMBENET_NODE_Proc ( void  )

Runs the networking process of the embeNET stack for node.

This function should be called periodically within the main loop of a program (or a thread) after a call to EMBENET_NODE_Init. It advances the networking process that is running in the stack which is responsible for all networking activities. In particular, many event callbacks registered in the stack are called from within the context of this function. This function performs time-invariant operations that may be processed in non-ISR, non-privileged MCU routine.

For more information refer to Stack handling

◆ EMBENET_NODE_Join()

EMBENET_Result EMBENET_NODE_Join ( const EMBENET_NODE_Config config)

Starts the network joining process as a node.

This functions starts the process of joining the node to the network. To join the network the application must provide the configuration structure (see EMBENET_NODE_Config) containing:

  • k1 - common network key
  • psk - pre-shared device-specific key

For more information on joining the network refer to Network handling

Parameters
[in]confignetwork configuration (see EMBENET_NODE_Config)
Return values
EMBENET_RESULT_OKif the joining process has begun successfully
EMBENET_RESULT_INVALID_ARGUMENTif at least one of the input arguments was invalid

◆ EMBENET_NODE_QuickJoin()

EMBENET_Result EMBENET_NODE_QuickJoin ( const EMBENET_NODE_QuickJoinCredentials quickJoinCredentials)

Starts the network joining process as a node using a previously stored EMBENET_NODE_QuickJoinCredentials for quicker join.

This functions starts the process of joining the node to the network using the credentials (EMBENET_NODE_QuickJoinCredentials), that were established during the previous join. Re-using these credentials allows the node to speed up the joining process.

For more information on joining the network refer to Network handling and specifically: Quick join

Parameters
[in]quickJoinCredentialscredentials returned by the EMBENET_NODE_OnJoined callback
Return values
EMBENET_RESULT_OKif the quick joining process has begun successfully
EMBENET_RESULT_INVALID_ARGUMENTif at least one of the input arguments was invalid
EMBENET_RESULT_INVALID_CREDENTIALSif the provided credentials were invalid

◆ EMBENET_NODE_Leave()

EMBENET_Result EMBENET_NODE_Leave ( void  )

Disconnects the node from the network.

This function causes the node to go back to the initialized state, stopping all network activity. If the node was joined to the network then all the tasks that were scheduled in network time get canceled. This call can also be used to stop the on-going joining process.

Returns
This call currently always returns EMBENET_RESULT_OK.

◆ EMBENET_NODE_RootStart()

EMBENET_Result EMBENET_NODE_RootStart ( void const *  panData,
size_t  panDataSize 
)

Starts operation as a root node.

This function causes the node to act as a root node in the network. Once started, such a node is controlled exclusively by an external entity called border router.

During network formation and operation the root node can broadcast additional data to all nodes wishing to join the network. This data can be set using the panData and panDataSize arguments. This data is available in the joining nodes through the EMBENET_NODE_OnJoinAttempt event handler.

Note
This call is only available if the embeNET Node library was build with ROOT_CAPABILITIES enabled
Parameters
[in]panDataadditional network-wide data to pass to each node wishing to join. The network is capable of sending max. 16 Bytes od PAN data
[in]panDataSizesize of the additional network-wide data.
Return values
EMBENET_RESULT_OKif the root operation has started successfully
EMBENET_RESULT_INVALID_ARGUMENTif at least one of the input arguments was invalid
EMBENET_RESULT_ROOT_CAPABILITIES_DISABLEDif the library was built without support for root capabilities

◆ EMBENET_NODE_JoinGroup()

bool EMBENET_NODE_JoinGroup ( EMBENET_GroupId  groupId)

Makes the node join the given multicast group.

The node can belong to many multicast groups. This call is used to join the group with a specific group identifier.

Parameters
[in]groupIdidentifier of the group that the node should join
Return values
trueif the node successfully joined the group
falseotherwise

◆ EMBENET_NODE_LeaveGroup()

void EMBENET_NODE_LeaveGroup ( EMBENET_GroupId  groupId)

Makes the node leave the given multicast group.

The node can belong to many multicast groups. This call is used to leave the group with a specific group identifier.

Parameters
[in]groupIdidentifier of the group that the node should leave

◆ EMBENET_NODE_GetGroupCount()

size_t EMBENET_NODE_GetGroupCount ( void  )

Gets the number of groups the node belongs to.

The node can belong to many multicast groups. Each time the EMBENET_NODE_JoinGroup or EMBENET_NODE_JoinGroup is called, the number of groups the node belongs to may change. This call allows to get the current number of groups the node belongs to. After that the user code may poll each group using the EMBENET_NODE_GetGroupByIndex

Returns
current number of groups the node belongs to

◆ EMBENET_NODE_GetGroupByIndex()

EMBENET_GroupId EMBENET_NODE_GetGroupByIndex ( size_t  index)

Gets the groups the node belongs to by their index.

Parameters
[in]indexgroup index ranging from 0 to EMBENET_NODE_GetGroupCount - 1
Returns
group identifier or EMBENET_GROUPID_INVALID if the index is outside the valid range

◆ EMBENET_NODE_TaskCreate()

EMBENET_TaskId EMBENET_NODE_TaskCreate ( EMBENET_NODE_TaskFunction  taskFunction,
void *  userContext 
)

Registers an application-level task.

This function registers a new application-level task within the networking stack.

Parameters
[in]taskFunctionpointer to a function that will be run as a task
[in]userContextoptional context that will be passed to the taskFunction once it is called
Returns
task identifier or EMBENET_TASKID_INVALID if the task has not been created

◆ EMBENET_NODE_TaskDestroy()

void EMBENET_NODE_TaskDestroy ( EMBENET_TaskId  taskId)

Destroys a task.

Parameters
[in]taskIdtask identifier (as returned by EMBENET_NODE_TaskCreate)

◆ EMBENET_NODE_TaskSchedule()

EMBENET_Result EMBENET_NODE_TaskSchedule ( EMBENET_TaskId  taskId,
EMBENET_NODE_TimeSource  timeSource,
uint64_t  t 
)

Schedules task in time, reschedules if task was already scheduled.

Parameters
[in]taskIdtask identifier (as returned by EMBENET_NODE_TaskCreate)
[in]timeSourcetime source for the scheduled task
[in]ttime expressed in ms
Return values
EMBENET_RESULT_OKif scheduled properly.
EMBENET_RESULT_INVALID_ARGUMENTif at least one of the input arguments was invalid
EMBENET_RESULT_UNABLE_TO_SCHEDULE_IN_THE_PASTif the schedule time is in the past
EMBENET_RESULT_NOT_SYNCHRONIZEDif schedule was requested in network time but the node is not synchronized to the network

◆ EMBENET_NODE_TaskCancel()

EMBENET_Result EMBENET_NODE_TaskCancel ( EMBENET_TaskId  taskId)

Cancels the previously scheduled task.

Note
May be safely called even when task was not scheduled. In such case there is no effect.
Parameters
[in]taskIdtask identifier (as returned by EMBENET_NODE_TaskCreate)
Return values
EMBENET_RESULT_OKif the task canceled properly
EMBENET_RESULT_INVALID_ARGUMENTif at least one of the input arguments was invalid

◆ EMBENET_NODE_GetUID()

EMBENET_EUI64 EMBENET_NODE_GetUID ( void  )

Gets own UID which is an EUI64 address.

Returns
UID or EMBENET_EUI64_INVALID if the UID was not set neither by the underlying hardware nor by the user

◆ EMBENET_NODE_SetUID()

EMBENET_Result EMBENET_NODE_SetUID ( EMBENET_EUI64  uid)

Sets own UID which is an EUI64 address.

This function sets the UID which is used to identify the node in the network. In most cases calling this function directly from application code is not needed, as the UID of the node is normally taken form the underlying hardware platform.

In rare cases however the application may want to control how the UIDs are generated. In such scenarios extreme care should be taken to ensure that the UIDs in nodes are truly unique across all available inventory.

This function should not be called once the networking is engaged (after a call to EMBENET_NODE_Join or EMBENET_NODE_QuickJoin).

◆ EMBENET_NODE_ForceParentChange()

void EMBENET_NODE_ForceParentChange ( void  )

Forces parent change.

This function should be used when QoS highly outreaches the expected level. Eg. when multicast traffic does not work despite all other services works properly.

◆ EMBENET_NODE_GetBorderRouterAddress()

EMBENET_Result EMBENET_NODE_GetBorderRouterAddress ( EMBENET_IPV6 ipv6)

Gets the IPv6 address of the border router, if it is reachable.

This function gets the IPv6 address of the border router that started the network that the node has joined. In vast majority of cases the border router address becomes valid immediately after join.

Parameters
[out]ipv6pointer the location where the IPv6 address will be stored, must not be NULL.
Return values
EMBENET_RESULT_OKif the border router IPv6 address was stored successfully
EMBENET_RESULT_INVALID_ARGUMENTif at least one of the input arguments was invalid
EMBENET_RESULT_UNSPECIFIED_ERRORif the IPv6 was not stored

◆ EMBENET_NODE_GetParentAddress()

EMBENET_Result EMBENET_NODE_GetParentAddress ( EMBENET_IPV6 ipv6)

Gets the link-local IPv6 address of the parent node.

In vast majority of cases the parent address will be valid after node joins network. Parent address may change over time.

Parameters
[out]ipv6pointer the location where the IPv6 address will be stored, must not be NULL.
Return values
EMBENET_RESULT_OKif parent's IPv6 address was stored successfully
EMBENET_RESULT_INVALID_ARGUMENTif at least one of the input arguments was invalid
EMBENET_RESULT_UNSPECIFIED_ERRORif the IPv6 was not stored

◆ EMBENET_NODE_GetLocalTime()

uint64_t EMBENET_NODE_GetLocalTime ( void  )

Gets the current local time since the networking stack was initialized.

This function returns the value of a monotonic clock, that is started from value 0 when EMBENET_NODE_Init is called. The clock is stopped when EMBENET_NODE_Deinit is invoked. The clock measures time in milliseconds. It is a local node clock and it is NOT synchronized with other nodes in the network. By using a 64-bit value range it is assumed, that the time overflow should not be concerned.

Returns
Local time expressed in ms.

◆ EMBENET_NODE_GetNetworkTime()

uint64_t EMBENET_NODE_GetNetworkTime ( void  )

Gets the current network time.

This time has no particular start point and may begin from a very large value.

Note
Network time is a current duration since ASN no 0. Every EmbeNET node holds the same time notion.
Returns
Time expressed in ms. 0 if not synchronized.

◆ EMBENET_NODE_GetNetworkAsn()

uint64_t EMBENET_NODE_GetNetworkAsn ( void  )

Gets the current network time expressed in Absolute Slot Number.

This time has no particular start point and may begin from a very large value.

Returns
Time expressed in ASN. 0 if not synchronized.

◆ EMBENET_NODE_GetRandomValue()

uint32_t EMBENET_NODE_GetRandomValue ( uint32_t  start,
uint32_t  stop 
)

Gets a random unsigned integer value from a given range.

Note
The value of stop must be greater or equal the value of start.
Parameters
[in]startlowest number in the range
[in]stophighest number in the range
Returns
random unsigned integer value in the range of start to stop.

Contact us

Any question or remarks? Just write us a message!

Contact Information

Feel free to get in touch