iAcommsDriver

iAcommsDriver provides our standard interface between MOOS and the WHOI uModem. It implements the GOBY uModem driver class and allows other MOOS applications to make use of the modem through several MOOS variables.  It provides two main methods of interface.  The unified interface should be used by new applications, at least for receiving acomms messages.  The simple interface is primarily designed for a human to use with uPokeDB, but can provide adequate transmission functionality for some applications.  

Simple Interface

Great for simple applications or human use.

Transmitting

Transmitting is very easy - simply post a string to the variable ACOMMS_TRANSMIT_DATA and the modem will immediately send that data if it is not currently receiving or transmitting data. The variable ACOMMS_DRIVER_STATUS indicates whether the modem is ready (0), transmitting (1), or receiving (2). The transmission rate and destination can be set by posting the the variables ACOMMS_TRANSMIT_RATE and ACOMMS_TRANSMIT_DEST. If sending non-ASCII data, post a binary string to ACOMMS_TRANSMIT_DATA_BINARY instead.  

Request an ack by posting 1 to ACOMMS_REQUEST_ACK.  

Lockout transmits by posting 1 to ACOMMS_TRANSMIT_LOCKOUT.

Receiving

Whenever a transmission is received, information about the reception is posted to several variables:

  • ACOMMS_RECEIVED_DATA - binary string type - contains all the received data. Data from multiple frames is concatenated together, even if frames in the middle are missing.
  • ACOMMS_BAD_FRAMES - string type - comma delimited list of bad frame indices
  • ACOMMS_SOURCE_ID - double type - integer ID of the transmitting modem
  • ACOMMS_DEST_ID - double type - integer ID of the destination modem (0 = broadcast)
  • ACOMMS_RATE - double type - integer rate of the transmission
  • ACOMMS_RECEIVED_STATUS - double type - integer indicated status. 0=good, 1=partial, 2=bad
  • ACOMMS_ONE_WAY_TRAVEL_TIME - double type - posted if synced to pps, or requesting two-way ranging
  • ACOMMS_STATS_SNR_OUT
  • ACOMMS_STATS_SNR_IN
  • ACOMMS_STATS_DQF
  • ACOMMS_STATS_STDDEV_NOISE
  • ACOMMS_STATS_MSE
  • ACOMMS_STATS_DOPPLER
  • ACOMMS_STATS_SPL
  • ACOMMS_STATS_PSK_ERROR_CODE

Unified Interface

Sometimes the simple interface is cumbersome because applications have to subscribe to many variable to get enough information about incoming acomms transmissions. With the unified interface, only one variable is required to send or receive data.  The HoverAcomms library provides a number of useful functions for creating and interpreting the transmission and reception objects.

Transmitting

Use the AcommsTransmission class defined in the HoverAcomms library. Post the serialized object to ACOMMS_TRANSMIT and the acomms driver will set the rate, destination, data, etc. all from the information stored in that object.

Receiving

With each receipt an object of the AcommsReception class defined in the HoverAcomms libary is posted to the binary string ACOMMS_RECEIVED. 

Logging

Several postings are made specifically for logging purposes, but applications may use them as well. These postings are always enabled. The serial communications between the host and modem are also recorded in a goby_log.txt file in the same directory pLogger uses.

Transmitting

  • ACOMMS_TRANSMITTED_DATA_HEX - string - a hex translation of the transmitted data
  • ACOMMS_TRANSMITTED_ALL - string - a loggable serialization of the transmission protobuf

Receiving

  • ACOMMS_RECEIVED_ALL - string - a loggable serialization of the reception protobuf
  • ACOMMS_RECEIVED_DATA_HEX - string - a hex translation of the received data
  • ACOMMS_IMPULSE_RESPONSE - string - self explanatory

Additional Options and Special Rates

Mini Packets - Rate 100

Just a 13-bit packet. If only one byte is provided, it will be packed with a leading 0x00. If two or more bytes are provided, only the first two bytes will be taken and a bitwise and with 0x1f will be performed on the first byte. Examples:

0x6161 --> 0x0161
0x0061 --> 0x0061
0x6100 --> 0x0100
0x61 --> 0x0061

FSK or PSK encoding can be set using the "PSK_minipackets" process config. Default is FSK.

REMUS LBL - Rate 101

A ping that contains no data. Each LBL transponder in the water will yield a range response. As many as four responses are published in comma delimited form to REMUS_LBL_TIMES.

Two Way Ranging - Rate 102

Must set a destination ID.  Range return should arrive as an independent reception.  

One Way Ranging

Enabled using the "enable_ranging" process config, this option syncs all transmissions to a PPS pulse provided by PPS. Both sending and receiving modems must have this option enabled to work. The travel time will be posted to ACOMMS_ONE_WAY_TRAVEL_TIME and is also contained in the AcommsReception object.

Scheduler

Use the MOOS config line "use_scheduler" to enable use with the application pAcommsScheduler. This will substitute the following subscriptions:

  • ACOMMS_TRANSMIT_DATA --> SCHEDULER_TRANSMIT_DATA
  • ACOMMS_TRANSMIT_DATA_BINARY --> SCHEDULER_TRANSMIT_BINARY
  • ACOMMS_TRANSMIT --> SCHEDULER_TRANSMIT

Other Variables

Publications

  • ACOMMS_DRIVER_WARNING - string - debug warnings
  • SYSTEM_TIME_SECONDS - double - time of system clock from midnight, used for synchronization purposes.
  • VIEW_RANGE_PULSE - blue for transmissions; green, yellow, or red for receptions depending on status.

Subscriptions

Quirks and Works in Progress

  • Two way ranging
  • Driver crashes if pLogger is not started first
  • Acomms stats may be incorrect if, for example, one and a fraction of three available frames are used

pAcommsSimulator

pAcommsSimulator is designed to run on the shoreside MOOS community and provide a simulation back-end for any number of connected iAcommsDriver's.  The acomms simulator is in active development and new feature requests or bug reports are welcome.  Please email jleight@mit.edu.

Simulator Configuration

ProcessConfig = pAcommsSimulator
{
    IterateMode = 0    // regular iterate and mail
    AppTick     = 20

    sound_speed = 1450  // m/s
    p_partial_loss = 0.1
    p_complete_loss = 0.1
    p_sync_loss = 0.1
    p_loss_per_frame = 0.5
}

The currently loss configuration is:
    p_partial_loss - probability that some, but not all frames are lost.  In the case of single-frame packets, partial losses cannot occur.  
    p_complete_loss - probability that all frames are lost, but the packet is still received.  One way ranging will also still occur.
    p_sync_loss - probability that a packet is not heard at all.  The receiver will never enter the receiving state.
    p_loss_per_frame - given that a partial loss occurs, the probability that any given frame within the packet is lost.  If no frames are lost after this probability is applied, one frame is randomly selected to be lost.  Similarly, if all frames are lost, one frame is randomly preserved.  

Given this configuration, the probability of no loss is simply:
    p_no_loss = 1 - (p_partial_loss + p_complete_loss + p_sync_loss)

Except in the case of single-frame packets where it is:
    p_no_loss = 1 - (p_complete_loss + p_sync_loss) 

Driver Configuration

iAcommsDriver communicates with pAcommsSimulator by establishing a connection to the same MOOSDB the simulator is running on.  An example iAcommsDriver configuration for simulation:

ProcessConfig = iAcommsDriver
{
    IterateMode = 0    // regular iterate and mail
    AppTick     = 5
    PortName = /dev/ttyUSB1
    ID       = 5

    PSK_minipackets   = false
    enable_ranging    = true
    show_range_pulses = true

    in_sim = true
    sim_server = localhost
    sim_port = 9000
}

In this case, the shoreside MOOS community on which pAcommsSimulator is running is found at localhost, port 9000.  

Features

Implemented:

  • Approximate timing of transmission/reception length for different rates
  • All standard rates and mini packets
  • One way travel times
  • All fields used by HoverAcomms library

Not implemented:

  • Complete / accurate receive statistics
  • LBL pings
  • two way ranging
  • time warp

If you are using the HoverAcomms library to interact with iAcommsDriver, you should not encounter any issues using the simulator.  However many fields, particularly in the receive statistics, are either not populated or populated with dummy (and potentially incorrect) values by the simulator.  

  • No labels