Connect to Eywa

Devices or basically anything that talks websocket or http should be able to connect to Eywa. But before that, you should define your channel, so that Eywa can be aware of what kind of device it is and also make basic authentication achievable. Please read the Basic Concepts before reading the following section.

After defining your channel, you can use either websocket or make individual http requests to Eywa.

via HTTP

Push Data to Eywa

By using http requests, devices can upload data for indexing.

A typical RESTful http request would be:

curl -XPOST -H "AccessToken: abcdefg" "http://localhost:8081/channels/<channel_id>/devices/<device_id>/push?building=west-1&floor=3&room=1102&room_type=luxry" -d '{
  "brightness": 5,
  "cooler": true,
  "humidity": 75,
  "noise": 35.7,
  "pm2_5": 45,
  "temperature": 74.2
}'

We assume you have already read the example channel definition. And you can see that tag values are appended in the url params. Field values are provided in json format in the payload.

Long Polling from Eywa

While http post requests help devices to send interesting data, http long-polling helps to send signal back to devices. A typical long-polling request looks like:

curl -XGET -H "AccessToken: abcdefg" "http://localhost:8081/channels/<channel_id>/devices/<device_id>/poll?building=west-1&floor=3&room=1102&room_type=luxry" -d '{
  "brightness": 5,
  "cooler": true,
  "humidity": 75,
  "noise": 35.7,
  "pm2_5": 45,
  "temperature": 74.2
}'

The only differences here are the url and http method. The url here is tailed with poll instead of push from last example. And we use GET for long-polling connections. With this example, Eywa will also index the data from the payload, and wait for signals that will be sent to device. Each long-polling connection times out in 10 minutes by default, while it's tunable through the configuration file or via API.

via Websocket

To set up the connection, make a websocket GET request like this:

GET -H "AccessToken: abcdefg" "http://localhost:8081/channels/<channel_id>/devices/<device_id>/ws?building=west-1&floor=3&room=1102&room_type=luxry"

Similar to HTTP requests, tags are recommended to be appended in the url. This way any data you are sending to Eywa from onwards will be tagged automatically, unless you want to override them within the message body.

Pinging the Server

While websocket keeps connection open, the client does need to Ping the server periodically. See connections.websocket.timeouts.read in Configuration Details for more information.

A websocket Ping message is a standard PingMessage type defined in RFC 6455 and the server will response back a PongMessage with plain text data indicating the milliseconds from epoch. Just to help the clients to synchronize their clock.

Message Types

There are 3 major types of messages supported so far:

Upload:   1
Request:  2
Send:     3
Response: 4

Upload upstream

To upload metrics to server, you will pick Upload message. The uploaded messages are indexed asynchronously. A typical data format would be:

1|<message_id>|{"brightness":5,"cooler":true}

message_id is used to identify each individual message on server side. A recommended message_id can simply be the timestamp from epoch.

Send downstream

Send message type is sent from Eywa, and received by device. It is usually used for sending asynchronous commands. Upon receiving this message, device doesn't need to reply to Eywa. Example:

3|<message_id>|turn off lights

Request & Response

A Request message is used for server to send synchronous message to the client, expecting the client to send back a Response message. A typical Request message could be something like:

2|1456959587000|turn on cooler

This message is telling the client to turn on the cooler. To respond back to server, a client should send back a Response message:

4|1456959587000|{"cooler":true","status": "success","message":""}

As you can see, the message_id responded back to server has to be the same as what the device receives. This is because that Eywa uses this message_id to keep track of synchronous messages.

The response message can be basically anything in whatever format: telling the error, or the success, or even more information. As long as they are understood by the requester.

QoS of Messaging

QoS is a concept of how reliable a message is passed to the receiver in network messaging.

For QoS=0, message is sent at most once.

For QoS=1, message is sent at least once.

For QoS=2, message is sent exactly once.

With our http long-polling, message is sent under QoS=0. Device is not guaranteed to receive the message under certain situations. Network congestion for example.

With our websocket connection, the Upload and Send message types are of QoS=0, while the Request message type is of QoS=1. Devices need to response back to indicate of receival of message.

We have a plan to integrate Eywa with MQTT, which enables QoS=2. Please stay tuned and check out our Road Map or forum.