Proto commits in adjacentlink/emane

These 17 commits are when the Protocol Buffers files have changed:

2023-06-21

Initial development of the Bent Pipe radio model: a generic regenerative bent-pipe (u-bend) satellite model. The model supports configuration of one or more transponders, where each transponder may operate in ubend or process mode. A transponder operating in ubend mode will relay any successfully received over-the-air uplink frame over its downlink channel. A transponder operating in process mode will forward any successfully received over-the-air frame up the stack for processing. Bent Pipe differentiates between operating as a satellite or ground station solely based on transponder receive action, either ubend or process, and can be configured as a satellite with inter-satellite links by using a combination of ubend and process transponders. The Bent Pipe radio model supports: * Multiple Transponders: Per Transponder receive action ubend or process * Configurable Channel Access: Per Transponder TDMA or No-protocol channel access * Multiple Antenna: Ideal omni or profile defined with per transponder receive and transmit antenna assignment * Aggregation and Fragmentation: Per transponder MTU specification * Boundary Transponder Selection: Mapping priority to transponder index for downstream frame transmission in process mode * Packet Completion Rate Curves: Per transponder PCR curve selection

The documentation is generated from this commit.

2022-02-16

Added spectral mask support to the emulator physical layer to model the effects at receiving nodes from transmitters that radiate energy at frequencies (side lobes and spurs) outside its defined bandwidth (main lobe/beam). A spectral mask manifest defines one or more spectral masks, where the spectral mask manifest is defined using the emulator (<platform>) spectralmaskmanifesturi configuration parameter: <param name="spectralmaskmanifesturi" value="spectralmasks.xml"/> As long as at least one NEM in an emulation is using spectral masks, all emulator instances must use the same spectral mask manifest -- with the respective in use mask ids defined. A spectral mask is composed of a primary signal and zero or more spurs. Each spectral mask must have a unique non-zero id. <spectral-mask-manifest> <mask id='1'> <primary> <width hz='1M' dBr='0'/> </primary> </mask> <mask id='2'> <primary> <width hz='500K' dBr='-50'/> <width hz='500K' dBr='-30'/> <width hz='1M' dBr='0'/> <width hz='500K' dBr='-30'/> <width hz='500K' dBr='-50'/> </primary> </mask> <mask id='3'> <primary> <width hz='500K' dBr='-50'/> <width hz='500K' dBr='-30'/> <width hz='1M' dBr='0'/> <width hz='500K' dBr='-30'/> <width hz='500K' dBr='-50'/> </primary> <spurs> <spur offset_from_center_hz='1G'> <width hz='10K' dBr='10'/> </spur> </spurs> </mask> </spectral-mask-manifest> Spectral mask primary and spur elements are defined using one or more contiguous segments specified in length (hz) and a reference power offset (dBr) to be applied to the received signal with accounting for overlap percentage. Additionally, spurs contain an offset from the center transmit frequency. By default, the emulator physical layer uses a square mask across the entire transmit bandwidth. When using spectral masks, the transmit bandwidth is determined at the receiver to be the total width defined by the respective mask element segments. Compatibility mode 1 and 2 radio models can use the emulator physical layer configuration parameter spectralmaskindex to set the spectral mask to use when transmitting. Compatibility 2 radio models can dynamically change the transmit mask as part of MIMOTransmitPropertiesControlMessage. Added emulator physical layer ObservedPowerTable showing the calculated observed power for the last received segment organized by transmitter, rx antenna, tx antenna, frequency, and mask.

2021-06-01

Added lognormal fading model to the emulator physical layer. The Lognormal EMANE fading model was created to more accurately model Free Space Optical (FSO) loss, but is written in a purely statistical manner so it may have other uses. The model works by creating a constant series of fades, each of which has a constant fade depth that may or may not cause packet loss. The model keeps internal state on the time each fading period ends, and generates a new fading period once a packet arrives after the current fading period has ended. Fade depths (related to the effective pathloss experienced during the fade) are lognormally distributed (but constant during a given fading period). Fade lengths are normally distributed. Some of the model parameters (thresholds, pathloss values) are used to relate the fading depth to EMANE-relevant pathloss to cause a corresponding amount of packet loss. Note that there is an inverse relationship for the fading depths and pathloss values -- lower values for fading depth result in 100% loss, while higher values result in no loss. For values between the thresholds, linear interpolation is done to calculate a corresponding pathloss value that may result in random probability drops during the fading period. The following configuration parameters were added/modified: fading.model: 'lognormal' can be specified in addition to 'none', 'event', and 'nakagami'. Running-state modifiable. lognormal.dmu: lognormal fading depth mu (mean of underlying normal distribution). Running-state modifiable. lognormal.dsigma: lognormal fading depth sigma (standard deviation of underlying normal distribution). Running-state modifiable. lognormal.dlthresh: lognormal fading depth lower threshold (below this threshold is 0% POR/100% loss). Running-state modifiable. lognormal.duthresh: lognormal fading depth upper threshold (above this threshold is 100% POR/0% loss). Running-state modifiable. lognormal.maxpathloss: pathloss value (in dBm) corresponding to the fading depth lower threshold (0% POR/100% loss). Running-state modifiable. lognormal.minpathloss: pathloss value (in dBm) corresponding to the fading depth upper threshold (100% POR/0% loss). Running-state modifiable. lognormal.lmean: lognormal fading length mean in seconds (normal distribution). Running-state modifiable. lognormal.lstddev: lognormal fading length standard deviation in seconds (normal distribution). Running-state modifiable. Test cases were updated to reflect changes to physical layer configuration.

2020-12-23

Added MIMO capability to the physical layer. The physical layer supports MIMO by allowing simultaneous use of multiple transmit and receive antenna. Waveform implementation specifics are modeled within the radio model, with MIMO control messages conveying transmit and receive information between the layers. EMANE 1.2.x Compatibility The MIMO capable physical layer is backward compatible with all radio models currently working with the emane 1.2.x non-MIMO API, allowing over-the-air compatibility between MIMO (compat 2) and non-MIMO (compat 1) radio models. Existing compat 1 radio models will require a recompile and link with the latest emane. No radio model source modification required. A new physical layer compatibilitymode parameter is used to select between the non-MIMO API and the MIMO API. The compatibilitymode parameter defaults to 1 for the emane 1.2.x non-MIMO API. Radio models wishing to use the MIMO API should set compatibilitymode to 2. All new radio models should use the compat 2 API, even if not modeling MIMO features. Multiple Antenna Using MIMO API control messages, a radio model can define any number of receive antenna (ideal omni or antenna profile defined), and likewise, define multiple transmit antenna for each over-the-air transmission. Every received over-the-air message will be processed once for each receive path, where the total number of receive paths is equal to the number of transmit antenna multiplied by the number of receive antenna. Receive antennas are added using the RxAntennaAddControlMessage, updated using the RxAntennaUpdateControlMessage, and removed using the RxAntennaRemoveControlMessage. When adding a receive antenna, a unique antenna index must be specified along with the frequency of interest information for the antenna and the antenna type: ideal omni (fixed gain) or antenna pattern defined (profile id and pointing). The unique index value supplied during RxAntennaAddControlMessage is how an antenna is referenced during an update or remove. It is also how per antenna receive power information is identified when communicating received over-the-air transmissions to the radio model via MIMOReceivePropertiesControlMessage. When sending an over-the-transmission, a radio model specifies one or more transmit antenna along with one or more groups of frequency segments using MIMOTransmitPropertiesControlMessage. Each transmit antenna may be mapped to its own unique group of frequency segments or share a group with other transmit antennas. Each transmit antenna is specified using a unique antenna index value which is unrelated to indexes used when adding receive antennas via RxAntennaAddControlMessage. A radio model is free to use the same index for receive and transmit antennas to create its own logical association of the same antenna being used for both receive and transmit. The physical layer does not store any transmit antenna information in the downstream direction. In the upstream (receive) direction, the physical layer caches computed gain information when using antenna profiles, so it is important to be consistent when indexing transmit antennas when sending over-the-air transmissions. For example, if NEM 1 has antenna A1 and antenna A2, where A1 is pointing at Az1,El1 and A2 is pointing at Az2,El2, sending over-the-air messages and alternating or changing transmit antenna indexes while not updating position and/or pointing, will defeat any possible receive side caching gains which are keyed off of transmit antenna index. Pick indexes for A1 and A2, then be consistent so receiving physical layers will not invalidate cached antenna gains unless actual position and/or pointing updates dictate so. Antenna Defaults When adding a receive antenna with RxAntennaAddControlMessage, use one of the following to create the antenna: Antenna Antenna::createDefault(); Antenna Antenna::createIdealOmni(AntennaIndex antennaIndex, double dFixedGaindBi); Antenna Antenna::createProfileDefined(AntennaIndex antennaIndex, const Pointing & pointing = {}); createDefault: Creates a default antenna which will either be an ideal omni with a fixed gain or a profile defined antenna, based on the physical layer fixedantennagain configuration parameter. createIdealOmni: Creates an ideal omni antenna with a specified fixed gain. createProfileDefined: Creates an antenna profile defined antenna with an optional initial pointing. If the newly created receive antenna does not have it's bandwidth set, the physical layer will use the value from its bandwidth configuration parameter. If the RxAntennaAddControlMessage contains an empty frequency of interest set, the physical layer will use the value(s) from its frequencyofinterest configuration parameter. When sending a MIMOTransmitPropertiesControlMessage, use one of the following to create the transmit antenna: Antenna Antenna::createIdealOmni(AntennaIndex antennaIndex, double dFixedGaindBi); Antenna Antenna::createProfileDefined(AntennaIndex antennaIndex, const Pointing & pointing = {}); Use an empty antenna set when creating a MIMOTransmitPropertiesControlMessage to indicate use of the default antenna configuration, which follows the same assignment logic as createDefault(). If the newly created antenna does not have it's bandwidth set, the physical layer will use the value from its bandwidth configuration parameter. If any frequency segment has a 0 Hz frequency, the physical layer will use the value from its frequency configuration parameter. If any frequency segment does not specify a transmit power, the physical layer will use the value from its txpower configuration parameter. Antenna Profiles and Pointing MIMO API radio models using antenna profiles must specify pointing information in every over-the-air transmission as part of MIMOTransmitPropertiesControlMessage. The MIMO compatible physical layer supports event compatibility with compat 1 radio models using external AntennaProfileEvents, where, the AntennaProfileEvent allows for specifying profile and pointing information for a single antenna (always index 0) for each specified NEM. When using the MIMO API to point and transmit simultaneously, and modeling a logical re-pointing of the same antenna for receive, you must specify both a MIMOTransmitPropertiesControlMessage and a RxAntennaUpdateControlMessage in order for the pointing to take effect for receive. Spectrum Windows Each receive antenna has its own view of the spectrum, which internally maps to a unique spectrum monitor instance. When processing received over-the-air transmissions, radio models should wait for end-of-reception and then query for a spectrum window from each receive antenna using: SpectrumWindow SpectrumServiceProvider::requestAntenna(AntennaIndex antennaIndex, std::uint64_t u64FrequencyHz, const Microseconds & duration, const TimePoint & startTime); Using the requested SpectrumWindow(s), the MIMOReceivePropertiesControlMessage, and the contents of the radio model specific header, a radio model can perform its MIMO or non-MIMO receive processing. Receive Sensitivity Promiscuous Mode Sometimes it may be advantageous to know when an over-the-air message has been dropped by the physical layer because every contained frequency segment was below the thermal noise floor. Setting the physical layer rxsensitivitypromiscuousmodeenable configuration parameter to true will cause the physical layer to send upstream messages to the radio model when the receive sensitivity check fails. These messages will not contain a MIMOReceivePropertiesControlMessage, indicating the occurrence of an over-the-air message that cannot be processed.

2020-03-11

Added physical spectrum filter support. A physical layer spectrum filter records spectrum energy based on a set of specified criteria. Filter spectrum windows are queried similar to spectrum energy windows, and are used in conjunction with spectrum energy windows to perform actions such as excision and cancellation. A radio model adds one or more spectrum filters using SpectrumFilterAddControlMessage instances in sendDownstreamControl: SpectrumFilterAddControlMessage::create(1, // filter index 1000000000, // center freq 20000000, // bandwidth 100000, // sub-band width in hz BandwidthFilterElementLessEqual::create(100000)) A radio model removes one or more spectrum filters using SpectrumFilterRemoveControlMessage instances in sendDownstreamControl: Controls::SpectrumFilterRemoveControlMessage::create(1) Where, 1 is a unique filter index assigned by a radio model and used to specify the filter. Filter range is specified as a center frequency (Hz), bandwidth (Hz), optional sub-band width (Hz), and an optional match criterion. In the above example, the filter will record all energy in the range 1GHz +/- 10MHz that is <= 100KHz wide. Energy will be recorded in sub-bands of 100KHz. By default, filters do not record energy with the same subid as their associated physical layer (in-band waveform). Set the physical layer 'excludesamesubidfromfilterenable' to 'false' to allow filter processing of in-band spectrum energy and add SubIdFilterElementEqual::create(0) to the FilterMatchCriterion expression. Where, subid 0 means match the radio model's associated physical layer subid. Match criterion may be specified using: * FrequencyFilterElementLess * FrequencyFilterElementLessEqual * FrequencyFilterElementGreater * FrequencyFilterElementGreaterEqual * FrequencyFilterElementEqual * FrequencyFilterElementNotEqual * BandwidthFilterElementLess * BandwidthFilterElementLessEqual * BandwidthFilterElementGreater * BandwidthFilterElementGreaterEqual * BandwidthFilterElementEqual * BandwidthFilterElementNotEqual * SubIdFilterElementLess * SubIdFilterElementLessEqual * SubIdFilterElementGreater * SubIdFilterElementGreaterEqual * SubIdFilterElementEqual * SubIdFilterElementNotEqual * FilterDataFilterElementEqual * FilterDataFilterElementNotEqual More complex compound expressions are created using: * FilterMatchCriterionAnd * FilterMatchCriterionOr * FilterMatchCriterionNot FilterData is opaque data a radio model can attach to a downstream packet to allow additional match criteria. This opaque data can be used in conjunction with a custom FilterMatchCriterion when creating the FilterMatchCriterion expression, or with FilterDataFilterElementEqual and FilterDataFilterElementNotEqual: SpectrumFilterAddControlMessage::create(2, // Filter Index 2347000000, // Freq 1GHz 20000000, // 20 MHz bandwidth 0, // no sub-bands FilterDataFilterElementEqual::create("Hello World!")); A radio model uses the SpectrumFilterDataControlMessage to add FilterData when sending a downstream packet: sendDownstreamPacket(CommonMACHeader{type_, u16SequenceNumber_++}, pkt, {Controls::SpectrumFilterDataControlMessage::create("Hello World!"), ... }) A radio model queries spectrum filter energy using SpectrumServiceProvider::requestFilter: auto windowFilter = pRadioService_->spectrumService().requestFilter(1, span, startOfReception); Where, the returned filter window is a SpectrumFilterWindow instance. In this instance, the filter was added with a sub-band width causing the energy values contained in the spectrum window to be: [TO_SUB_0,TO_SUB_1,...,TO_SUB_N,T1_SUB_0,T1_SUB_1,...,T1_SUB_N,...] The number of sub-band entries per time bin (N) is returned as the last item in the windowFilter tuple: auto subBandBinCount = std::get<5>(windowFilter);

2017-09-14

Added proto2 syntax statement to all protocol buffer specifications.

2017-08-31

Merge branch 'feature/fading' into develop See https://github.com/adjacentlink/emane/pull/77

2017-08-30

Added Nakagami-m fading support to the emulator physical layer. The emulator physical layer supports per source fading model selection that can be modified via fading selection events. The following configuration parameters were added: fading.model: One of either 'none', 'event' or 'nakagami'. Selecting event requires fading selection events in order to determine the fading model to use per NEM source. Running-state modifiable. fading.nakagami.distance0 = Distance used for lower bound shape selection. Running-state modifiable. fading.nakagami.distance1 = Distance used for upper bound shape selection. Running-state modifiable. fading.nakagami.m0: Shape factor to use for distance < fading.nakagami.distance0. Running-state modifiable. fading.nakagami.m1: Shape factor to use for distance >= fading.nakagami.distance0 and < fading.nakagami.distance1. Running-state modifiable. fading.nakagami.m2: Shape factor to use for distance >= fading.nakagami.distance1. Running-state modifiable. Additional drop table columns were added for fading related drops: Fade Location, Fade Algorithm and Fade Select. Fade Location indicates fading was enabled but source and/or destination location is unknown. Fade Algorithm indicates the selected fading model was unable to calculate receive power due to an internal error. Fade Select indicates no fading model selection was made for the NEM source. The physical layer FadingSelectionInfoTable table lists the fading model used per NEM source. nem 1 phy FadingSelectionInfoTable | NEM | Model | | 2 | none | | 3 | nakagami | Note: This table only reflects the fading model used when the fading.model configuration parameter is set to event. The emaneevent-fadingselection utility can be used to quickly set the fading model selection of 1 or more NEMs: emaneevent-fadingselection 1:10 nakagami -i lo The EEL fadingselection sentence parser adds fading selection support to EEL scenarios: <time> nem:<Id> fadingselection nem:<Id>,'none'|'nakagami' [nem:<Id>,'none'|'nakagami']... Test cases were updated to reflect changes to physical layer configuration and drop table output. White space cleanup.

2017-06-16

Added functionality to the OTAManager to allow fragmenting OTA messages based on a configurable MTU value. This functionality allows for emulating waveforms with burst rates greater than what can be supported via the UDP multicast OTA channel. Three new configuration items were added to support OTA fragmentation: * otamanagermtu - MTU to enforce. Set to 0 to disable fragmentation. * otamanagerpartcheckthreshold - Rate in seconds to check if part reassembly efforts should be abandoned due to missing fragments. * otamanagerparttimeoutthreshold - Threshold in seconds to wait for another fragment before abandoning a specific packet reassembly. An additional column was added to the OTAChannelPacketCountTable emulator statistic table to indicate the number of packets dropped by the emulator due to missing one or more fragments broken out by source. A new statistic dropnumOTAChannelUpstreamPacketsDroppedMissingPart was added to indicate total packets dropped due to missing fragments. This functionality breaks OTA message compatibility with previous versions of emane.

2015-12-02

Add transmit power level to frequency segments. The addition permits each frequency segment to be transmitted at a different power. When specified, the frequency segment power level takes precedent over the transmitter power levels specified in the transmitter control messages.

2015-08-13

Renamed tdmabasemodelheader.proto to tdmabasemodelmessage.proto to better reflect that the model sends messages instead of prepending headers to downstream packets.

2015-06-19

The radio model was modified to create its own message format which is used to transmit message components instead of the more traditional emane notion of packets. Depending on whether aggregation and fragmentation are enabled, the radio model will transmit one or more message components per transmission. A message component, depending on slot and message data size, can be one or more entire downstream packets, a portion (fragment) of one or more downstream packets or some combination thereof. A single over-the-air transmission may contain a mixture of both unicast and broadcast message components, where unicast components can be for different destinations. Added QueueManager support to dequeue packets from other queues (highest priority) first, if there are no message components available for the specified queue. This can be disabled using the queue.strictdequeueenable config parameter. Added QueueManager support for aggregation and fragmentation of outbound transmissions. Support includes the ability to disable aggregation (queue.aggregationenable), disable fragmentation (queue.fragmentationenable) and when enabled, to set an aggregation message (slot) size threshold (queue.aggregationslotthreshold). Two config parameters: fragmentcheckthreshold and fragmenttimeoutthreshold are used to control abandoning reassembly on lost fragments. Added ReceiveManager support for aggregated message components and fragmentation reassembly. The ReceiveManager will handle aggregation and fragmentation of inbound messages even when the model is configured to not aggregate or fragment transmissions. Added QueueStatusTable and QueueFragmentHistogram to monitor performance. Added one of each per queue: UnicastByteAcceptTable, BroadcastByteAcceptTable, UnicastByteDropTable and BroadcastByteDropTable to monitor processed and dropped messages (in bytes).

2015-05-13

Added initial TDMA Base radio model functionality and event scheduler module. Initial functionality includes: schedule event processing, emanesh event components for authoring and publishing schedules, tx and rx processing, priority and destination queue management, upstream SINR POR curve logic and slot structure performance tables.

2014-07-03

Added the ability to instantiate transport plugins within the emulator (internal transports) as an NEM layer stack entry. This eliminates the need for running emanetransportd in all use cases where emane and emanetransportd are running on the same node. Transports that are internal to the NEM no longer require platformendpoint and transportendpoint configuration parameters. In order to connect an emulator with an external transport, either running in emanetransportd or embedded in another application, you will have to add a transport='external' attribute to the <nem> platform XML elements and specify both platformendpoint and transportendpoint. Internal transports are now the default. In order to support internal transports, DTDs were changed to remove the often confusing <transport> is not in the proper place when defining an NEM. Existing XML will have to place <transport> at the top of layer definitions instead of the bottom, this is where it logically belongs. The Remote Control Port protobuf specification and emanesh were modified to support configuration, statistic and statistic table access for internal transports. emanegentransportxml was modified to ignore internal transports. Fixed flow control token grant acknowledgment bug. See https://github.com/adjacentlink/emane/issues/8.

2014-03-16

Added received OTA UUID to PacketInfo Changed Common MAC Header sequence number to 64 bit Refactored NeighborMetricManager missed packet logic to use PacketInfo UUID to indicate remote NEM restart

2014-02-27

Renamed protocol buffer log level enumerations to avoid collision with possible -DDEBUG preprocessor definition

2014-02-10

Migration to git