The REDHAWK rest-python Server

And now for something long overdue...

2016-01-21T00:00:00+00:00

Welcome to the long-overdue API documentation for Geon’s modified version of rest-python! It’s a distant fork of the excellent version backing the admin-console UI released last year, adding several features we’ve found useful including Frontend Interfaces and event channels.

Subscribe to the posts feed or the repository to keep informed of changes to the API. Shortly, we will also be posting a user’s guide for our Angular.JS -based UI framework that is also loosely-based on an early version of admin-console.

Monitoring the Addition and Removal of Domains

2016-01-01T00:00:00+00:00

{
    "domains": [ /* List of Domain Names */ ],
    "added":   [ /* Those Added */ ],
    "removed": [ /* Those Removed */]
}

This stream continually polls at roughly once per second on the server side so that multiple clients remain synchronized without bombarding the server with HTTP GET requests. So rather than having to poll /redhawk/rest/domains to keep track of changes manually, this socket will instead push not only the list of known Domains but also added and removed lists for simple top-level management of which REDHAWK Domains are presently online.

Get NavData

2016-01-01T00:00:00+00:00

Required Properties:

idl.namespace == "FRONTEND"
idl.type == "NavData"
direction == "Provides"
name begins "NavData"

{
    "name": "NavData", 
    "idl": {
        "namespace":    "FRONTEND", 
        "version":      ":1.0", 
        "type":         "NavData"
    }, 
    "direction": "Provides", 
    "repId": "IDL:FRONTEND/NavData:1.0", 

    "nav_packet": {
        "position": {
            "valid":    true, 
            "datum":    "DATUM_WGS84", 
            "lat":      1.968344489698476e-316, 
            "alt":      0.0, 
            "lon":      6.9223758306637051e-310
        }, 
        "cposition": {
            "valid":    true,
            "datum":    "DATUM_WGS84",
            "lat":      1.968344489698476e-316, 
            "alt":      0.0, 
            "lon":      6.9223758306637051e-310
        },
        "velocity": {
            "valid":                true,
            "datum":                "DATUM_WGS84",
            "coordinate_system":    "CS_ECF",    /** Values: CS_ECF, CS_ENU, CS_NED **/
            "x":                    0.0,
            "y":                    0.0,
            "z":                    0.0
        },
        "acceleration": {
            "valid":                true,
            "datum":                "DATUM_WGS84",
            "coordinate_system":    "CS_ECF",    /** Values: CS_ECF, CS_ENU, CS_NED **/
            "x":                    0.0,
            "y":                    0.0,
            "z":                    0.0
        },
        "attitude": {
            "valid":    true,
            "pitch":    0.0,
            "yaw":      0.0,
            "roll":     0.0
        }
        "timestamp": {
            "tcmode":   -6960, 
            "tfsec":    9.6441614068211325e-321, 
            "toff":     2.1219957904712067e-314, 
            "tcstatus": 607, 
            "twsec":    5.7311614917584599e-322
        }, 
        "additional_info":  [
            /* Properties list */
        ],
    }
}

Get GPS Data

2016-01-01T00:00:00+00:00

Required Properties:

idl.namespace == "FRONTEND"
idl.type == "GPS"
direction == "Provides"
name begins "GPS"

{
    "name": "GPS", 
    "idl": {
        "namespace":    "FRONTEND", 
        "version":      ":1.0", 
        "type":         "GPS"
    }, 
    "direction": "Provides", 
    "repId": "IDL:FRONTEND/GPS:1.0", 

    "gps_info": {
        "freq_offset":  1.9684361882823442e-316, 
        "timestamp": {
            "tcmode":   -6960, 
            "tfsec":    9.6441614068211325e-321, 
            "toff":     2.1219957904712067e-314, 
            "tcstatus": 607, 
            "twsec":    5.7311614917584599e-322
        }, 
        "tfom":             39841168, 
        "freq_variance":    0.0, 
        "rf_flow_id":       "", 
        "snr":              0.0, 
        "mode":             "", 
        "time_variance":    6.9223758361948688e-310, 
        "fom":              39839632, 
        "source_id":        "", 
        "satellite_count":  49, 
        "time_offset":      1.9683401419207926e-316, 
        "status_message":   "", 
        "additional_info":  [], 
        "datumID":          39841280
    }, 
    "gps_time_pos": {
        "position": {
            "lat":      1.968344489698476e-316, 
            "datum":    "", 
            "alt":      0.0, 
            "valid":    true, 
            "lon":      6.9223758306637051e-310
        }, 
        "timestamp": {
            "tcmode":   449, 
            "tfsec":    2.1219957904712067e-314, 
            "toff":     1.9683393514157593e-316, 
            "tcstatus": 0, 
            "twsec":    1.2858049178971268e-312
        }
    }
}

Get Frontend RFSource

2016-01-01T00:00:00+00:00

Required Properties:

idl.namespace == "FRONTEND"
idl.type == "RFSource"
direction == "Provides"
name begins "RFSource"

{
    "type":         "RFSource", 
    "name":         "RFSource_in", 
    "idl": {
        "namespace":    "FRONTEND", 
        "version":      ":1.0", 
        "type":         "RFSource"
    }, 
    "direction": "Provides", 
    "repId": "IDL:FRONTEND/RFSource:1.0", 
    
    "available_rf_inputs":  [
        /* List of RFInfoPkt structures */
    ],
    "current_rf_input": {
        /* RFInfoPkt Structure */
    }
}

The RFInfoPkt structure is as follows:

{
    "spectrum_inverted":    false, 
    "rf_center_freq":       50000000000.0, 
    "if_center_freq":       0.0, 
    "capabilities": {
        "bw_range":     { "max_val": 0.0, "values": [], "min_val": 0.0 }, 
        "freq_range":   { "max_val": 0.0, "values": [], "min_val": 0.0 }
    }, 
    "ext_path_delays":  [], 
    "rf_bandwidth":     100000000000.0, 
    "rf_flow_id":       "FLOW_ID_NOT_SET", 
    "sensor": {
        "feed": {
            "polarization": "", 
            "name":         "", 
            "freq_range": {
                "max_val":  0.0, 
                "values":   [], 
                "min_val":  0.0
            }
        }, 
        "collector":    "", 
        "rx":           "", 
        "mission":      "", 
        "antenna": {
            "size":         "", 
            "type":         "", 
            "description":  "", 
            "name":         ""
        }
    },
    "additional_info":  []
}

Get Frontend RFInfo

2016-01-01T00:00:00+00:00

Required Properties:

idl.namespace == "FRONTEND"
idl.type == "RFInfo"
direction == "Provides"
name begins "RFInfo"

{
    "type":         "RFInfo", 
    "name":         "RFInfo_in", 
    "idl": {
        "namespace":    "FRONTEND", 
        "version":      ":1.0", 
        "type":         "RFInfo"
    }, 
    "direction": "Provides", 
    "repId": "IDL:FRONTEND/RFInfo:1.0", 

    "rf_flow_id":   "FLOW_ID_NOT_SET", 
    "rfinfo_pkt": {
        "spectrum_inverted":    false, 
        "rf_center_freq":       50000000000.0, 
        "if_center_freq":       0.0, 
        "capabilities": {
            "bw_range":     { "max_val": 0.0, "values": [], "min_val": 0.0 }, 
            "freq_range":   { "max_val": 0.0, "values": [], "min_val": 0.0 }
        }, 
        "ext_path_delays":  [], 
        "rf_bandwidth":     100000000000.0, 
        "rf_flow_id":       "FLOW_ID_NOT_SET", 
        "sensor": {
            "feed": {
                "polarization": "", 
                "name":         "", 
                "freq_range": {
                    "max_val":  0.0, 
                    "values":   [], 
                    "min_val":  0.0
                }
            }, 
            "collector":    "", 
            "rx":           "", 
            "mission":      "", 
            "antenna": {
                "size":         "", 
                "type":         "", 
                "description":  "", 
                "name":         ""
            }
        },
        "additional_info":  [
            /* Properties list */
        ]
    }
}

Set (Tune) a Frontend Allocation

2016-01-01T00:00:00+00:00

Required Properties:

idl.namespace == "FRONTEND"
idl.type == any("DigitalTuner", "AnalogTuner")
direction == "Provides"
"Tuner" in name

By providing the allocation ID, one can PUT tuner properties directly to the port to use the IDL-defined methods (similar to calling configure, etc.). The structure of properties to use is as follows:

{
    "properties": [
        /* Analog or Digital */
        { "id": "tuner_agc_enable",         "value": true }, 
        { "id": "tuner_center_frequency",   "value": 0.0 },
        { "id": "tuner_reference_source",   "value": "source" }, 
        { "id": "tuner_bandwidth",          "value": 0.0 }, 
        { "id": "tuner_enable",             "value": true },
        { "id": "tuner_gain",               "value": 0.0 },

        /* Digital ONLY */
        { "id": "tuner_output_sample_rate", "value": 0.0 }
    ]
}

Get a Frontend Allocation

2016-01-01T00:00:00+00:00

Required Properties:

idl.namespace == "FRONTEND"
idl.type == any("DigitalTuner", "AnalogTuner")
direction == "Provides"
"Tuner" in name

{
    "direction": "Provides",
    "name": "DigitalTuner_in",
    "active_allocation_ids": [
        /* List of Allocation IDs (strings) */
    ],
    "idl": {
        "namespace": "FRONTEND",
        "version": ":1.0",
        "type": "DigitalTuner"
    },
    "allocations": [
        {
            "id":   "allocationId",
            "value": [
                { "id": "tuner_agc_enable",         "value": true }, 
                { "id": "tuner_control",            "value": "RX_DIGITIZER" }, 
                { "id": "tuner_reference_source",   "value": "NOT_SUPPORTED" }, 
                { "id": "tuner_bandwidth",          "value": 2000000.0 }, 
                { "id": "tuner_output_sample_rate", "value": 2000000.0 }, 
                { "id": "tuner_rf_flow_id",         "value": "RTL_FLOW_ID_NOT_SET" }, 
                { "id": "tuner_enable",             "value": true }, 
                { "id": "tuner_device_control",     "value": true }, 
                { "id": "tuner_gain",               "value": 0.0 }, 
                { "id": "tuner_group_id",           "value": "" }, 
                { "id": "tuner_center_frequency",   "value": 89500000.0 },
                { "id": "tuner_status",             "value" : [ 
                        /* FRONTEND::tuner_status* properties list */ 
                    ],
            ]   
        }
    ],
    "repId": "IDL:FRONTEND/DigitalTuner:1.0",
    "tuner_statuses": [
        /* Lists of FRONTEND::tuner_status::* properties for each tuner */
    ]
}

The tuner statuses list is in essence the FRONTEND::tuner_status::* property list, as defined by the IDL. It is not reproduced here.

Frontend Tuners

2016-01-01T00:00:00+00:00

Required Properties:

idl.namespace == "FRONTEND"
idl.type == any("DigitalTuner", "AnalogTuner")
direction == "Provides"
"Tuner" in name

{
    "direction": "Provides",
    "name": "DigitalTuner_in",
    "active_allocation_ids": [
        /* List of Allocation IDs (strings) */
    ],
    "idl": {
        "namespace": "FRONTEND",
        "version": ":1.0",
        "type": "DigitalTuner"
    },
    "allocations": [
        /* Empty unless an allocation ID is provided */
    ],
    "repId": "IDL:FRONTEND/DigitalTuner:1.0",
    "tuner_statuses": [
        /* Lists of FRONTEND::tuner_status::* properties for each tuner */
    ]
}

The tuner statuses list is in essence the FRONTEND::tuner_status::* property list, as defined by the IDL. It is not reproduced here.

Streaming from BULKIO

2016-01-01T00:00:00+00:00

Required Properties:

idl.namespace == "BULKIO"
idl.type == any("dataFloat", "dataDouble", "dataOctet", "dataShort")
direction == "Uses"

This socket provides both JSON and binary data. The JSON data is a representation of the SRI:

{
    "hversion": "hversion",
    "xstart":   0,
    "xdelta":   1.0,
    "xunits":   5,
    "subsize":  0,
    "ystart":   0,
    "ydelta":   1.0,
    "yunits":   "yunits",
    "mode":     "mode",
    "streamID": "streamID",
    "blocking": "blocking",
    "keywords": {
        "keywordID1": "keywordValue1",
        "keywordID2": "keywordValue2"
    }
}

The binary data is a vector of the appropriate type of information.

NOTE: Those familiar with REDHAWK can see there is no stream ID to marry the SRI with the binary stream. At this time multiple streams on a socket will be interleaved in such a way that re-joining the SRI with the data may be impossible. This will be resolved in a future release when this interface transmits only binary as a Google Protobuf structure.

Inspecting a Port's Properties

2016-01-01T00:00:00+00:00

{
    "name":     "portName",
    "repId":    "IDL:<namespace>/<type>:<version>",
    "direction": "Uses", /* or Provides */
    "idl": {
        "namespace":    "BULKIO", /* or FRONTEND */
        "version":      ":<version>",
        "type":         "<type>"
    }
}

Every port supports this interface, at a minimum. Many of these fields can be used by the client to determine what additional features are exposed.

Sending Messages

2016-01-01T00:00:00+00:00

That would be really awesome. Thank you for volunteering to add that feature. :-)

At this time we do not have a way to inject Messages back into an event channel. If you would like to write the handlers for this, please do so and submit a pull request. Otherwise, just know it’s on our To Do list.

Handling Messages and propEvent Ports

2016-01-01T00:00:00+00:00

At present the best way to get Messages and property change events out of rest-python is to attach the associated port (in REDHAWK) to a named event channel. Then subscribe to that channel name as your topic to read those messages and property events as they happen.

Messages

{
    "id":     "propertyId",
    "value":  [ 
        /* List of id-value pairs */
        { "id": "propertyId::field1", "value": 42 }
    ]
}

Messages are encapsulated as they appear on the event channel which is similar to struct Properties. The notable difference is the lack metadata (type, scaType, etc.).

propEvent

{
    "sourceId":     "entityId",
    "sourceName":   "entityName",
    "properties": [
        /* List of Message-like objects */
    ]
}

The properties is a list of objects formatted like Messages, above, meaning each lacks any metadata usually associated with Properties.

Handling ODM and IDM Events

2016-01-01T00:00:00+00:00

These structures are exclusively defined as one would find on the ODM and IDM channels in a REDHAWK system since those structures are simply converted into dictionaries and lists, as appropriate, but using JSON for syntax.

NOTE: The provided enumeration value for the affected fields was arbitrarily chosen as the index within the defining list so that the structure provided here is similar to Properties.

ODM Events

{
    "producerId":       "DCE:9ae444e0-0bfd-4e3d-b16c-1cffb3dc0f46",
    "sourceId":         "DCE:820e3275-4462-4823-b754-e09b4712869e", 

    "sourceName":       "FEIDevice_1", 
    "sourceCategory":   { 
        /* See enumerations */ 
        "value":        "DEVICE"
        "enumerations": {
            "DEVICE_MANAGER"        : 0, 
            "DEVICE"                : 1,
            "APPLICATION_FACTORY"   : 2,
            "APPLICATION"           : 3,
            "SERVICE"               : 4
        }
    },
    "sourceIOR":        "" /* OPTIONAL */
}

The sourceIOR and other object reference types are stripped since they’re of little use on the other side of the socket. Instead you will see the key name, like sourceIOR, but the value will be a string indicating it does not represent what the real value was in any way. NOTE: The presence of the sourceIOR key indicates the entity was added to the Domain.

IDM Events

{
    "producerId":       "DCE:9ae444e0-0bfd-4e3d-b16c-1cffb3dc0f46",
    "sourceId":         "DCE:820e3275-4462-4823-b754-e09b4712869e", 

    "stateChangeCategory": {
        /* See enumerations */
        "value":        "ADMINISTRATIVE_STATE_EVENT",
        "enumerations": {
            "ADMINISTRATIVE_STATE_EVENT"    : 0,
            "OPERATIONAL_STATE_EVENT"       : 1,
            "USAGE_STATE_EVENT"             : 2
        }
    },
    "stateChangeFrom": {
        /* See enumerations */
        "value":        "LOCKED",
        "enumerations": {
            "LOCKED"        : 0,
            "UNLOCKED"      : 1,
            "SHUTTING_DOWN" : 2,
            "ENABLED"       : 3,
            "DISABLED"      : 4,
            "IDLE"          : 5,
            "ACTIVE"        : 6,
            "BUSY"          : 7
        }
    },
    "stateChangeTo" : {
        /* Identical behavior to stateChangeFrom */
    }
}

Subscribe to an Event Channel

2016-01-01T00:00:00+00:00

{ 
    "command"  : "ADD",         /* Or "REMOVE" */
    "domainId" : "DOMAIN_NAME", /* Domain Name */
    "topic":     "ODM_Channel"  /* Channel Name */
}

SUBSCRIBE to specific event channels using the channel name, called a topic in websocket parlance, and the Domain ID (name) by writing the above JSON structure to the socket.

UNSUBSCRIBE from a specific event channel by changing the command to REMOVE and specifying the topic.

Inspecting a Domain

2016-01-01T00:00:00+00:00

{
    "name": "REDHAWK_DEV", 
    "id": "DCE:9ae444e0-0bfd-4e3d-b16c-1cffb3dc0f46", 
    "properties": [
        {
            "scaType": "simple", 
            "id": "COMPONENT_BINDING_TIMEOUT",
            "value": 60
        }, 
        {
            "scaType": "simple", 
            "id": "LOGGING_CONFIG_URI", 
            "value": ""
        }, 
        {
            "scaType": "simple", 
            "id": "REDHAWK_VERSION", 
            "value": "1.10.1"
        } 
    ], 
    "applications": [
        { 
            "name": "applicationName",
            "id":   "applicationId"
        }
    ], 
    "deviceManagers": [
        {   
            "name": "nodeName", 
            "id": "nodeId"
        }
    ], 
    "eventChannels": [
        /* List of event channel names as strings */
    ]
}

The applications field lists all running Waveforms. Likewise deviceManagers lists the known Device Managers in the system. Both of these lists can be indexed further using the id field of interest.

The eventChannels field provides a list of any event channels to which one has subscribed using the /redhawk/rest/events websocket interface (Event Channels). This list cannot be indexed.

Getting a list of Domains

2016-01-01T00:00:00+00:00

{
    "domains": [ /* List of Domain Names */ ],
}

Active domains are listed by their unique names in the domains field, the values of which can be used to further index URL.

NOTE: Rather than poll this property, consider using the REDHAWK Websocket.

Inspecting a Device Manager

2016-01-01T00:00:00+00:00

{
    "name":     "TestNode", 
    "id":       "DCE:d0645c12-7962-414f-9969-2372635b1170"
    "properties": [ 
        {
            "scaType":  "simple", 
            "id":       "HOSTNAME", 
            "value":    "localhost.localdomain"
        }, 
        {
            "scaType":  "simple", 
            "id":       "LOGGING_CONFIG_URI", 
            "value":    ""
        }
    ], 
    "devices": [ 
        /* List of name-id objects of Devices */
        { 
            "id":   "deviceId", 
            "name": "deviceName" 
        }
    ],
    "services": [ 
        /* List of name-id objects for services */
        { 
            "id": "serviceId", 
            "name": "serviceName" 
        }
    ]
}

The devices list can be indexed further by using the id field of interest (see Devices).

At this time, services are supported in name-only since it’s not possible to represent such a nebulous entity in a useful way through this interface.

Listing Device Managers

2016-01-01T00:00:00+00:00

{
    "deviceManagers": [
        {   
            "name": "nodeName", 
            "id":   "nodeID"
        }
    ], 
}

This deviceManagers URL can be indexed using the id field of interest.

Listing Device Ports

2016-01-01T00:00:00+00:00

{
    "ports": [
        /* List of port structures */
    ]
}

The general format for ports is shown here:

{
    "name":     "portName",
    "repId":    "IDL:<namespace>/<type>:<version>",
    "direction": "Uses", /* or Provides */
    "idl": {
        "namespace":    "BULKIO", /* or FRONTEND */
        "version":      ":<version>",
        "type":         "<type>"
    }
}

The list can be indexed using the name field. See Ports for more information.