EMANE  1.2.1
Emulator Physical Layer

Radio Model Interfacing

A radio model interfaces with the emulator physical layer using ControlMessages.

FrequencyControlMessage

The Controls::FrequencyControlMessage is used in both upstream and downstream packet processing and only valid when received as an argument to UpstreamTransport::processUpstreamPacket or DownstreamTransport::processDownstreamPacket.

In the downstream direction, a radio model must send a FrequencyControlMessage with every DownstreamPacket. This control message is used to specify one or more FrequencySegments to use during message transmission and to optionally set the transmitter bandwidth.

Radio model send downstream packet example with a FrequencyControlMessage:

sendDownstreamPacket(CommonMACHeader(type_, u64TxSequenceNumber_++),
pkt,
{Controls::FrequencyControlMessage::create(0, // bandwidth (0 means use phy default)
{{0, pendingDownstreamQueueEntry_.durationMicroseconds_}}), // freq (0 means use phy default)
Controls::TimeStampControlMessage::create(sot)});

For a FrequencyControlMessage to be valid it must contain at least one FrequencySegment. A FrequencySegment contains the segment center frequency, the segment offset from the CommonPHYHeader transmission time and the segment duration. A special frequency value of 0 Hz will cause the physical layer to use its configured frequency. Likewise, a FrequencyControlMessage with a bandwidth of 0 Hz will cause the physical layer's configured bandwidth to be used.

In the upstream direction, the physical layer will send a FrequencyControlMessage that contains each received FrequencySegment along with the segment's receive power in dBm with every UpstreamPacket.

Physical Layer send upstream packet example with a FrequencyControlMessage:

// send to mac with associated control messages
sendUpstreamPacket(pkt,
{Controls::FrequencyControlMessage::create(commonPHYHeader.getBandwidthHz(),
resultingFrequencySegments),
Controls::ReceivePropertiesControlMessage::create(sot,
propagationDelay,
span,
dReceiverSensitivitydBm_)});

The SpectrumMonitor will remove FrequencySegments that are below receiver sensitivity. Provided there is at least one FrequencySegment remaining, an UpstreamPacket will be sent to the radio model for processing.

An OTA message that matches physical layer registration id and physical layer subid and contains at least one FrequencySegment that is not in the frequency of interest list, will cause the entire message to be treated as out-of-band noise.

TransmitterControlMessage

The Controls::TransmitterControlMessage is used in downstream packet processing and only valid when received as an argument to DownstreamTransport::processDownstreamPacket.

A radio model can send a TransmitterControlMessage to indicate more than one transmitter is sending the OTA message as part of a collaborative transmission (constructive interference). This will result in a single OTA message with multiple transmitters.

When the physical layer receives an OTA collaborative transmission it will sum up the receive powers for each frequency segment before sending the message to the radio model for processing.

Radio model send downstream packet example with a TransmitterControlMessage:

// the pkt
DownstreamPacket pkt{PacketInfo{id_, dst_, 0, Clock::now()}, PAYLOAD_BUFFER, u16PacketSize_};
ControlMessages msgs = {Controls::TransmitterControlMessage::create(transmitters_),
Controls::FrequencyControlMessage::create(u64BandwidthHz_,
frequencySegments_)};
if(antennaProfileId_)
{
msgs.push_back(Controls::AntennaProfileControlMessage::create(antennaProfileId_,
dAntennaAzimuthDegrees_,
dAntennaElevationDegrees_));
}
// send pkt to phy
sendDownstreamPacket(pkt, msgs);

TimeStampControlMessage

The Controls::TimeStampControlMessage is used in downstream packet processing and only valid when received as an argument to DownstreamTransport::processDownstreamPacket.

A radio model can send a TimeStampControlMessage to specify the transmission time stamp used in the CommonPHYHeader. This time should be the start-of-transmission time for the message.

Radio model send downstream packet example with a TimeStampControlMessage:

sendDownstreamPacket(CommonMACHeader(type_, u64TxSequenceNumber_++),
pkt,
{Controls::FrequencyControlMessage::create(0, // bandwidth (0 means use phy default)
{{0, pendingDownstreamQueueEntry_.durationMicroseconds_}}), // freq (0 means use phy default)
Controls::TimeStampControlMessage::create(sot)});

If this control message is not present the physical layer will use the current time as the transmission time stamp.

ReceivePropertiesControlMessage

The Controls::ReceivePropertiesControlMessage is used in upstream packet processing and only valid when received as an argument to UpstreamTransport::processUpstreamPacket.

The physical layer will send a ReceivePropertiesControlMessage with every UpstreamPacket packet. This control message contains the message transmission time, propagation delay, span and receiver sensitivity. See Interpreting a Spectrum Window for more information.

Physical Layer send upstream packet example with a Controls::ReceivePropertiesControlMessage:

// send to mac with associated control messages
sendUpstreamPacket(pkt,
{Controls::FrequencyControlMessage::create(commonPHYHeader.getBandwidthHz(),
resultingFrequencySegments),
Controls::ReceivePropertiesControlMessage::create(sot,
propagationDelay,
span,
dReceiverSensitivitydBm_)});

AntennaProfileControlMessage

The Controls::AntennaProfileControlMessage is used in downstream processing and only valid when received as an argument to DownstreamTransport::processDownstreamPacket or DownstreamTransport::processDownstreamControl.

A radio model can send an AntennaProfileControlMessage to change the current antenna profile id and antenna pointing information. All physical layer instances must be aware of each others antenna profile id and antenna pointing information.

If the physical layer receives an AntennaProfileControlMessage as an argument to processDownstreamControl, it will send an Events::AntennaProfileEvent to inform all NEMs of the change.

Events::AntennaProfiles profiles{{id_,
pAntennaProfileControlMessage->getAntennaProfileId(),
pAntennaProfileControlMessage->getAntennaAzimuthDegrees(),
pAntennaProfileControlMessage->getAntennaElevationDegrees()}};
gainManager_.update(profiles);
pPlatformService_->eventService().sendEvent(0,Events::AntennaProfileEvent{profiles});

If the physical layer receives an AntennaProfileControlMessage as an argument to processDownstreamPacket, it will attach an AntennaProfileEvent to the packet using DownstreamPacket::attachEvent. This attached event will be processed by all other physical layers as if it were sent over the event channel with the additional guarantee that it will be processed before the packet is processed.

Events::AntennaProfiles profiles{{id_,
pAntennaProfileControlMessage->getAntennaProfileId(),
pAntennaProfileControlMessage->getAntennaAzimuthDegrees(),
pAntennaProfileControlMessage->getAntennaElevationDegrees()}};
gainManager_.update(profiles);
pkt.attachEvent(0,Events::AntennaProfileEvent{profiles});