Raw Link

This module includes functions that control the raw link-layer configuration.

Summary

Typedefs
`otLinkRawEnergyScanDone)(otInstance *aInstance, int8_t aEnergyScanMaxRssi)`	typedef `void(*` Pointer on receipt of a IEEE 802.15.4 frame.
`otLinkRawReceiveDone)(otInstance aInstance, otRadioFrame aFrame, otError aError)`	typedef `void(*` Pointer on receipt of a IEEE 802.15.4 frame.
`otLinkRawTransmitDone)(otInstance aInstance, otRadioFrame aFrame, otRadioFrame *aAckFrame, otError aError)`	typedef `void(*` Pointer on receipt of a IEEE 802.15.4 frame.

Functions
`otLinkRawEnergyScan(otInstance *aInstance, uint8_t aScanChannel, uint16_t aScanDuration, otLinkRawEnergyScanDone aCallback)`	`otError` Begins the energy scan sequence on the radio.
`otLinkRawGetCaps(otInstance *aInstance)`	`otRadioCaps` Get the radio capabilities.
`otLinkRawGetPromiscuous(otInstance *aInstance)`	`bool` Gets the status of promiscuous mode.
`otLinkRawGetRadioTime(otInstance *aInstance)`	`uint64_t` Get current platform time (64bits width) of the radio chip.
`otLinkRawGetRssi(otInstance *aInstance)`	`int8_t` Get the most recent RSSI measurement.
`otLinkRawGetTransmitBuffer(otInstance *aInstance)`	`otRadioFrame *` The radio transitions from Transmit to Receive.
`otLinkRawIsEnabled(otInstance *aInstance)`	`bool` Indicates whether or not the raw link-layer is enabled.
`otLinkRawReceive(otInstance *aInstance)`	`otError` Transitioning the radio from Sleep to Receive.
`otLinkRawSetAlternateShortAddress(otInstance *aInstance, otShortAddress aShortAddress)`	`otError` Set the alternate short address.
`otLinkRawSetMacFrameCounter(otInstance *aInstance, uint32_t aMacFrameCounter)`	`otError` Sets the current MAC frame counter value.
`otLinkRawSetMacFrameCounterIfLarger(otInstance *aInstance, uint32_t aMacFrameCounter)`	`otError` Sets the current MAC frame counter value only if the new value is larger than the current one.
`otLinkRawSetMacKey(otInstance aInstance, uint8_t aKeyIdMode, uint8_t aKeyId, const otMacKey aPrevKey, const otMacKey aCurrKey, const otMacKey aNextKey)`	`otError` Update MAC keys and key index.
`otLinkRawSetPromiscuous(otInstance *aInstance, bool aEnable)`	`otError` Enables or disables promiscuous mode.
`otLinkRawSetReceiveDone(otInstance *aInstance, otLinkRawReceiveDone aCallback)`	`otError` Enables/disables the raw link-layer.
`otLinkRawSetShortAddress(otInstance *aInstance, uint16_t aShortAddress)`	`otError` Set the Short Address for address filtering.
`otLinkRawSleep(otInstance *aInstance)`	`otError` Transition the radio from Receive to Sleep.
`otLinkRawSrcMatchAddExtEntry(otInstance aInstance, const otExtAddress aExtAddress)`	`otError` Adding extended address to the source match table.
`otLinkRawSrcMatchAddShortEntry(otInstance *aInstance, uint16_t aShortAddress)`	`otError` Adding short address to the source match table.
`otLinkRawSrcMatchClearExtEntries(otInstance *aInstance)`	`otError` Removing all the extended addresses from the source match table.
`otLinkRawSrcMatchClearExtEntry(otInstance aInstance, const otExtAddress aExtAddress)`	`otError` Removing extended address to the source match table of the radio.
`otLinkRawSrcMatchClearShortEntries(otInstance *aInstance)`	`otError` Removing all the short addresses from the source match table.
`otLinkRawSrcMatchClearShortEntry(otInstance *aInstance, uint16_t aShortAddress)`	`otError` Removing short address to the source match table.
`otLinkRawSrcMatchEnable(otInstance *aInstance, bool aEnable)`	`otError` Enable/Disable source match for frame pending.
`otLinkRawTransmit(otInstance *aInstance, otLinkRawTransmitDone aCallback)`	`otError` Begins the transmit sequence on the radio.

Typedefs

otLinkRawEnergyScanDone

void(* otLinkRawEnergyScanDone)(otInstance *aInstance, int8_t aEnergyScanMaxRssi)

Pointer on receipt of a IEEE 802.15.4 frame.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aEnergyScanMaxRssi`	The maximum RSSI encountered on the scanned channel.

otLinkRawReceiveDone

void(* otLinkRawReceiveDone)(otInstance *aInstance, otRadioFrame *aFrame, otError aError)

Pointer on receipt of a IEEE 802.15.4 frame.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aFrame`	A pointer to the received frame or NULL if the receive operation was aborted.
`[in] aError`	OT_ERROR_NONE when successfully received a frame. OT_ERROR_ABORT when reception was aborted and a frame was not received.

otLinkRawTransmitDone

void(* otLinkRawTransmitDone)(otInstance *aInstance, otRadioFrame *aFrame, otRadioFrame *aAckFrame, otError aError)

Pointer on receipt of a IEEE 802.15.4 frame.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aFrame`	A pointer to the frame that was transmitted.
`[in] aAckFrame`	A pointer to the ACK frame.
`[in] aError`	OT_ERROR_NONE when the frame was transmitted. OT_ERROR_NO_ACK when the frame was transmitted but no ACK was received OT_ERROR_CHANNEL_ACCESS_FAILURE when the transmission could not take place due to activity on the channel. OT_ERROR_ABORT when transmission was aborted for other reasons.

Functions

otLinkRawEnergyScan

otError otLinkRawEnergyScan(
  otInstance *aInstance,
  uint8_t aScanChannel,
  uint16_t aScanDuration,
  otLinkRawEnergyScanDone aCallback
)

Begins the energy scan sequence on the radio.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aScanChannel`	The channel to perform the energy scan on.
`[in] aScanDuration`	The duration, in milliseconds, for the channel to be scanned.
`[in] aCallback`	A pointer to a function called on completion of a scanned channel.

Return Values

`OT_ERROR_NONE`	Successfully started scanning the channel.
`OT_ERROR_BUSY`	The radio is performing energy scanning.
`OT_ERROR_NOT_IMPLEMENTED`	The radio doesn't support energy scanning.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawGetCaps

otRadioCaps otLinkRawGetCaps(
  otInstance *aInstance
)

Get the radio capabilities.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Returns

The radio capability bit vector. The stack enables or disables some functions based on this value.

otLinkRawGetPromiscuous

bool otLinkRawGetPromiscuous(
  otInstance *aInstance
)

Gets the status of promiscuous mode.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Return Values

`true`	Promiscuous mode is enabled.
`false`	Promiscuous mode is disabled.

otLinkRawGetRadioTime

uint64_t otLinkRawGetRadioTime(
  otInstance *aInstance
)

Get current platform time (64bits width) of the radio chip.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Returns

The current radio time in microseconds.

otLinkRawGetRssi

int8_t otLinkRawGetRssi(
  otInstance *aInstance
)

Get the most recent RSSI measurement.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Returns

The RSSI in dBm when it is valid. 127 when RSSI is invalid.

otLinkRawGetTransmitBuffer

otRadioFrame * otLinkRawGetTransmitBuffer(
  otInstance *aInstance
)

The radio transitions from Transmit to Receive.

Returns a pointer to the transmit buffer.

The caller forms the IEEE 802.15.4 frame in this buffer then calls otLinkRawTransmit() to request transmission.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Returns

A pointer to the transmit buffer or NULL if the raw link-layer isn't enabled.

otLinkRawIsEnabled

bool otLinkRawIsEnabled(
  otInstance *aInstance
)

Indicates whether or not the raw link-layer is enabled.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Return Values

`true`	The raw link-layer is enabled.
`false`	The raw link-layer is disabled.

otLinkRawReceive

otError otLinkRawReceive(
  otInstance *aInstance
)

Transitioning the radio from Sleep to Receive.

Turn on the radio.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Return Values

`OT_ERROR_NONE`	Successfully transitioned to Receive.
`OT_ERROR_INVALID_STATE`	The radio was disabled or transmitting.

otLinkRawSetAlternateShortAddress

otError otLinkRawSetAlternateShortAddress(
  otInstance *aInstance,
  otShortAddress aShortAddress
)

Set the alternate short address.

This is an optional API. Support for this is indicated by including the capability OT_RADIO_CAPS_ALT_SHORT_ADDR in otLinkRawGetCaps().

When supported, the radio will accept received frames destined to the specified alternate short address in addition to the short address provided in otLinkRawSetShortAddress().

The aShortAddress can be set to OT_RADIO_INVALID_SHORT_ADDR (0xfffe) to clear any previously set alternate short address.

Details

Parameters

`[in] aInstance`	The OpenThread instance structure.
`[in] aShortAddress`	The alternate short address. `OT_RADIO_INVALID_SHORT_ADDR` to clear.

Return Values

`OT_ERROR_NONE`	Successfully set the alternate short address.
`OT_ERROR_INVALID_STATE`	The raw link-layer is not enabled.

otLinkRawSetMacFrameCounter

otError otLinkRawSetMacFrameCounter(
  otInstance *aInstance,
  uint32_t aMacFrameCounter
)

Sets the current MAC frame counter value.

Always sets the MAC counter to the new given value aMacFrameCounter independent of the current value.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aMacFrameCounter`	The MAC frame counter value.

Return Values

`OT_ERROR_NONE`	If successful.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSetMacFrameCounterIfLarger

otError otLinkRawSetMacFrameCounterIfLarger(
  otInstance *aInstance,
  uint32_t aMacFrameCounter
)

Sets the current MAC frame counter value only if the new value is larger than the current one.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aMacFrameCounter`	The MAC frame counter value.

Return Values

`OT_ERROR_NONE`	If successful.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSetMacKey

otError otLinkRawSetMacKey(
  otInstance *aInstance,
  uint8_t aKeyIdMode,
  uint8_t aKeyId,
  const otMacKey *aPrevKey,
  const otMacKey *aCurrKey,
  const otMacKey *aNextKey
)

Update MAC keys and key index.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aKeyIdMode`	The key ID mode.
`[in] aKeyId`	The key index.
`[in] aPrevKey`	The previous MAC key.
`[in] aCurrKey`	The current MAC key.
`[in] aNextKey`	The next MAC key.

Return Values

`OT_ERROR_NONE`	If successful.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSetPromiscuous

otError otLinkRawSetPromiscuous(
  otInstance *aInstance,
  bool aEnable
)

Enables or disables promiscuous mode.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aEnable`	A value to enable or disable promiscuous mode.

Return Values

`OT_ERROR_NONE`	If successful.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSetReceiveDone

otError otLinkRawSetReceiveDone(
  otInstance *aInstance,
  otLinkRawReceiveDone aCallback
)

Enables/disables the raw link-layer.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aCallback`	A pointer to a function called on receipt of a IEEE 802.15.4 frame. NULL to disable the raw-link layer.

Return Values

`OT_ERROR_FAILED`	The radio could not be enabled/disabled.
`OT_ERROR_INVALID_STATE`	If the OpenThread IPv6 interface is already enabled.
`OT_ERROR_NONE`	If the enable state was successfully set.

otLinkRawSetShortAddress

otError otLinkRawSetShortAddress(
  otInstance *aInstance,
  uint16_t aShortAddress
)

Set the Short Address for address filtering.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aShortAddress`	The IEEE 802.15.4 Short Address.

Return Values

`OT_ERROR_NONE`	If successful.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSleep

otError otLinkRawSleep(
  otInstance *aInstance
)

Transition the radio from Receive to Sleep.

Turn off the radio.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Return Values

`OT_ERROR_NONE`	Successfully transitioned to Sleep.
`OT_ERROR_BUSY`	The radio was transmitting
`OT_ERROR_INVALID_STATE`	The radio was disabled

otLinkRawSrcMatchAddExtEntry

otError otLinkRawSrcMatchAddExtEntry(
  otInstance *aInstance,
  const otExtAddress *aExtAddress
)

Adding extended address to the source match table.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aExtAddress`	The extended address to be added.

Return Values

`OT_ERROR_NONE`	Successfully added extended address to the source match table.
`OT_ERROR_NO_BUFS`	No available entry in the source match table.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSrcMatchAddShortEntry

otError otLinkRawSrcMatchAddShortEntry(
  otInstance *aInstance,
  uint16_t aShortAddress
)

Adding short address to the source match table.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aShortAddress`	The short address to be added.

Return Values

`OT_ERROR_NONE`	Successfully added short address to the source match table.
`OT_ERROR_NO_BUFS`	No available entry in the source match table.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSrcMatchClearExtEntries

otError otLinkRawSrcMatchClearExtEntries(
  otInstance *aInstance
)

Removing all the extended addresses from the source match table.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Return Values

`OT_ERROR_NONE`	If successful.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSrcMatchClearExtEntry

otError otLinkRawSrcMatchClearExtEntry(
  otInstance *aInstance,
  const otExtAddress *aExtAddress
)

Removing extended address to the source match table of the radio.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aExtAddress`	The extended address to be removed.

Return Values

`OT_ERROR_NONE`	Successfully removed the extended address from the source match table.
`OT_ERROR_NO_ADDRESS`	The extended address is not in source match table.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSrcMatchClearShortEntries

otError otLinkRawSrcMatchClearShortEntries(
  otInstance *aInstance
)

Removing all the short addresses from the source match table.

Details

Parameters

[in] aInstance

A pointer to an OpenThread instance.

Return Values

`OT_ERROR_NONE`	If successful.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSrcMatchClearShortEntry

otError otLinkRawSrcMatchClearShortEntry(
  otInstance *aInstance,
  uint16_t aShortAddress
)

Removing short address to the source match table.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aShortAddress`	The short address to be removed.

Return Values

`OT_ERROR_NONE`	Successfully removed short address from the source match table.
`OT_ERROR_NO_ADDRESS`	The short address is not in source match table.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawSrcMatchEnable

otError otLinkRawSrcMatchEnable(
  otInstance *aInstance,
  bool aEnable
)

Enable/Disable source match for frame pending.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aEnable`	Enable/disable source match for frame pending.

Return Values

`OT_ERROR_NONE`	If successful.
`OT_ERROR_INVALID_STATE`	If the raw link-layer isn't enabled.

otLinkRawTransmit

otError otLinkRawTransmit(
  otInstance *aInstance,
  otLinkRawTransmitDone aCallback
)

Begins the transmit sequence on the radio.

The caller must form the IEEE 802.15.4 frame in the buffer provided by otLinkRawGetTransmitBuffer() before requesting transmission. The channel and transmit power are also included in the otRadioFrame structure.

The transmit sequence consists of:

Transitioning the radio to Transmit from Receive.
Transmits the PSDU on the given channel and at the given transmit power.

Details

Parameters

`[in] aInstance`	A pointer to an OpenThread instance.
`[in] aCallback`	A pointer to a function called on completion of the transmission.

Return Values

`OT_ERROR_NONE`	Successfully transitioned to Transmit.
`OT_ERROR_INVALID_STATE`	The radio was not in the Receive state.

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.