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... | |
#define EMBENET_TASKID_INVALID SIZE_MAX |
typedef size_t EMBENET_TaskId |
Identifier of an application-level task running within the stack.
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.
[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 |
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).
[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 |
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.
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.
[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) |
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.
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.
[in] | port | port number on which the unexpected datagram was received |
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.
For more information refer to Stack handling
[in] | eventHandlers | structure, desired handlers may be set |
EMBENET_RESULT_OK | if initialization completed successfully |
EMBENET_RESULT_INVALID_ARGUMENT | if at least one of the input arguments was invalid |
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
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_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:
For more information on joining the network refer to Network handling
[in] | config | network configuration (see EMBENET_NODE_Config) |
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_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
[in] | quickJoinCredentials | credentials returned by the EMBENET_NODE_OnJoined callback |
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_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.
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.
[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. |
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 |
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.
[in] | groupId | identifier of the group that the node should join |
true | if the node successfully joined the group |
false | otherwise |
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.
[in] | groupId | identifier of the group that the node should leave |
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
EMBENET_GroupId EMBENET_NODE_GetGroupByIndex | ( | size_t | index | ) |
Gets the groups the node belongs to by their index.
[in] | index | group index ranging from 0 to EMBENET_NODE_GetGroupCount - 1 |
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.
[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 |
void EMBENET_NODE_TaskDestroy | ( | EMBENET_TaskId | taskId | ) |
Destroys a task.
[in] | taskId | task identifier (as returned by EMBENET_NODE_TaskCreate) |
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.
[in] | taskId | task identifier (as returned by EMBENET_NODE_TaskCreate) |
[in] | timeSource | time source for the scheduled task |
[in] | t | time expressed in ms |
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_Result EMBENET_NODE_TaskCancel | ( | EMBENET_TaskId | taskId | ) |
Cancels the previously scheduled task.
[in] | taskId | task identifier (as returned by EMBENET_NODE_TaskCreate) |
EMBENET_RESULT_OK | if the task canceled properly |
EMBENET_RESULT_INVALID_ARGUMENT | if at least one of the input arguments was invalid |
EMBENET_EUI64 EMBENET_NODE_GetUID | ( | void | ) |
Gets own UID which is an EUI64 address.
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).
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_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.
[out] | ipv6 | pointer the location where the IPv6 address will be stored, must not be NULL. |
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_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.
[out] | ipv6 | pointer the location where the IPv6 address will be stored, must not be NULL. |
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 |
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.
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.
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.
uint32_t EMBENET_NODE_GetRandomValue | ( | uint32_t | start, |
uint32_t | stop | ||
) |
Gets a random unsigned integer value from a given range.
[in] | start | lowest number in the range |
[in] | stop | highest number in the range |
Any question or remarks? Just write us a message!
Feel free to get in touch