PiCloud

A websocket server for simple Raspberry Pi pub/sub.

Build and deploy with Fabric

fab --user=username --hosts=remote_hostname build_deploy

Environment Variables

• PORT - Port for server. Defaults to 9000
• API_KEY - API Key required for authenticated requests.
• USE_TLS - Set this variable to enable TLS
• KEY_FILE - Path to TLS key file
• CERT_FILE - Path to TLS cert file
• DEPLOY_USER - User for SSH connection (Fabric deployment only)
• DEPLOY_HOST - Host for SSH connection (Fabric deployment only)

Websocket

Websocket subscription route

This route requires authentication with an API key passed in via the X-API-Key header or apiKey query parameter. Additionally, each connected client must send a query parameter clientName.

/subscribe?clientName=Something

Subscribe to an event

Send the following JSON message to subscribe to an event. After subscribing, your connection will receive data from any other connection that publishes that event.

{
    "action": "subscribe",
    "event": "whatever"
}

Websocket publish route

This route requires authentication with an API key passed in via the X-API-Key header or apiKey query parameter. Additionally, each connected client must send a query parameter clientName.

/publish?clientName=Something

{
    "event": "whatever",
    "data": "howdy"
}

Websocket info route

This route requires authentication with an API key passed in via the X-API-Key header or apiKey query parameter. This socket does not handle any incoming messages. It pushes a JSON message every 5 seconds with info about the clients connected to the server. This is used to run the picloud-info-web app.

/info

{
    "subscriptions": [
        {
            "name": "test",
            "connections": [        
                {   
                    "ip_address": "192.168.99.1:62178",     
                    "connected_at": "2015-11-25T03:40:13.433493056Z"
                }
            ]
        }
    ],
    "all_connections": [
        {
            "ip_address": "192.168.99.1:62178",
            "connected_at": "2015-11-25T03:40:13.433493056Z"
        },
        {
            "ip_address":"192.168.99.1:62184",
            "connected_at":"2015-11-25T03:40:31.147654724Z"
        }
    ],
    "created_at":"2015-11-25T03:40:39.889395863Z"
}

HTTP Routes

Publish data

Each request must send a query parameter clientName or a header X-API-Client-Name.

POST:

/publish?clientName=Something

Body:

{
    "event": "whatever",
    "data": "howdy"
}

Response: None

Status Codes:

• 201 if successful
• 400 if incorrect data provided
• 401 if invalid X-API-Key