The xVlepsis "base station" server

This is the man component "server" component installed in the home network of xVlepsis. It is responsible for receiving the sensor readings (e.g. temperature, breathing rate, etc), storing them locally, forwarding them to the central (cloud) xVlepsis server, and last but not least supporting the local (i.e. inside the house) client apps by sending the stream of "events". The events can be the sensor readings, critical events (e.g. clinical apnea), etc.

The current "sensors" are two: one for the temperature ("thermometer") and another for identifying the whether the baby is crying or not. Since we currently lack any such sensor, the values are fake and automatically generated.

The currently supported endpoints are:

• POST /prefs: Saving a user's preferences in JSON format. The server does not look what's inside the JSON message..

• GET /prefs: Retrieving a user's preferences in JSON format.

• GET /events : Retrieves a "stream" of "events" in a "server-sent events"-compliant way. Currently, the only event types supported are the "thermometer" and "crying". The events endpoint accepts the followong parameters:

  • a lastEventId parameter that specifies the Id of the last event received in client in order to start sending events from this timestamp on. Since server-sent events support automatic reconnection, the browser could also make additional requests by sending the Last-Event-ID header. By default, if no lastEventIdwas provided, the server will retrieve and return all the events of the last hour.

  • sensor : either "thermometer" or "crying" in order to retrieve events only for the given "sensor". If this parameter is not supplied, the events from all sensors are returned.

    Example of returned stream :

event: thermometer
data: {"t":1555449989881,"sid":"thermo-1","v":38.939716,"evt":"thermometer"}
id: 1555449989881

event: crying
data: {"t":1555449940283,"sid":"cry-detector","v":false,"evt":"crying"}
id: 1555449940283

• GET /events-recent : Like the events endpoint above, but it starts by returning the "last known reading" from the sensors, so that the client knows what is the "current" situation immediately (i.e. instead of waiting for the next sensor event)
• GET /latest : Returns the last / "current" readings ..and that's it!
• GET /critical-events : Returns a paginated view of the "critical" events going to the past one "page" at the time. It accepts two optional parameters:
  • The n param specifies how many results ("critical events") each "page" will contain. If not given, it defaults to 10.
  • The key param specifies the last "key" (event id) received in a page by the client.
• GET /history/thermometer : Returns historical temperature data in a JSON array. It requires two parameters:
  • from: A long number in milliseconds specifying the starting timestamp.
  • to : A long number in milliseconds for the end timestamp.
• GET /history/crying : Returns historical data about when the baby started and ended crying, in a JSON array. It requires two parameters:
  • from: A long number in milliseconds specifying the starting timestamp.
  • to : A long number in milliseconds for the end timestamp.

All endpoints are secured using the oAuth2 Bearer "authorization" mechanism. The tokens should have been created by the xVlepsis OAuth2 server (Identity provider).

Schema for xVlepsis events coming from sensors and monitoring devices

As shown in the example above the events are represented as JSON objects with the following properties:

• sid: Source id (e.g. a sensor), a string (TODO: should we also include a device-id and node-id?)

• evt: Event type, an enumeration. Possible values: thermometer, cardio, etc.

• t: the effective time of the measurement. It is represented as a number value in milliseconds since the Epoch (January 1st, 1970). This allows for example to do the following in Javascript:

  let dateTime = new Date(t)

  while in Java you can get it through a System.currentTimeMillis() and also convert it in Dates using the same syntax: new Date(t). (There's some controversy about the best way to represent dates in JSON, we chose the most efficient. See also this discussion: https://stackoverflow.com/questions/10286204/the-right-json-date-format)

• v: the actual value. Its type depends on the event type, e.g. for a thermometer it should be a float representing baby's temperature in degrees Celsius.