Skip to end of metadata
Go to start of metadata
This page describes the interface that enables CI to interact with the RSN OMS system. The focus of the interface is to support Platform Agent and Platform Driver functionality, but other CI components may also make use of it. A simulator supporting this interface has been developed by CI in this module.

Interface Overview for "CI-OMS Interface"

See the System Interfaces overview page for a list of all internal and external system interfaces.

Subsystem MI
Giver RSN Observatory Management System
Receiver MI Platform Drivers representing RSN infrastructure elements
Release Introduced R2
Status candidate
Document Number None
Interface Description How to connect to the RSN OMS and which operations are available.
Dependencies  
Technical Notes  
Source Code https://github.com/ooici/coi-services/tree/master/ion/agents/platform

Interface Specification

Operation status notation

Signature stable
Signature not fully specified
Obsolete operation – proposed to be deprecated/removed [4, 5]



Operations

Misc

ping()

Basic verification of connection with RSN OMS.

retval "PONG"

Platforms

get_platform_metadata(platform_id)

Returns the metadata for a requested platform.

platform_id   ID of desired platform
retval { platform_id: {mdAttrName: mdAttrValue, ...}, ... } dict with a single entry for the requested platform ID with a dictionary for corresponding metadata.
  {platform_id: 'ERROR_INVALID_PLATFORM_ID'} requested platform_id is invalid.

Possible platform metadata may include:

platform_types [platform_type, ...] list of types of the corresponding platform
description description some human-readable description of the platform
lat value latitude of the deployed platform
lon value longitude of the deployed platform
height value height of the deployed platform
depth value depth of the deployed platform
model_number value platform model number
serial_number value platform serial number

Platform attribute values

 get_platform_attribute_values(platform_id, attrs)

Returns the values for specific attributes associated with a given platform since a given time for each attribute.

platform_id   Platform ID
attrs [(attr_id, from_time), ...] Names of desired attributes and corresponding time (NTP v4 float value) after which attribute values are requested.
retval {platform_id: {attr_id : [(attrValue, timestamp), ...], ...}} dict with a single entry for the requested platform ID and value as a list of (value, timestamp) pairs for each attribute. Returned timestamps are NTP v4 float values.
  {platform_id: 'ERROR_INVALID_PLATFORM_ID'} requested platform_id is invalid.
  {platform_id: {attr_id: 'ERROR_INVALID_ATTRIBUTE_ID'}} requested attr_id is invalid.
  • If there are no values having a timestamp strictly greater than the indicated from_time for an attribute attr_id, then the entry from the attribute will be an empty array: attr_id: [].

Platform ports

get_platform_ports(platform_id)

Returns information for each port in a given platform.

platform_id   Platform ID
retval {platform_id: {port_id: portInfo, ...} } Dict with information for each port in the platform. Each key in this dict is the ID of the port, while the corresponding value is a dict {'state': state }, where state is either "OFF" or "ON" indicting whether the port is currently turned off or on.
  {platform_id: 'ERROR_INVALID_PLATFORM_ID'} requested platform_id is invalid.

turn_on_platform_port(platform_id, port_id , src)

Turns on a port in a platform.

platform_id   Platform ID
port_id   Port ID
src
String - Source of Command - i.e. Actor (MissionEx,UserName)
 
retval {platform_id: {port_id: 'OK_PORT_TURNED_ON'} } Confirmation
  {platform_id: {port_id: 'OK_PORT_ALREADY_ON'} } Port was already on
  {platform_id: 'ERROR_INVALID_PLATFORM_ID'} If the requested platform_id is invalid
  {platform_id: {port_id: 'ERROR_INVALID_PORT_ID'}} If the requested port_id is invalid

turn_off_platform_port(platform_id, port_id,src)

Turns off a port in a platform.

platform_id   Platform ID
port_id   Port ID
src
String - Source of Command - i.e. Actor (MissionEx,UserName)  
retval {platform_id: {port_id: 'OK_PORT_TURNED_OFF'} } Confirmation
  {platform_id: {port_id: 'OK_PORT_ALREADY_OFF'} } Port was already off
  {platform_id: 'ERROR_INVALID_PLATFORM_ID'} If the requested platform_id is invalid
  {platform_id: {port_id: 'ERROR_INVALID_PORT_ID'}} If the requested port_id is invalid

set_over_current(platform_id, port_id , ma, us, src)

...

platform_id   Platform ID
port_id   Port ID
ma    
us    
src    
retval {platform_id: {port_id: 'OK'} } Confirmation
  {platform_id: 'ERROR_INVALID_PLATFORM_ID'} If the requested platform_id is invalid
  {platform_id: {port_id: 'ERROR_INVALID_PORT_ID'}} If the requested port_id is invalid

Events

Event Instance

An event occurrence may contain the following elements:

field required description example
message human-readable message <VAR UPS> on battery power
platform_id platform ID where the event occurred 'Node2B'
event_id ID used from Platform to Mission Execution ("None")
'profiler_at _20m'
timestamp time of occurrence  
first_time_timestamp time of first occurrence  
severity level of severity 3
group   string for categorization power
test_event   Only to be included for event generated upon a generate_test_event request true

Event Notification

RSN OMS will notify all registered event listeners as events are occurring in the system. The notification consists of making an HTTP POST request to the associated URL of each registered listener with a payload describing the event or events in JSON format. This will be an array of objects, with each object reflecting and instance of the record described above. Example:

The listener server on the CI side will respond with a '202 Accepted' status indicating acknowledgment of the event notification.

register_event_listener(url)

Registers an event listener.

url http://listener.example.org/abc/def URL to be called
retval { url: reg_time } Dict with a single entry for the given URL with a timestamp confirming the time of registration
  • If the requested url is invalid (malformed or some other reason), then the returned entry in the dict will be url: 'ERROR_INVALID_EVENT_LISTENER_URL'.

Section "Event Notification' explains how RSN OMS makes the notification of events.

unregister_event_listener(url)

Un-registers the listener corresponding to a given URL.

url   URL of the listener
retval { url: unreg_time } Dict with a single entry for the given URL with the time of un-registration
  • If the URL is not registered, then the reported time will be 0 (zero).

get_registered_event_listeners()

Returns the currently registered event listeners.

retval { url: reg_time, ...], ... } Dict of event listeners indicating for each URL the associated time of latest registration

generate_test_event(event)

Used for testing and diagnostics purposes this operation instructs OMS to generate a simulated event with the given information. The event should be notified within a few seconds. See the Event Instance section.

event   A dictionary with event information. See Event Instance section
retval True Request acknowledged, event will be notified
  False Request acknowledged but no event will be notified because there are currently no registered listeners
  err Error message indicating any missing element in the requested event, etc.

The notified event instance will include a test_event attribute with value true indicating that the event is a "test" event as requested.

For example, if the requested event dictionary in this call is:

Then the JSON contents of the notified event should look something like:

References

[1] https://alfresco.oceanobservatories.org/alfresco/webdav/OOI/CONTROLLED/1131-00001_OMS_CI_Interface_White_Paper.doc (note: this is not the latest version)

[2] https://alfresco.oceanobservatories.org/alfresco/webdav/OOI/CONTROLLED/1131-00002_OMS_CI_ICD_Data_Command_Dictionary_RSN.xls

[3] https://alfresco.oceanobservatories.org/alfresco/webdav/OOI/CONTROLLED/4870-64460_OMS_CI_XMLRPC_Prototype_RSN.pdf

[4] Platform_Agent_DriverWhitepaper_2014-03-26_ver_1-03.docx (Mike Harrington, via email)

[5] https://confluence.oceanobservatories.org/display/RSNEng/Change+Requests+to+Platform+Agent

Labels

interfacespec interfacespec Delete
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.