Querying an OBC for Telemetry Data¶
At some point, users will want to fetch data which was written to the telemetry database (for an example of this, see the mission application tutorial).
This tutorial will walk the user through the process of communicating with the telemetry database service in order to retrieve a desired set of telemetry information.
Pre-Requisites¶
Have an OBC available with ethernet capabilities (preferably with an installation of Kubos Linux)
Have the telemetry database service running on a target OBC (this happens by default when running KubOS)
Setup¶
In order to have something to query, we’ll need to seed the database.
Note
For all commands, replace the 10.0.2.20
value with the IP address of your OBC.
The example commands will also be referencing the telemetry database service’s default port, 8006
From your instance of the SDK, run the following:
$ echo "mutation {insert(subsystem:\"eps\",parameter:\"voltage\",value:\"5.0\"){success}}" | nc -uw1 10.0.2.20 8006
$ echo "mutation {insert(subsystem:\"eps\",parameter:\"voltage\",value:\"5.0\"){success}}" | nc -uw1 10.0.2.20 8006
$ echo "mutation {insert(subsystem:\"eps\",parameter:\"current\",value:\"0.1\"){success}}" | nc -uw1 10.0.2.20 8006
$ echo "mutation {insert(subsystem:\"eps\",parameter:\"current\",value:\"0.1\"){success}}" | nc -uw1 10.0.2.20 8006
$ echo "mutation {insert(subsystem:\"gps\",parameter:\"voltage\",value:\"3.3\"){success}}" | nc -uw1 10.0.2.20 8006
Each of these commands should return the following:
{"errs":"","msg":{"insert":{"success":true}}}
Schema¶
The telemetry
query can be used to fetch a certain selection of data from the telemetry database.
It will return an array of database entries.
The query has the following schema:
query {
telemetry(timestampGe: Integer, timestampLe: Integer, subsystem: String, parameter: String, limit: Integer): [{
timestamp: Integer!
subsystem: String!
parameter: String!
value: String!
}]
}
Each of the input arguments acts as a filter for the database query:
- timestampGe - Return entries with timestamps occurring on or after the given value
- timestampLe - Return entries with timestamps occurring on or before the given value
- subsystem - Return entries which match the given subsystem name
- parameter - Return entries which match the given parameter name
- limit - Return only the first n entries found
Using the telemetry
query without specifying any of the input arguments will result in all
entries in the telemetry database being returned.
The query returns an array of entries, each of which has the following response fields:
- timestamp - The system time when the entry was recorded, in milliseconds since UNIX epoch
- subsystem - The subsystem which generated the entry data
- parameter - The specific data point the entry corresponds to
- value - The value of the data point
Querying a Specific Subsystem¶
In order to return only telemetry generated by a specific subsystem, we’ll send a query using the
subsystem
input parameter.
For example, to get only telemetry from our (fake) EPS subsystem, we’ll send the following:
$ echo "{telemetry(subsystem:\"eps\"){timestamp,subsystem,parameter,value}}" | nc -uw1 10.0.2.20 8006
Adding a little bit of formatting, the request should return something like this:
{
"errs": "",
"msg": {
"telemetry": [
{
"parameter": "current",
"subsystem": "eps",
"timestamp": 77853891,
"value": "0.1"
},
{
"parameter": "current",
"subsystem": "eps",
"timestamp": 77852840,
"value": "0.1"
},
{
"parameter": "voltage",
"subsystem": "eps",
"timestamp": 77841215,
"value": "5.0"
},
{
"parameter": "voltage",
"subsystem": "eps",
"timestamp": 77833211,
"value": "5.0"
}
]}
}
Querying a Time Frame¶
If we want to fetch the telemetry from a particular time frame, for example all telemetry occurring
between 1pm and 2pm, we’ll use a combination of the timestampGe
and timestampLe
input
arguments.
Note
In order to select a timeframe, it is helpful to know the current system time.
This can be found by running the following command on the OBC: echo $(($(date +%s)*1000))
.
The command gets the current number of seconds since UNIX epoch and converts it to milliseconds
to match the telemetry timestamp units
Our request should look like this:
$ echo "{telemetry(timestampGe: 77830000, timestampLe: 77840000){timestamp,subsystem,parameter,value}}" | nc -uw1 10.0.2.20 8006
This queries the system for telemetry in a 10 second window between 77830000 and 77840000, inclusive. You will need to update the query for your specific timestamp range.
The response should look something like this:
{
"errs": "",
"msg": {
"telemetry": [
{
"parameter": "voltage",
"subsystem": "eps",
"timestamp": 77833211,
"value": "5.0"
}
]}
}
Limiting the Results¶
Let’s say we only want to know the most recent voltage reading from our EPS subsystem.
We’ll specify the subsystem
and parameter
input argument to narrow the filters down to the
subsystem and parameter we want.
We’ll then also use the limit
input argument to tell the telemetry database service to only
return the single most-recent entry.
Our request should look like this:
$ echo "{telemetry(subsystem:\"eps\", parameter:\"voltage\", limit: 1){timestamp,subsystem,parameter,value}}" | nc -uw1 10.0.2.20 8006
The response should look like this:
{
"errs": "",
"msg": {
"telemetry": [
{
"parameter": "voltage",
"subsystem": "eps",
"timestamp": 77841215,
"value": "5.0"
}
]}
}