Ieee802154Mac

compound module

Generic CSMA protocol supporting Mac-ACKs as well as constant, linear or exponential backoff times.

Inheritance diagram

The following diagram shows inheritance relationships for this type. Unresolved types are missing from the diagram.

Known subclasses

Name	Type	Description
Ieee802154NarrowbandMac	compound module	(no description)

Extends

Name	Type	Description
MacProtocolBase	simple module	Module base for different MAC protocols.

Parameters

Name	Type	Default value	Description
interfaceTableModule	string
address	string	"auto"	MAC address as hex string (12 hex digits), or "auto". "auto" values will be replaced by a generated MAC address in init stage 0.
headerLength	int	72 b	length of MAC header
mtu	int	0B
bitrate	double	250000 bps	bit rate
ccaDetectionTime	double	0.000128 s	Clear Channel Assessment detection time
rxSetupTime	double	0 s	Time to setup radio to reception state
aTurnaroundTime	double	0.000192 s	Time to switch radio from Rx to Tx state
useMACAcks	bool		Send/Expect MAC acks for unicast traffic?
macMaxFrameRetries	int	3	Maximum number of frame retransmission, only used when usage of MAC acks is enabled.
macAckWaitDuration	double	0.00056 s	Time to wait for an acknowledgement after transmitting a unicast frame. Only used when usage of MAC acks is enabled. Value is calculated from 1+12+10+12 symbols, which is defined for nonbeacon-enabled PAN. In the non-beacon-enabled case, the receiver responds at aTurnaroundTime (i.e. the time for the sender and receiver to both be guaranteed to have switched from Tx to Rx and vice verse). This gives the value 192us + 352us = 544us (there's been some discussion about the "extra" 1 symbol == 16us) [section 7.5.6.4.2 of the specification].
ackLength	int	40 b	Complete MAC ack message length (in bits) (! headerLength is not added to this), only used when usage of MAC acks is enabled.
sifs	double	0.000192 s	Simple interframe space (12 symbols). Time to wait between receiving a frame and acknowledging it. Should be bigger than the maximum time for switching between Tx and Rx at the receiver. Only used when usage of MAC acks is enabled.
backoffMethod	string	"linear"	Backoff method to use: constant, linear or exponential
macMaxCSMABackoffs	int	5	maximum number of extra backoffs (excluding the first unconditional one) before frame drop
aUnitBackoffPeriod	double	0.00032 s	base unit for all backoff calculations
contentionWindow	int	2	# of backoff periods of the initial contention window (for linear and constant backoff method only)
macMinBE	int	3	minimum backoff exponent (for exponential backoff method only)
macMaxBE	int	8	maximum backoff exponent (for exponential backoff method only)
radioModule	string	"^.radio"	The path to the Radio module //FIXME remove default value

Properties

Name	Value	Description
display	i=block/rxtx
class	Ieee802154Mac

Gates

Name	Direction	Size	Description
upperLayerIn	input
upperLayerOut	output
lowerLayerIn	input
lowerLayerOut	output

Signals

Name	Type	Unit
linkBroken	inet::Packet

Statistics

Name	Title	Source	Record	Interpolation Mode
packetDropNotAddressToUs	packet drop: not addressed to us	packetDropReasonIsNotAddressedToUs(packetDropped)	count, sum(packetBytes), vector(packetBytes)	none
packetDropQueueOverflow	packet drop: queue overflow	packetDropReasonIsQueueOverflow(packetDropped)	count, sum(packetBytes), vector(packetBytes)	none
packetDropBackoffLimitReached	packet drop: backoff limit reached	packetDropReasonIsCongestion(packetDropped)	count, sum(packetBytes), vector(packetBytes)	none
packetDropRetryLimitReached	packet drop: retry limit reached	packetDropReasonIsRetryLimitReached(packetDropped)	count, sum(packetBytes), vector(packetBytes)	none
linkBroken	link break	linkBroken	count	none
packetDropIncorrectlyReceived	packet drop: incorrectly received	packetDropReasonIsIncorrectlyReceived(packetDropped)	count, sum(packetBytes), vector(packetBytes)	none

Scheduled messages (observed)

msg	kind	ctrl	tags	msgname	context
omnetpp::cMessage	0			timer-backoff
omnetpp::cMessage	0			timer-cca

Direct method calls (observed)

call to	function	info
MessageDispatcher	inet::MessageDispatcher::arrived	arrived
PcapRecorder	inet::PcapRecorder::receiveSignal	packetReceivedFromLower
InterfaceTable	inet::InterfaceTable::interfaceChanged	interfaceChanged
ApskDimensionalRadio	inet::physicallayer::ApskRadio::setRadioMode	setRadioMode
ApskScalarRadio	inet::physicallayer::ApskRadio::setRadioMode	setRadioMode
UnitDiskRadio	inet::physicallayer::UnitDiskRadio::setRadioMode	setRadioMode
DropTailQueue	inet::queueing::PacketQueue::pullPacket	pullPacket

Called methods (observed)

function	info	call from
inet::Ieee802154Mac::handleCanPullPacketChanged	handleCanPullPacketChanged	DropTailQueue
inet::Ieee802154Mac::receiveSignal	transmissionStateChanged	ApskDimensionalRadio, ApskScalarRadio, UnitDiskRadio

Incoming messages (observed)

gate	msg	srcModule	tags
lowerLayerIn	Packet	ApskDimensionalRadio	ErrorRateInd, PacketProtocolTag, SignalPowerInd, SignalTimeInd, SnirInd
lowerLayerIn	Packet	ApskScalarRadio	ErrorRateInd, PacketProtocolTag, SignalPowerInd, SignalTimeInd, SnirInd
lowerLayerIn	Packet	UnitDiskRadio	ErrorRateInd, PacketProtocolTag, SignalPowerInd, SignalTimeInd, SnirInd

Outgoing messages (observed)

gate	msg	destModule	tags
lowerLayerOut	Packet	ApskDimensionalRadio	InterfaceReq, MacAddressReq, PacketProtocolTag, DispatchProtocolInd?, NetworkProtocolInd?, SocketReq?
lowerLayerOut	Packet	ApskScalarRadio	InterfaceReq, MacAddressReq, PacketProtocolTag, DispatchProtocolInd?, NetworkProtocolInd?, SocketReq?
lowerLayerOut	Packet	UnitDiskRadio	InterfaceReq, MacAddressReq, PacketProtocolTag, DispatchProtocolInd?, NetworkProtocolInd?, SocketReq?
upperLayerOut	Packet	Arp	DispatchProtocolReq, ErrorRateInd, InterfaceInd, MacAddressInd, PacketProtocolTag, SignalPowerInd, SignalTimeInd, SnirInd
upperLayerOut	Packet	Ipv4	DispatchProtocolReq, ErrorRateInd, InterfaceInd, MacAddressInd, PacketProtocolTag, SignalPowerInd, SignalTimeInd, SnirInd

Pull in messages (observed)

gate	msg	kind	ctrl	srcModule	tags
upperLayerIn	Packet	0		DropTailQueue	InterfaceReq, MacAddressReq, PacketProtocolTag, DispatchProtocolInd?, NetworkProtocolInd?, SocketReq?

Packet operations (observed)

chunkType	packetAction
Ieee802154MacHeader	insertAtFront, peekAtFront, popAtFront

Shared Tagging operations (observed)

tagType	tagAction
DispatchProtocolReq	addTagIfAbsent
InterfaceInd	addTagIfAbsent
MacAddressInd	addTagIfAbsent
MacAddressReq	getTag
PacketProtocolTag	addTagIfAbsent, getTag

Source code

//
// Generic CSMA protocol supporting Mac-ACKs as well as
// constant, linear or exponential backoff times.
//
module Ieee802154Mac extends MacProtocolBase like IMacProtocol
{
    parameters:
        string address @mutable = default("auto"); // MAC address as hex string (12 hex digits), or
                                                   // "auto". "auto" values will be replaced by
                                                   // a generated MAC address in init stage 0.

        // length of MAC header
        int headerLength @unit(b) = default(72 b);
        int mtu @unit(B) = default(0B);
        // bit rate
        double bitrate @unit(bps) = default(250000 bps);

        // Clear Channel Assessment detection time
        double ccaDetectionTime @unit(s) = default(0.000128 s); // 8 symbols
        // Time to setup radio to reception state
        double rxSetupTime @unit(s) = default(0 s);
        // Time to switch radio from Rx to Tx state
        double aTurnaroundTime @unit(s) = default(0.000192 s);    // 12 symbols

        // Send/Expect MAC acks for unicast traffic?
        bool useMACAcks;
        // Maximum number of frame retransmission,
        // only used when usage of MAC acks is enabled.
        int macMaxFrameRetries = default(3);
        // Time to wait for an acknowledgement after transmitting a unicast frame.
        // Only used when usage of MAC acks is enabled.
        // Value is calculated from 1+12+10+12 symbols, which is defined for nonbeacon-enabled PAN.
        // In the non-beacon-enabled case, the receiver responds at aTurnaroundTime
        // (i.e. the time for the sender and receiver to both be guaranteed to have
        // switched from Tx to Rx and vice verse).  This gives the value 192us +
        // 352us = 544us (there's been some discussion about the "extra" 1 symbol == 16us)
        // [section 7.5.6.4.2 of the specification].
        double macAckWaitDuration @unit(s) = default(0.00056 s);
        // Complete MAC ack message length (in bits)
        // (! headerLength is not added to this),
        // only used when usage of MAC acks is enabled.
        int ackLength @unit(b) = default(40 b);
        // Simple interframe space (12 symbols). Time to wait between receiving a frame and acknowledging it.
        // Should be bigger than the maximum time for switching between Tx and Rx at the receiver.
        // Only used when usage of MAC acks is enabled.
        double sifs @unit(s) = default(0.000192 s);

        //Backoff method to use: constant, linear or exponential
        string backoffMethod = default("linear");
        // maximum number of extra backoffs (excluding the first unconditional one) before frame drop
        int macMaxCSMABackoffs = default(5);
        // base unit for all backoff calculations
        double aUnitBackoffPeriod @unit(s) = default(0.00032 s);
        // # of backoff periods of the initial contention window
        // (for linear and constant backoff method only)
        int contentionWindow = default(2);
        // minimum backoff exponent (for exponential backoff method only)
        int macMinBE = default(3);
        // maximum backoff exponent (for exponential backoff method only)
        int macMaxBE = default(8);

        string radioModule = default("^.radio");   // The path to the Radio module  //FIXME remove default value

        @class(Ieee802154Mac);
        @signal[linkBroken](type=inet::Packet);
        @statistic[linkBroken](title="link break"; source=linkBroken; record=count; interpolationmode=none);
        @statistic[packetDropNotAddressToUs](title="packet drop: not addressed to us"; source=packetDropReasonIsNotAddressedToUs(packetDropped); record=count,sum(packetBytes),vector(packetBytes); interpolationmode=none);
        @statistic[packetDropIncorrectlyReceived](title="packet drop: incorrectly received"; source=packetDropReasonIsIncorrectlyReceived(packetDropped); record=count,sum(packetBytes),vector(packetBytes); interpolationmode=none);
        @statistic[packetDropQueueOverflow](title="packet drop: queue overflow"; source=packetDropReasonIsQueueOverflow(packetDropped); record=count,sum(packetBytes),vector(packetBytes); interpolationmode=none);
        @statistic[packetDropRetryLimitReached](title="packet drop: retry limit reached"; source=packetDropReasonIsRetryLimitReached(packetDropped); record=count,sum(packetBytes),vector(packetBytes); interpolationmode=none);
        @statistic[packetDropBackoffLimitReached](title="packet drop: backoff limit reached"; source=packetDropReasonIsCongestion(packetDropped); record=count,sum(packetBytes),vector(packetBytes); interpolationmode=none);
}

File: src/inet/linklayer/ieee802154/Ieee802154Mac.ned