Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
286 lines (253 sloc) 8.54 KB

Embedded Radio Tracker HTTP and WebSocket API endpoints

The HTTP and WebSocket API endpoints exposed by both ertgateway and ertnode allow a user interface or another application to monitor and download telemetry data messages and image files. ertgateway provides all of the endpoints listed below, so that it is possible to browse telemetry data messages of the node and the gateway separately, whereas ertnode exposes only the node-specific endpoints and allows access to transmitted data (because ertnode functions as a transmitter).

All data is returned in JSON format unless specified otherwise.

WebSocket connection

The WebSocket connection uses the same port as the HTTP endpoints. The server uses WebSocket protocol name ert-data-logger for providing real-time updates of received/generated telemetry messages and image files.

Each message is a JSON object that contains field type to identify the type of data in the object:

  • 0x01 = Node telemetry message

  • 0x02 = Gateway telemetry message

  • 0x41 = Node image file

HTTP endpoints

GET /api/data-logger/latest-entry/node:

Fetch the latest telemetry message received from (or transmitted by) node.

GET /api/data-logger/latest-entry/gateway:

Fetch the latest telemetry message generated by the gateway.

GET /api/data-logger/history/node?count={count}:

count is an optional parameter and defaults to 10.

Fetch count latest telemetry messages received from (or transmitted by) node.

GET /api/data-logger/history/gateway?count={count}:

count is an optional parameter and defaults to 10.

Fetch count latest telemetry messages generated by the gateway.

GET /api/image-history?count={count}:

count is an optional parameter and defaults to 10.

List file names of count latest images received from (or transmitted by) node in reversed alphabetical order.

Response example:

[
  "image-2017-06-08T06-09-05Z-00579-local.webp",
  "image-2017-06-08T06-07-57Z-00578-local.webp",
  "image-2017-06-08T06-07-10Z-00007.webp",
  "image-2017-06-08T06-06-47Z-00577-local.webp",
  "image-2017-06-08T06-06-36Z-00006.webp"
]

GET /api/image/{filename}:

Download an image with the given filename. Image file format depends on the file stored on the server (JPEG or WEBP).

GET|POST /api/config:

Fetch (GET) or change (POST) the application configuration. GET method returns the full configuration is JSON format. POST method can be used to alter runtime application configuration. The endpoint accepts partial configuration data, where only specific configuration entry values are changed.

The configuration data structure and the entry names are the same as in the YAML application configuration.

Response example:

{
  "global": {
    "device_name": "ertgateway1",
    "device_model": "Raspberry Pi with RFM96W LoRa shield",
    "thread_count_per_comm_handler": 4
  },
  "display_handler": {
    "display_update_interval_seconds": 1,
    "display_mode_cycle_length_in_update_intervals": 0
  },
  "image_handler": {
    "image_path": "./image",
    "image_format": "webp"
  },
  "telemetry_handler": {
    "gateway_telemetry_collect_interval_seconds": 5
  },
  "gps": {
    "gpsd": {
      "enabled": true,
      "host": "localhost",
      "port": 2947
    }
  },
  "server": {
    "enabled": true,
    "port": 9000,
    "buffer_length": 32768,
    "image_path": "./image",
    "static_path": "./static",
    "data_logger": {
      "path": "./log",
      "node_filename_template": "ertgateway-data-logger-node.%Y-%m-%d.log",
      "gateway_filename_template": "ertgateway-data-logger-gateway.%Y-%m-%d.log"
    }
  },
  "ui": {
    "st7036_enabled": true,
    "st7036": {
      "spi": {
        "bus_index": 1,
        "device_index": 0,
        "clock_speed": 1000000
      },
      "pins": {
        "reset": 25,
        "register_select": 2
      },
      "columns": 16,
      "rows": 3,
      "bias": "1/4",
      "power_boost": true,
      "follower_circuit": true,
      "follower_circuit_amplified_ratio": 3,
      "initial_contrast": 40
    },
    "dothat": {
      "backlight_enabled": true,
      "touch_enabled": true,
      "leds_enabled": true,
      "brightness": 60,
      "backlight_color": 65535,
      "backlight_error_color": 16776960
    }
  },
  "comm_transceiver": {
    "transmit_buffer_length_packets": 16,
    "receive_buffer_length_packets": 64,
    "transmit_timeout_milliseconds": 30000,
    "poll_interval_milliseconds": 1000,
    "maximum_receive_time_milliseconds": 0
  },
  "comm_protocol": {
    "passive_mode": false,
    "transmit_all_data": false,
    "ignore_errors": false,
    "receive_buffer_length_packets": 64,
    "stream_inactivity_timeout_millis": 20000,
    "stream_acknowledgement_interval_packet_count": 32,
    "stream_acknowledgement_receive_timeout_millis": 1000,
    "stream_acknowledgement_guard_interval_millis": 50,
    "stream_acknowledgement_max_rerequest_count": 5,
    "stream_end_of_stream_acknowledgement_max_rerequest_count": 2,
    "transmit_stream_count": 16,
    "receive_stream_count": 32
  },
  "comm_devices": {
    "rfm9xw": {
      "spi": {
        "bus_index": 0,
        "device_index": 1,
        "clock_speed": 500000
      },
      "pins": {
        "dio0": 27,
        "dio5": 26
      },
      "receive_single_after_detection": false,
      "transmit": {
        "pa_boost": true,
        "pa_output_power": 15,
        "pa_max_power": 7,
        "frequency": 434250000.0,
        "implicit_header_mode": false,
        "error_coding_rate": "4:5",
        "bandwidth": "62K5",
        "spreading_factor": 8,
        "crc": true,
        "low_data_rate_optimize": false,
        "expected_payload_length": 0,
        "preamble_length": 8,
        "iq_inverted": false,
        "receive_timeout_symbols": 0,
        "frequency_hop_enabled": false,
        "frequency_hop_period": 0
      },
      "receive": {
        "pa_boost": true,
        "pa_output_power": 15,
        "pa_max_power": 7,
        "frequency": 434250000.0,
        "implicit_header_mode": false,
        "error_coding_rate": "4:5",
        "bandwidth": "62K5",
        "spreading_factor": 8,
        "crc": true,
        "low_data_rate_optimize": false,
        "expected_payload_length": 0,
        "preamble_length": 8,
        "iq_inverted": false,
        "receive_timeout_symbols": 0,
        "frequency_hop_enabled": false,
        "frequency_hop_period": 0
      }
    }
  }
}

GET /api/comm-protocol/active-streams:

The active-streams endpoint provides a snapshot of currently active comm protocol streams. The snapshot contains details of the state and data transfer statistics.

This endpoint is basically only useful for debugging purposes.

Response example:

{
  "streams": [
    {
      "type": "RECEIVE",
      "stream_id": 14,
      "port": 1,
      "acks_enabled": true,
      "acks": false,
      "ack_request_pending": false,
      "start_of_stream": false,
      "end_of_stream_pending": false,
      "end_of_stream": false,
      "close_pending": false,
      "failed": false,
      "current_sequence_number": 1,
      "last_acknowledged_sequence_number": 1,
      "last_transferred_sequence_number": 1,
      "transferred_packet_count": 1.0,
      "transferred_data_bytes": 255.0,
      "transferred_payload_data_bytes": 251.0,
      "duplicate_transferred_packet_count": 0.0,
      "last_transferred_packet_timestamp": "2017-05-22T11:52:27.068Z",
      "ack_rerequest_count": 0,
      "end_of_stream_ack_rerequest_count": 0,
      "retransmitted_packet_count": 0.0,
      "retransmitted_data_bytes": 0.0,
      "retransmitted_payload_data_bytes": 0.0,
      "received_packet_sequence_number_error_count": 0.0
    },
    {
      "type": "RECEIVE",
      "stream_id": 13,
      "port": 11,
      "acks_enabled": true,
      "acks": false,
      "ack_request_pending": false,
      "start_of_stream": false,
      "end_of_stream_pending": false,
      "end_of_stream": false,
      "close_pending": false,
      "failed": false,
      "current_sequence_number": 6,
      "last_acknowledged_sequence_number": 6,
      "last_transferred_sequence_number": 6,
      "transferred_packet_count": 6.0,
      "transferred_data_bytes": 1530.0,
      "transferred_payload_data_bytes": 1506.0,
      "duplicate_transferred_packet_count": 0.0,
      "last_transferred_packet_timestamp": "2017-05-22T11:52:26.262Z",
      "ack_rerequest_count": 0,
      "end_of_stream_ack_rerequest_count": 0,
      "retransmitted_packet_count": 0.0,
      "retransmitted_data_bytes": 0.0,
      "retransmitted_payload_data_bytes": 0.0,
      "received_packet_sequence_number_error_count": 0.0
    }
  ]
}
You can’t perform that action at this time.