IEEE 802.15.4

Parsing Dot15d4 messages

When processing Dot15d4 messages sent to a compatible interface, the whad::dot15d4::Dot15d4Msg::getType() function returns the corresponding message type (whad::dot15d4::MessageType). This message type is then used to process and parse the incoming message.

The following example code shows a message processing function defined for a compatible interface that only supports Dot15d4 packet sniffing. The supported commands must also be indicated in the interface’s capabilities as described in Discovery of interface characteristics.

void process_dot15d4_message(Message *p_message)
{
    NanoPbMsg *response = NULL;

    /* Wrap our NanoPbMsg into a Dot15d4Msg. */
    whad::dot15d4::Dot15d4Msg dot15d4_msg(message);

    switch (dot15d4_msg.getType())
    {
        case whad::dot15d4::MessageType::SniffModeMsg:
        {
            /* Configure our interface in sniff mode ... (custom code) */
            /* ... */

            /* Return a success message. */
            response = new whad::generic::Success();
        }
        break;

        case whad::dot15d4::MessageType::StartMsg:
        {
            /* Start current mode. */
            /* ... */

            /* Return a success message. */
            response = new whad::generic::Success();
        }
        break;

        case whad::dot15d4::MessageType::StopMsg:
        {
            /* Stop current mode. */
            /* ... */

            /* Return a success message. */
            response = new whad::generic::Success();
        }
        break;

        default:
        {
            /* Return an error message. */
            response = new whad::generic::Error();
        }
        break;
    }

    /* Send the response to the host. */
    whad::send(*response);
    delete response;
}

Dot15d4 API reference

namespace dot15d4

Typedefs

typedef whad::Packet<255> PDU

Enums

enum MessageType

Dot15d4 message types.

Values:

enumerator UnknownMsg: Unknown message.

enumerator SetNodeAddressMsg: Set interface address message.

enumerator SniffModeMsg: Set interface in sniffing mode.

enumerator JamModeMsg: Set interface in jamming mode.

enumerator EnergyDetectionMsg: Set interface in energy detection mode.

enumerator SendMsg: Send a PDU.

enumerator SendRawMsg: Send a raw PDU.

enumerator EndDeviceModeMsg: Set interface in end device mode.

enumerator RouterModeMsg: Set interface in router mode.

enumerator CoordModeMsg: Set interface in coordinator mode.

enumerator StartMsg: Start current mode.

enumerator StopMsg: Stop current mode.

enumerator MitmModeMsg: Set interface in Man-in-the-Middle mode.

enumerator JammedMsg: Jamming result notification.

enumerator EnergyDetectionSampleMsg: Energy detection sample notification message.

enumerator RawPduReceivedMsg: Raw PDU received notification message.

enumerator PduReceivingMsg: PDU received notification message.

enum AddressType

Dot15d4 address type.

Values:

enumerator AddressShort: Short (16-bit) node address.

enumerator AddressExtended: Extended (64-bit) node address.

enum MitmRole

MitM role.

Values:

enumerator ReactiveRole: Reactive role.

enumerator CorrectorRole: Corrector role.

class Dot15d4Msg : public whad::NanoPbMsg 

#include <base.hpp>

Subclassed by whad::dot15d4::CoordMode, whad::dot15d4::EndDeviceMode, whad::dot15d4::EnergyDetect, whad::dot15d4::EnergySample, whad::dot15d4::JamMode, whad::dot15d4::Jammed, whad::dot15d4::MitmMode, whad::dot15d4::PduReceived, whad::dot15d4::RawPduReceived, whad::dot15d4::RouterMode, whad::dot15d4::SendPdu, whad::dot15d4::SendRawPdu, whad::dot15d4::SetNodeAddress, whad::dot15d4::SniffMode

Public Functions

Dot15d4Msg(): Dot15d4 message base class.

Dot15d4Msg(NanoPbMsg pMessage)

Dot15d4 message base class.

Parameters:: pMessage – [in] NanoPbMsg object containing a ble domain message

~Dot15d4Msg(): Dot15d4 message base class destructor.

MessageType getType(void)

Identify the underlying dot15d4 message.

This method can be used when parsing incoming Dot15d4 domain message to identify the type of message it contains and process it later.

Returns:: Dot15d4 message type.

class CoordMode : public whad::dot15d4::Dot15d4Msg 

#include <coord.hpp>

Public Functions

CoordMode(Dot15d4Msg &message): Parse a message as a CoordMode message.

CoordMode(uint32_t channel)

CoordMode message constructor.

Parameters:: channel – [in] Specify the ZigBee channel to use

uint32_t getChannel()

Retrieve the dot15d4 channel to use.

Return values:: Channel – number

class EndDeviceMode : public whad::dot15d4::Dot15d4Msg 

#include <enddevice.hpp>

Public Functions

EndDeviceMode(Dot15d4Msg &message): Parse a message as a EndDeviceMode message.

EndDeviceMode(uint32_t channel)

EndDeviceMode message constructor.

Parameters:: channel – [in] Specify the ZigBee channel to use

uint32_t getChannel()

Retrieve the dot15d4 channel to use.

Return values:: Channel – number

class JamMode : public whad::dot15d4::Dot15d4Msg 

#include <jam.hpp>

Public Functions

JamMode(Dot15d4Msg &message): Parse a message as a JamMode message.

JamMode(uint32_t channel)

JamMode message constructor.

Parameters:: channel – [in] Specify the ZigBee channel to jam

uint32_t getChannel()

Retrieve the dot15d4 channel to jam.

Return values:: Channel – number

class Jammed : public whad::dot15d4::Dot15d4Msg 

#include <jammed.hpp>

Public Functions

Jammed(Dot15d4Msg &message): Parse a message as a Jammed message.

Jammed(uint32_t timestamp)

Jammed message constructor.

Parameters:: timestamp – [in] Specify the timestamp

uint32_t getTimestamp()

Retrieve the timestamp.

Return values:: Timestamp – value (in seconds)

class MitmMode : public whad::dot15d4::Dot15d4Msg 

#include <mitm.hpp>

Public Functions

MitmMode(Dot15d4Msg &message): Parse a message as a MitmMode message.

MitmMode(MitmRole role)

MitmMode message constructor.

Parameters:: role – [in] Specify the MitM role

MitmRole getRole()

Retrieve the MitM role.

Return values:: MitM – role

class EnergyDetect : public whad::dot15d4::Dot15d4Msg 

#include <nrgdetect.hpp>

Public Functions

EnergyDetect(Dot15d4Msg &message): Parse a message as a EnergyDetect message.

EnergyDetect(uint32_t channel)

EnergyDetect message constructor.

Parameters:: channel – [in] Specify the ZigBee channel to detect

uint32_t getChannel()

Retrieve the dot15d4 channel to detect.

Return values:: Channel – number

class EnergySample : public whad::dot15d4::Dot15d4Msg 

#include <nrgsample.hpp>

Public Functions

EnergySample(Dot15d4Msg &message): Parse a message as a EnergySample message.

EnergySample(uint32_t timestamp, uint32_t value)

EnergySample message constructor.

Parameters:

timestamp – [in] Specify the sample timestamp
value – [in] Sample value

uint32_t getTimestamp()

Retrieve the sample timestamp.

Return values:: Timestamp – value (in seconds1)

uint32_t getValue()

Retrieve the sample value.

Return values:: Sample – value

class Dot15d4Packet

#include <packet.hpp>

Public Functions

Dot15d4Packet(uint32_t channel, uint8_t *pPdu, int length, uint32_t fcs)

Create a Dot15d4Packet object with the given channel, PDU and FCS values.

Parameters:

channel – [in] ZigBee channel on which the PDU has been received
pPdu – [in] Pointer to a buffer containing the PDU bytes
length – [in] PDU length in bytes
fcs – [in] Frame Check Sequence value

Dot15d4Packet(uint32_t channel, uint8_t *pPdu, int length, uint32_t fcs, int32_t rssi)

Create a Dot15d4Packet object with the given channel, PDU and FCS values.

Parameters:

channel – [in] ZigBee channel on which the PDU has been received
pPdu – [in] Pointer to a buffer containing the PDU bytes
length – [in] PDU length in bytes
fcs – [in] Frame Check Sequence value
rssi – [in] Received Signal Strength Indicator value (in dBm)

Dot15d4Packet(uint32_t channel, uint8_t *pPdu, int length, uint32_t fcs, int32_t rssi, uint32_t timestamp)

Create a Dot15d4Packet object with the given channel, PDU and FCS values.

Parameters:

channel – [in] ZigBee channel on which the PDU has been received
pPdu – [in] Pointer to a buffer containing the PDU bytes
length – [in] PDU length in bytes
fcs – [in] Frame Check Sequence value
rssi – [in] Received Signal Strength Indicator value (in dBm)
timestamp – [in] Timestamp (in seconds) at which the PDU has been received

void setChannel(uint32_t channel)

Set dot15d4 packet channel value.

Parameters:: channel – [in] Zigbee channel this packet has been received on

void setPdu(PDU &pdu)

Set dot15d4 packet PDU.

Parameters:: pdu – [in] packet PDU

void setFcs(uint32_t fcs)

Set dot15d4 packet channel FCS value.

Parameters:: fcs – [in] Frame Check Sequence value for this packet

void addRssi(int32_t rssi)

Add RSSI to the received PDU.

Parameters:: rssi – [in] Received Signal Strength Indicator in dBm

void addTimestamp(uint32_t timestamp)

Add Timestamp to the received PDU.

Parameters:: timestamp – [in] Timestamp in seconds

void addFcsValidity(bool valid)

Add FCS validity to the received PDU.

Parameters:: valid – [in] FCS validity

void addLqi(uint32_t lqi)

Add LQI to the received PDU.

Parameters:: lqi – [in] Link Quality Indication

uint32_t getChannel()

Retrieve the channel on which the PDU has been received.

Return values:: Channel – number

PDU &getPdu()

Retrieve the received PDU.

Return values:: Received – PDU

uint32_t getFcs()

Retrieve the Frame Check Sequence value.

Return values:

FCS – value
0 – if not available

bool hasRssi()

Determine if the PDU has RSSI information available.

Returns:: True if RSSI is available, false otherwise

int32_t getRssi()

Retrieve the PDU RSSI value.

Return values:: RSSI – value

bool hasFcsValidity()

Determine if the PDU has FCS validity information available.

Return values:: FCS – validity presence

bool isFcsValid()

Determine if the PDU FCS value is valid.

Return values:: FCS – validity

bool hasLqi()

Determine if the PDU Link Quality Indication is available.

Return values:: True – if available, false otherwise.

uint32_t getLqi()

Retrieve the LQI value.

Return values:: LQI – value

bool hasTimestamp()

Determine if the packet timestamp is available.

Return values:: True – if available, false otherwise.

uint32_t getTimestamp()

Retrieve the timestamp value.

Return values:: Timestamp – value

class PduReceived : public whad::dot15d4::Dot15d4Msg 

#include <pdu.hpp>

Public Functions

PduReceived(Dot15d4Msg &message)

Create a PduReceived message from a Dot15d4Msg message.

Parameters:: message – [in] Reference to a ZigbeeMessage

PduReceived(Dot15d4Packet &pdu)

Create a PduReceived message from a dot15d4 packet.

Parameters:: packet – [in] Zigbee packet to include in the message

Dot15d4Packet &getPacket()

Retrieve the Zigbee packet.

Return values:: Reference – to a dot15d4 packet, including PDU and metadata

class RawPduReceived : public whad::dot15d4::Dot15d4Msg 

#include <rawpdu.hpp>

Public Functions

RawPduReceived(Dot15d4Msg &message)

Create a RawPduReceived message from a Dot15d4Msg message.

Parameters:: message – [in] Reference to a ZigbeeMessage

RawPduReceived(Dot15d4Packet &pdu)

Create a RawPduReceived message from a dot15d4 packet.

Parameters:: packet – [in] Zigbee packet to include in the message

Dot15d4Packet &getPacket()

Retrieve the Zigbee packet.

Return values:: Reference – to a dot15d4 packet, including PDU and metadata

class RouterMode : public whad::dot15d4::Dot15d4Msg 

#include <router.hpp>

Public Functions

RouterMode(Dot15d4Msg &message): Parse a message as a RouterMode message.

RouterMode(uint32_t channel)

RouterMode message constructor.

Parameters:: channel – [in] Specify the ZigBee channel to use

uint32_t getChannel()

Retrieve the dot15d4 channel to use.

Return values:: Channel – number

class SendPdu : public whad::dot15d4::Dot15d4Msg 

#include <sendpdu.hpp>

Public Functions

SendPdu(Dot15d4Msg &message): Parse a message as a SendPdu message.

SendPdu(uint32_t channel, uint8_t *pPdu, int length)

SendPdu message constructor.

Parameters:

channel – [in] Specify the 802.15.4 channel to use
pPdu – [in] Pointer to a byte buffer to send
length – [in] PDU length in bytes

uint32_t getChannel()

Retrieve the dot15d4 channel to use.

Return values:: Channel – number

PDU &getPdu()

Retrieve the PDU to send.

Return values:: Reference – to the PDU object containing the bytes to send

class SendRawPdu : public whad::dot15d4::Dot15d4Msg 

#include <sendrawpdu.hpp>

Public Functions

SendRawPdu(Dot15d4Msg &message): Parse a message as a SendRawPdu message.

SendRawPdu(uint32_t channel, uint8_t *pPdu, int length, uint32_t fcs)

SendRawPdu message constructor.

Parameters:

channel – [in] Specify the 802.15.4 channel to use
pPdu – [in] Pointer to a byte buffer to send
length – [in] PDU length in bytes
fcs – [in] PDU frame check sequence (FCS)

uint32_t getChannel()

Retrieve the dot15d4 channel to use.

Return values:: Channel – number

PDU &getPdu()

Retrieve the PDU to send.

Return values:: Reference – to the PDU object containing the bytes to send

uint32_t getFcs()

Retrieve the Frame Check Sequence value.

Return values:: FCS – value

class SetNodeAddress : public whad::dot15d4::Dot15d4Msg 

#include <setnodeaddr.hpp>

Public Functions

SetNodeAddress(Dot15d4Msg &message): Parse a message as a SetNodeAddress message.

SetNodeAddress(AddressType addrType, uint64_t address)

SetNodeAddress message constructor.

Parameters:

addrType – [in] ZigBee device address type (short or extended)
address – [in] Specify the device address to use

AddressType getAddressType()

Retrieve the dot15d4 node address type.

Return values:: Node – address type

uint64_t getAddress()

Retrieve the dot15d4 node address.

Return values:: Node – address

class SniffMode : public whad::dot15d4::Dot15d4Msg 

#include <sniff.hpp>

Public Functions

SniffMode(Dot15d4Msg &message): Parse a message as a SniffMode message.

SniffMode(uint32_t channel)

SniffMode message constructor.

Parameters:: channel – [in] Specify the ZigBee channel to sniff

uint32_t getChannel()

Retrieve the dot15d4 channel to sniff.

Return values:: Channel – number