Skip to main content

Client Requests

Connected Systems API​

OSHConnect-JS includes helper classes/methods to query resources from a Connected Systems API.

Each class used by the OSHConnect-JS interface for interacting with a Connected Systems API server stems from a ConnectedSystemsApi class.

This class acts as a tool for querying JSON resources from a Connected Systems API.

The following sections on this page will walk through examples of how to use each client request. I encourage you to read the linked documentation for each section to see available methods.

Configuration​

All classes derivative of ConnectedSystemsApi (all classes below) require configuration to be able to connect with the server hosting the Connected Systems API.

See API Reference

The classes require a networkProperties object with a few fields to configure:

  • endpointUrl - Endpoint of Connected Systems API server (e.g. localhost:8181/sensorhub/api)
  • tls - true or false (for HTTPs/HTTP)
  • connectorOpts - Authentication configuration
    • username
    • password
  • streamProtocol (Optional) - Default is 'ws', but 'mqtt' is also available
  • mqttOpts (Optional) - MQTT-specific configuration
    • prefix
    • endpointUrl

Example configuration:

const networkProperties = {
    endpointUrl: `localhost:8181/sensorhub/api`,
    tls: false,
    connectorOpts: {
        username: 'admin',
        password: 'admin',
    }
  };

Systems​

See API Reference

Retrieving systems from the API is as easy as creating a Systems object, making sure you have the proper configuration.

For the sake of simplicity, all the following examples will use the networkProperties object defined above.

import Systems from 'osh-js/source/core/consysapi/system/Systems';
const systems = new Systems(networkProperties);

Retrieving all systems:

// Get paginated collection of systems
const systemsCollection = await systems.searchSystems(/*System Filter*/undefined, /*page size*/100);
// Get first page (list) of systems
const firstSystems = await systemsCollection.nextPage();
// Or get all pages
let allSystems = [];
while (systemsCollection.hasNext()) {
    const currSystems = await systemsCollection.nextPage();
    allSystems.push(currSystems);
}

Retrieving a system by its id:

const system522 = systems.getSystemById("sys522");

SystemFilter​

See API Reference Filter objects are used to return a filtered list of the queried resource.

All filters should correspond with the query parameters defined in the OGC API - Connected Systems specification, which can be found here

Using SystemFilter to search for systems:

// Get systems with matching id and use text query parameter
systems.searchSystems(new SystemFilter({ 
  id: "sys522",
  q: "weather"
}), 100);

System​

See API Reference

System objects should be retrieved from another OSHConnect-JS client request.

Example of some queries from a system:

// System retrieved from previous example
const system = firstSystems[0];
// Each of these yields collections of the corresponding type
system.searchSubSystems(); // /api/system/{sysId}/subsystems
system.searchDataStreams(); // /api/systems/{sysId}/datastreams
system.searchSamplingFeatures(); // /api/systems/{sysId}/samplingFeatures
system.searchControlStreams(); // /api/systems/{sysId}/controlstreams
info

All single resources (System, DataStream, Observation, etc.) will include all response fields according to OGC API - Connected Systems specification. These are directly accessible like so: system.id, datastream.outputName, etc.

DataStreams​

See API Reference

Querying from all DataStreams on server:

const datastreams = new DataStreams(networkProperties);
datastreams.searchDataStreams(/*DataStreamFilter, pageSize*/);
datastreams.getDataStreamById("someDsId123");

DataStreamFilter​

See API Reference

DataStream​

See API Reference

Querying a DataStream's Observations and schema:

// Observations
datastream.searchObservations(/*ObservationFilter, pageSize*/);
// DataStream schema
datastream.getSchema();

DataStream objects can also be used to directly listen for new Observations:

datastream.streamObservations(/*ObservationFilter*/undefined, (datablock) => {
    console.log("Data received! ", datablock);
})

DataStream to Data Source​

DataStreams can also be indirectly converted into ConSysApi data source objects:

const datasource = new ConSysApi(datastream.properties.name, {
    protocol: datastream.networkProperties.streamProtocol,
    endpointUrl: datastream.networkProperties.endpointUrl,
    resource: `/datastreams/${datastream.properties.id}/observations`,
    mode: Mode.REAL_TIME,
    tls: false,
    responseFormat: 'application/swe+json',
    connectorOpts: datastream.networkProperties.connectorOpts
});

Observations​

See API Reference

Querying from all observations on server:

const observations = new Observations(networkProperties);
observations.searchObservations(/*ObservationFilter, pageSize*/);

ObservationFilter​

See API Reference

Observation​

See API Reference

Observation objects are JSON objects described by the OGC API - Connected Systems specification.

console.log(observation.result);
console.log(observation.resultTime);
console.log(observation.id);

SamplingFeatures​

See API Reference

Querying from all SamplingFeatures on server:

const features = new SamplingFeatures(networkProperties);
features.searchSamplingFeatures(/*SamplingFeatureFilter, pageSize*/);
features.getSamplingFeatureById("someFeatureId123");

SamplingFeatureFilter​

See API Reference

SamplingFeature​

See API Reference

SamplingFeature objects are JSON objects described by the OGC API - Connected Systems specification.

console.log(feature.type);
console.log(feature.properties);
console.log(feature.geometry);

ControlStreams​

See API Reference

Querying from all ControlStreams on server:

const controlstreams = new ControlStreams(networkProperties);
controlstreams.searchControlStreams(/*ControlStreamFilter, pageSize*/)
controlstreams.getControlStreamById("someControlStreamId123");

ControlStreamFilter​

See API Reference

ControlStream​

See API Reference

ControlStream objects can be used to search for commands, stream commands, and even send commands.

// Querying commands on a control stream
controlstream.searchCommands(/*CommandFilter, pageSize*/);
// Streaming commands
controlstream.streamCommands(/*CommandFilter*/undefined, (commandData) => {
    console.info("Command has been received! ", commandData);
});
// Posting command to control stream
controlstream.postCommand({
  parameters: {
    pan: 10,
    tilt: 5,
    zoom: 1
  }
});

Commands​

See API Reference

Querying from all commands on server:

const commands = new Commands(networkProperties);
commands.searchCommands(/*CommandFilter, pageSize*/);

CommandFilter​

See API Reference

Command​

See API Reference

Command objects can be used to retrieve associated status reports of that command.

command.searchStatus(/*CommandFilter, pageSize*/);
command.streamStatus(/*CommandFilter*/undefined, (status) => {
   console.info("New command status report received! ", status); 
});