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]	taskId	id of the running task
[in]	timeSource	time source for the scheduled task
[in]	t	time at which the task was expected to run
[in]	context	context 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]	panId	PAN ID of network to which the node has joined.
[in]	quickJoinCredentials	credentials 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]	panId	PAN ID of network to which the node tries to join.
[in]	panData	data that is propagated by root node in the network, may be NULL
[in]	panDataSize	size 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] port port number on which the unexpected datagram was received

Enumeration Type Documentation

◆ EMBENET_NODE_TimeSource

enum 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] eventHandlers structure, desired handlers may be set

Return values

EMBENET_RESULT_OK	if initialization completed successfully
EMBENET_RESULT_INVALID_ARGUMENT	if 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] config network configuration (see EMBENET_NODE_Config)

Return values

EMBENET_RESULT_OK	if the joining process has begun successfully
EMBENET_RESULT_INVALID_ARGUMENT	if 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] quickJoinCredentials credentials returned by the EMBENET_NODE_OnJoined callback

Return values

EMBENET_RESULT_OK	if the quick joining process has begun successfully
EMBENET_RESULT_INVALID_ARGUMENT	if at least one of the input arguments was invalid
EMBENET_RESULT_INVALID_CREDENTIALS	if 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]	panData	additional network-wide data to pass to each node wishing to join. The network is capable of sending max. 16 Bytes od PAN data
[in]	panDataSize	size of the additional network-wide data.

Return values

EMBENET_RESULT_OK	if the root operation has started successfully
EMBENET_RESULT_INVALID_ARGUMENT	if at least one of the input arguments was invalid
EMBENET_RESULT_ROOT_CAPABILITIES_DISABLED	if 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] groupId identifier of the group that the node should join

Return values

true	if the node successfully joined the group
false	otherwise

◆ 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] groupId identifier 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] index group 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]	taskFunction	pointer to a function that will be run as a task
[in]	userContext	optional 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] taskId task 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]	taskId	task identifier (as returned by EMBENET_NODE_TaskCreate)
[in]	timeSource	time source for the scheduled task
[in]	t	time expressed in ms

Return values

EMBENET_RESULT_OK	if scheduled properly.
EMBENET_RESULT_INVALID_ARGUMENT	if at least one of the input arguments was invalid
EMBENET_RESULT_UNABLE_TO_SCHEDULE_IN_THE_PAST	if the schedule time is in the past
EMBENET_RESULT_NOT_SYNCHRONIZED	if 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] taskId task identifier (as returned by EMBENET_NODE_TaskCreate)

Return values

EMBENET_RESULT_OK	if the task canceled properly
EMBENET_RESULT_INVALID_ARGUMENT	if 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] ipv6 pointer the location where the IPv6 address will be stored, must not be NULL.

Return values

EMBENET_RESULT_OK	if the border router IPv6 address was stored successfully
EMBENET_RESULT_INVALID_ARGUMENT	if at least one of the input arguments was invalid
EMBENET_RESULT_UNSPECIFIED_ERROR	if 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] ipv6 pointer the location where the IPv6 address will be stored, must not be NULL.

Return values

EMBENET_RESULT_OK	if parent's IPv6 address was stored successfully
EMBENET_RESULT_INVALID_ARGUMENT	if at least one of the input arguments was invalid
EMBENET_RESULT_UNSPECIFIED_ERROR	if 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]	start	lowest number in the range
[in]	stop	highest number in the range

Returns: random unsigned integer value in the range of start to stop.

Detailed Description

Data Structures

Macro Definition Documentation

◆ EMBENET_TASKID_INVALID

Typedef Documentation

◆ EMBENET_TaskId

◆ EMBENET_NODE_TaskFunction

◆ EMBENET_NODE_OnJoined

◆ EMBENET_NODE_OnLeft

◆ EMBENET_NODE_OnJoinAttempt

◆ EMBENET_NODE_OnQuickJoinCredentialsObsolete

◆ EMBENET_NODE_DataOnUnregisteredPort

Enumeration Type Documentation

◆ EMBENET_NODE_TimeSource

Function Documentation

◆ EMBENET_NODE_Init()

◆ EMBENET_NODE_Deinit()

◆ EMBENET_NODE_Proc()

◆ EMBENET_NODE_Join()

◆ EMBENET_NODE_QuickJoin()

◆ EMBENET_NODE_Leave()

◆ EMBENET_NODE_RootStart()

◆ EMBENET_NODE_JoinGroup()

◆ EMBENET_NODE_LeaveGroup()

◆ EMBENET_NODE_GetGroupCount()

◆ EMBENET_NODE_GetGroupByIndex()

◆ EMBENET_NODE_TaskCreate()

◆ EMBENET_NODE_TaskDestroy()

◆ EMBENET_NODE_TaskSchedule()

◆ EMBENET_NODE_TaskCancel()

◆ EMBENET_NODE_GetUID()

◆ EMBENET_NODE_SetUID()

◆ EMBENET_NODE_ForceParentChange()

◆ EMBENET_NODE_GetBorderRouterAddress()

◆ EMBENET_NODE_GetParentAddress()

◆ EMBENET_NODE_GetLocalTime()

◆ EMBENET_NODE_GetNetworkTime()

◆ EMBENET_NODE_GetNetworkAsn()

◆ EMBENET_NODE_GetRandomValue()