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

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

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

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.

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)

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.

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

Possible time sources for task scheduling

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

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

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

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

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

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.

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

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

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

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

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

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

Destroys a task.

Parameters

[in]

taskId

task identifier (as returned by EMBENET_NODE_TaskCreate)

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

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

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

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).

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.

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

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

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.

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.

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.

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.