Platform helper functions for OpenThread. More...

Collaboration diagram for Thread helper functions for baremetal:

Macros
#define	SuccessOrExit(aCondition)

Enumerations
enum	openthread_message_codes { OT_SERIAL_DOWNLINK = 0xB2 , OT_SERIAL_UPLINK = 0xB3 }

Functions
struct ca821x_dev *	PlatformGetDeviceRef (void)
	Following Initialisation, this can be used to obtain the pDeviceRef that openthread is using. More...

int	PlatformRadioInit (void)
	Initialise the openthread platform layer with the internal device struct. More...

int	PlatformRadioInitWithDev (struct ca821x_dev *pDeviceRef)
	Initialise the openthread platform layer with apDeviceRef as the device. More...

int	PlatformRadioInitWithDevEui64 (struct ca821x_dev apDeviceRef, uint8_t pEui64)
	Initialise the openthread platform layer with pDeviceRef as the device, and pEui64 as the EUI64. More...

int	PlatformIsExpectingIndication (void)
	Determines whether or not an MCPS-DATA-INDICATION is currently expected, based on the result of the previous poll. More...

void	PlatformRadioStop (void)
	Stop and reset the CA-821x. More...

void	PlatformAlarmInit (void)
	Initialise the platform alarm subsystem. More...

otError	PlatformSleep (uint32_t aSleepTime)
	Sends the platform and cax to sleep for the given number of milliseconds. More...

bool	PlatformCanSleep (otInstance *aInstance)
	Check whether the platform is able to sleep. More...

otError	PlatformUartReceive (const uint8_t *aBuf, uint16_t aBufLength)
	Handle received serial data. More...

otError	PlatformTryJoin (struct ca821x_dev pDeviceRef, otInstance aInstance)
	Helper function to attempt the Thread joining process. More...

otError	PlatformTryJoinWithCustomPoll (struct ca821x_dev pDeviceRef, otInstance aInstance, void(*poll_func)(void))
	Identical to PlatformTryJoin(), except that an additional poll function can be provided, which will be called while the joining process is in progress. More...

otError	PlatformTryJoinWithPskd (struct ca821x_dev pDeviceRef, otInstance aInstance, const char *aPskd)
	Helper function to attempt the Thread joining process, with an explicit passcode. More...

otError	PlatformTryJoinWithPskdWithCustomPoll (struct ca821x_dev pDeviceRef, otInstance aInstance, const char aPskd, void(poll_func)(void))
	Identiacl to PlatformTryJoinWithPsdk(), except that an additional poll function can be provided, which will be called while the joining process is in progress. More...

otError	PlatformPrintJoinerCredentials (struct ca821x_dev pDeviceRef, otInstance aInstance, uint32_t aMaxWaitMs)
	Helper function to print the Thread Joiner credentials (for instance, upon boot). More...

otError	PlatformPrintJoinerCredentialsWithPskd (struct ca821x_dev pDeviceRef, otInstance aInstance, uint32_t aMaxWaitMs, const char *aPskd)
	Helper function to print the Thread Joiner credentials, with an explicit passcode (for instance, upon boot). More...

otError	PlatformEraseJoinerCredentials (otInstance *aInstance)
	Helper function to erase the joiner credentials of this device. More...

const char *	PlatformGetJoinerCredential (otInstance *aInstance)
	Helper function to get the joiner credential of this device. More...

otError	otPlatSettingsGetAddress (uint16_t aKey, int aIndex, void *aValue, uint16_t aValueLength)
	Get the address at which a setting is stored, so that it can be read without copying it, as would be necessary when using otPlatSettingsGet(). More...

otError	otPlatSettingsAddVector (otInstance aInstance, uint16_t aKey, struct settingBuffer aVector, size_t aCount)
	This function adds the value to a setting identified by aKey, without replacing any existing values. More...

otError	PlatformGetQRString (char aBufOut, size_t bufferSize, otInstance aInstance)
	Get the QR text string format to be read as a Thread Connect QR Code, enabling external commissioning via the Thread Commissioning App. More...

Variables
otInstance *	OT_INSTANCE

Detailed Description

Platform helper functions for OpenThread.

Macro Definition Documentation

◆ SuccessOrExit

#define SuccessOrExit ( aCondition )

Value:

    do                            \
    {                             \
        if ((aCondition) != 0)    \
        {                         \
            goto exit;            \
        }                         \
    } while (0)

Enumeration Type Documentation

◆ openthread_message_codes

enum openthread_message_codes

Enumerator
OT_SERIAL_DOWNLINK
OT_SERIAL_UPLINK

Function Documentation

◆ otPlatSettingsAddVector()

otError otPlatSettingsAddVector	(	otInstance *	aInstance,
		uint16_t	aKey,
		struct settingBuffer *	aVector,
		size_t	aCount
	)

This function adds the value to a setting identified by aKey, without replacing any existing values.

This function differs from otPlatSettingsAdd in that it takes a vector of buffers instead of a single one. Use this function if you must write several non-contiguous buffers into a single setting without copying them into contiguous memory first.

Note that the underlying implementation is not required to maintain the order of the items associated with a specific key. The added value may be added to the end, the beginning, or even somewhere in the middle. The order of any pre-existing values may also change.

Calling this function successfully may cause unrelated settings with multiple values to be reordered.

Parameters

[in]	aInstance	The OpenThread instance structure.
[in]	aKey	The key associated with the setting to change.
[in]	aVector	The array of buffers that will be written to the setting.
[in]	aCount	The length of the aVector array.

Return values

OT_ERROR_NONE	The given setting was added or staged to be added.
OT_ERROR_NOT_IMPLEMENTED	This function is not implemented on this platform.
OT_ERROR_NO_BUFS	No space remaining to store the given setting.

◆ otPlatSettingsGetAddress()

otError otPlatSettingsGetAddress	(	uint16_t	aKey,
		int	aIndex,
		void **	aValue,
		uint16_t *	aValueLength
	)

Get the address at which a setting is stored, so that it can be read without copying it, as would be necessary when using otPlatSettingsGet().

Parameters

[in]	aKey	The key associated with the requested setting.
[in]	aIndex	The index of the specific item to get.
[out]	aValue	A pointer to where the address of the setting should be written. May be set to NULL if just testing for the presence or length of a setting.
[in,out]	aValueLength	A pointer to the length of the value. At return, will be overwritten with the length of the value.

Note that the pointer written to aValue is not valid after a call to any other otPlatSettings* function, so it must be used immediately.

Return values

OT_ERROR_NONE	The given setting was found and fetched successfully.
OT_ERROR_NOT_FOUND	The given setting was not found in the setting store.
OT_ERROR_NOT_IMPLEMENTED	This function is not implemented on this platform.

◆ PlatformAlarmInit()

void PlatformAlarmInit ( void )

Initialise the platform alarm subsystem.

◆ PlatformCanSleep()

bool PlatformCanSleep ( otInstance * aInstance )

Check whether the platform is able to sleep.

Parameters

aInstance The OpenThread instance

Returns: true if platform can sleep, false if busy.

◆ PlatformEraseJoinerCredentials()

otError PlatformEraseJoinerCredentials ( otInstance * aInstance )

Helper function to erase the joiner credentials of this device.

Parameters

aInstance The openthread instance

◆ PlatformGetDeviceRef()

struct ca821x_dev* PlatformGetDeviceRef ( void )

Following Initialisation, this can be used to obtain the pDeviceRef that openthread is using.

Return values

The	pDeviceRef that openthread is using

◆ PlatformGetJoinerCredential()

const char* PlatformGetJoinerCredential ( otInstance * aInstance )

Helper function to get the joiner credential of this device.

Parameters

aInstance The openthread instance

Returns: The joiner credential as a null-terminated string

◆ PlatformGetQRString()

otError PlatformGetQRString	(	char *	aBufOut,
		size_t	bufferSize,
		otInstance *	aInstance
	)

Get the QR text string format to be read as a Thread Connect QR Code, enabling external commissioning via the Thread Commissioning App.

Parameters

aBufOut	A string buffer which stores the QR string format
bufferSize	String buffer size
aInstance	openThread struct for retrieving Eui64 value.

Returns: Thread Connect QR commissioning null-terminated string of the form: v=1&&eui=0000b57fffe15d68&&cc=J01NU5 source: https://openthread.io/guides/border-router/external-commissioning?comm=ot-commissioner-app#commission-the-joiner_1

◆ PlatformIsExpectingIndication()

int PlatformIsExpectingIndication ( void )

Determines whether or not an MCPS-DATA-INDICATION is currently expected, based on the result of the previous poll.

This is used by the platform to determine whether or not sleeping is a good idea.

Return values

1	if an indication is expected, 0 if an indication is not expected.

◆ PlatformPrintJoinerCredentials()

otError PlatformPrintJoinerCredentials	(	struct ca821x_dev *	pDeviceRef,
		otInstance *	aInstance,
		uint32_t	aMaxWaitMs
	)

Helper function to print the Thread Joiner credentials (for instance, upon boot).

This function prints the Thread Joiner credentials using printf. It also handles leaving the interface active in the case of USB, where going to sleep will kill the USB interface and prevent the information from being read. This function will not print the credentials if the device is already commissioned.

Parameters

pDeviceRef	Pointer to initialised ca821x_device_ref struct
aInstance	The openthread instance
aMaxWaitMs	The maximum time to stay awake to allow credentials to be read (USB only). Only required for devices that sleep.

◆ PlatformPrintJoinerCredentialsWithPskd()

otError PlatformPrintJoinerCredentialsWithPskd	(	struct ca821x_dev *	pDeviceRef,
		otInstance *	aInstance,
		uint32_t	aMaxWaitMs,
		const char *	aPskd
	)

Helper function to print the Thread Joiner credentials, with an explicit passcode (for instance, upon boot).

This function prints the Thread Joiner credentials using printf. It also handles leaving the interface active in the case of USB, where going to sleep will kill the USB interface and prevent the information from being read. This function will not print the credentials if the device is already commissioned.

Parameters

pDeviceRef	Pointer to initialised ca821x_device_ref struct
aInstance	The openthread instance
aPskd	Pre-shared Key to use during the join
aMaxWaitMs	The maximum time to stay awake to allow credentials to be read (USB only). Only required for devices that sleep.

◆ PlatformRadioInit()

int PlatformRadioInit ( void )

Initialise the openthread platform layer with the internal device struct.

Either this or PlatformRadioInitWithDev must be used before openthread will be functional.

Return values

zero	on success, nonzero on failure

◆ PlatformRadioInitWithDev()

int PlatformRadioInitWithDev ( struct ca821x_dev * pDeviceRef )

Initialise the openthread platform layer with apDeviceRef as the device.

Either this or PlatformRadioInit must be used before openthread will be functional.

Parameters

pDeviceRef Pointer to initialised ca821x_device_ref struct

Return values

zero	on success, nonzero on failure

◆ PlatformRadioInitWithDevEui64()

int PlatformRadioInitWithDevEui64	(	struct ca821x_dev *	apDeviceRef,
		uint8_t *	pEui64
	)

Initialise the openthread platform layer with pDeviceRef as the device, and pEui64 as the EUI64.

Either this, PlatformRadioInit or PlatformRadioInitWithDev must be used before openthread will be functional.

Parameters

pDeviceRef	Pointer to initialised ca821x_device_ref struct
pEui64	pointer to array containing the EUI64 to use

Return values

zero	on success, nonzero on failure

◆ PlatformRadioStop()

void PlatformRadioStop ( void )

Stop and reset the CA-821x.

This will prevent the MAC from responding to ACKs and command frames as well as wiping the PIB.

◆ PlatformSleep()

otError PlatformSleep ( uint32_t aSleepTime )

Sends the platform and cax to sleep for the given number of milliseconds.

Parameters

aSleepTime The time in milliseconds to go to sleep for

Return values

OT_ERROR_NONE upon success

◆ PlatformTryJoin()

otError PlatformTryJoin	(	struct ca821x_dev *	pDeviceRef,
		otInstance *	aInstance
	)

Helper function to attempt the Thread joining process.

The state of the Thread IPv6 interface (otIp6SetEnabled) upon returning from this function depends on the return code. Upon a success (OT_ERROR_ALREADY or OT_ERROR_NONE), the interface is left up, anticipating further radio activity. Otherwise, it is brought down, anticipating being retried after a wait period.

Parameters

pDeviceRef	Pointer to initialised ca821x_device_ref struct
aInstance	The openthread instance

Returns: Status of the join

Return values

OT_ERROR_NONE	Successfully joined Thread Network (Thread IPv6 interface is left up)
OT_ERROR_ALREADY	Device was already joined to Thread network (can leave with otInstanceFactoryReset) (Thread IPv6 interface is left up)
(other)	Failed to join a Thread Network for the given reason. (Thread IPv6 interface is brought down)

◆ PlatformTryJoinWithCustomPoll()

otError PlatformTryJoinWithCustomPoll	(	struct ca821x_dev *	pDeviceRef,
		otInstance *	aInstance,
		void(*)(void)	poll_func
	)

Identical to PlatformTryJoin(), except that an additional poll function can be provided, which will be called while the joining process is in progress.

Parameters

pDeviceRef	Pointer to initialised ca821x_device_ref struct
aInstance	The openthread instance
poll_func	The function that will be called while the joining process is in progress.

Returns: Status of the join

Return values

OT_ERROR_NONE	Successfully joined Thread Network (Thread IPv6 interface is left up)
OT_ERROR_ALREADY	Device was already joined to Thread network (can leave with otInstanceFactoryReset) (Thread IPv6 interface is left up)
(other)	Failed to join a Thread Network for the given reason. (Thread IPv6 interface is brought down)

◆ PlatformTryJoinWithPskd()

otError PlatformTryJoinWithPskd	(	struct ca821x_dev *	pDeviceRef,
		otInstance *	aInstance,
		const char *	aPskd
	)

Helper function to attempt the Thread joining process, with an explicit passcode.

The state of the Thread IPv6 interface (otIp6SetEnabled) upon returning from this function depends on the return code. Upon a success (OT_ERROR_ALREADY or OT_ERROR_NONE), the interface is left up, anticipating further radio activity. Otherwise, it is brought down, anticipating being retried after a wait period.

Parameters

pDeviceRef	Pointer to initialised ca821x_device_ref struct
aInstance	The openthread instance
aPskd	Pre-shared Key to use during the join

Returns: Status of the join

Return values

OT_ERROR_NONE	Successfully joined Thread Network (Thread IPv6 interface is left up)
OT_ERROR_ALREADY	Device was already joined to Thread network (can leave with otInstanceFactoryReset) (Thread IPv6 interface is left up)
(other)	Failed to join a Thread Network for the given reason. (Thread IPv6 interface is brought down)

◆ PlatformTryJoinWithPskdWithCustomPoll()

otError PlatformTryJoinWithPskdWithCustomPoll	(	struct ca821x_dev *	pDeviceRef,
		otInstance *	aInstance,
		const char *	aPskd,
		void(*)(void)	poll_func
	)

Identiacl to PlatformTryJoinWithPsdk(), except that an additional poll function can be provided, which will be called while the joining process is in progress.

Parameters

pDeviceRef	Pointer to initialised ca821x_device_ref struct
aInstance	The openthread instance
aPskd	Pre-shared Key to use during the join
poll_func	The function that will be called while the joining process is in progress.

Returns: Status of the join

Return values

OT_ERROR_NONE	Successfully joined Thread Network (Thread IPv6 interface is left up)
OT_ERROR_ALREADY	Device was already joined to Thread network (can leave with otInstanceFactoryReset) (Thread IPv6 interface is left up)
(other)	Failed to join a Thread Network for the given reason. (Thread IPv6 interface is brought down)

◆ PlatformUartReceive()

otError PlatformUartReceive	(	const uint8_t *	aBuf,
		uint16_t	aBufLength
	)

Handle received serial data.

Parameters

aBuf	Pointer to the received data payload
aBufLength	The length of the received data payload

Return values

OT_ERROR_NONE upon success

Variable Documentation

◆ OT_INSTANCE

otInstance* OT_INSTANCE

extern

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ SuccessOrExit

Enumeration Type Documentation

◆ openthread_message_codes

Function Documentation

◆ otPlatSettingsAddVector()

◆ otPlatSettingsGetAddress()

◆ PlatformAlarmInit()

◆ PlatformCanSleep()

◆ PlatformEraseJoinerCredentials()

◆ PlatformGetDeviceRef()

◆ PlatformGetJoinerCredential()

◆ PlatformGetQRString()

◆ PlatformIsExpectingIndication()

◆ PlatformPrintJoinerCredentials()

◆ PlatformPrintJoinerCredentialsWithPskd()

◆ PlatformRadioInit()

◆ PlatformRadioInitWithDev()

◆ PlatformRadioInitWithDevEui64()

◆ PlatformRadioStop()

◆ PlatformSleep()

◆ PlatformTryJoin()

◆ PlatformTryJoinWithCustomPoll()

◆ PlatformTryJoinWithPskd()

◆ PlatformTryJoinWithPskdWithCustomPoll()

◆ PlatformUartReceive()

Variable Documentation

◆ OT_INSTANCE