Commit 5eb2a95a authored by Pim Schellart's avatar Pim Schellart
Browse files

Update README to give basic background and example.

parent a11937f5
Pipeline #968 skipped
Radboud Radio Lab VLBI Monitor (Client)
=======================================
Client software for the Radboud Rado Lab VLBI Monitor.
Client software for the Radboud Radio Lab VLBI Monitor.
License
-------
......@@ -13,3 +13,163 @@ License
Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
General background
------------------
The number one design requirement of the Radboud Radio Lab VLBI Monitor is:
> It shall be as easy as possible for observatories to opt-in and send
> data to the server.
Therefore on the client (i.e. observatory) side:
- the system imposes an absolute minimum number of
requirements / dependencies;
- the interface is flexible, enabling scripts / programs
to be written in any programming language to be either completely
stand alone (e.g. a Python script grepping from a local log file)
or fully integrated (e.g. within a Java / C++ based telescope
control system);
- the system requires only a minimum number of security
privileges (i.e. no open ports and no super user access).
For this reason:
1. All communication with the server goes through simple HTTP requests.
2. Requests to the server are plain text, formatted according to the
JSON RPC 2.0 standard.
3. The standard Auth extension to the JSON RPC 2.0 standard is used
for user and session authentication.
4. Request payloads (e.g. metadata records) is in simple JSON format.
5. Metadata fields are combined into records. Individual records may be
incomplete, but are merged into the last record before being stored.
As such a complete overview of all metadata from a facility at a given
time is always available with a single read.
6. All metadata records are validated against a configurable JSON
schema, before insertion, to ensure conformity and configureability.
This brief description was adapted from the general VLBI monitor
[design document](https://gitlab.science.ru.nl/radiolab/vlbi_monitor/blob/master/DESIGN.md).
How the system works
--------------------
Clients (e.g. observatories) communicate with the server by sending JSON RPC 2.0 requests
over HTTP(S) POST. The most common request is an `updateRecords` request. This sends a
metadata record (a list of fields) to the server. Such a request looks like:
{
"jsonrpc":"2.0",
"id":0,
"auth":{
"username":"admin",
"password":"admin",
"facility":"SPT"
},
"method":"updateRecords",
"params":{
"records":[
{
"metadata":{
"observingMode":{
"value":"VLBI",
"time":"2016-01-23T11:34:44.623545Z"
},
"oscillatorFrequencyOffset":{
"value":0.35,
"time":"2016-01-23T11:34:44.623545Z",
"expires":"2016-02-23T12:00:00.0Z"
},
"maser":{
"value":false,
"time":"2016-01-23T11:34:44.623545Z"
},
"maser.chamberTemperature":{
"value":0.916,
"time":"2016-01-23T11:34:44.623545Z"
},
"maser.vacPumpCurrent":{
"value":0.75,
"time":"2016-01-23T11:34:44.623545Z"
}
}
}
]
}
}
Because this is simply a plain-text HTTP request it can be sent with any common tool or HTTP
library. On the UNIX command line one can for example send it with CURL:
```
$ curl -vX POST http://localhost:8000/rpc -d @request.json --header "Content-Type: application/json"
```
if the content is stored in a file `request.json`.
The VLBI monitor [client repository](https://gitlab.science.ru.nl/radiolab/vlbi_monitor_client)
contains example clients written in Python or C that can be easily adapted to integrate with
existing control software at the telescopes.
Adapting a client for your observatory
--------------------------------------
There are four steps to implement a client for your observatory:
1. Request a username / password for your observatory by sending an email to the
monitor administrator (you may modify the password later through an RPC request).
2. Decide upon the list of fields you are able to provide and, if necessary, request an update
to the JSON schema (the schema insures that all observatories send metadata in the same format).
3. Decide how best to gather the relevant metadata locally before sending. On some sites it may be
easiest to just write a little script that periodically parses a log file, on others you might
want to integrate it into your telescope control system.
4. Select an example client in your preferred language (the one that is easiest to integrate with
your local system) and adapt it (slightly) to send the metadata you want. Currently Python and
C example clients are available, but more may be written on request.
Example
-------
A basic example in Python using the provided `vlbi` module looks like:
```
import time
import datetime
import vlbi
url = "http://vlbi.astro.ru.nl:8000/rpc"
username = "foo"
password = "bar"
facility = "SMTO"
client = vlbi.Client(url, facility, username, password, backup=False)
now = datetime.datetime.utcnow()
s_now = now.isoformat('T') + 'Z'
later = now + datetime.timedelta(seconds=10)
s_later = later.isoformat('T') + 'Z'
metadata = {}
metadata["systemTemperature"] = {"time": s_now, "value": 352.234}
metadata["observingMode"] = {"time": s_now, "expires": s_later, "value": "VLBI"}
metadata["maser"] = {"time": s_now, "value": True}
metadata["maser.chamberTemperature"] = {"time": s_now, "value": 13.325}
record = {"observatory" : "SMTO", "time" : s_now, "metadata" : metadata}
client.updateRecord(record)
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment