Programmatic Interaction with the Website

Having a programmatic interface allows one to write applications for monitoring and controlling the Virtual Wiring website. The Devices within the System and their terminal states can be queried from the website and returned in a machine friendly format. In addition, values and method calls can be posted to any Device or Device terminal in the System by posting to the website.

Querying for the Devices and Their Terminals State

The Devices and state of the system are available as a JSON string. A JSON string is returned when querying the Device Explorer page with a JSON format. If your website's Device Explorer page is visible at: localhost:4567/, query localhost:4567/?format=json to get a JSON string. The printout below is the JSON for a system with a single wireless XBee Smart Plug Device. The Coordinator Device has ID "coordinator", and the Smart Plug Device has ID "smart_plug". The Smart Plug Device is switched off.

{
  "connectors": [
    {
      "connector": {
        "id": "coordinator",
        "name": "coordinator",
        "device_id": "coordinator",
        "terminals": []
      }
    },
    {
      "connector": {
        "id": "smart_plug",
        "name": "smart_plug",
        "device_id": "smart_plug",
        "terminals": [
          {
            "terminal": {
              "id": "smart_plug:1",
              "name": "1",
              "device_id": "1",
              "connector_id": "smart_plug",
              "value": "off",
              "value_eventable_id": "smart_plug:1",
              "updated_at": "unavailable"
            }
          },
          {
            "terminal": {
              "id": "smart_plug:1S",
              "name": "1S",
              "device_id": "1S",
              "connector_id": "smart_plug",
              "value": "off",
              "value_eventable_id": "smart_plug:1S",
              "updated_at": "unavailable"
            }
          },
          {
            "terminal": {
              "id": "smart_plug:current_AMPs",
              "name": "current_AMPs",
              "device_id": "current_AMPs",
              "connector_id": "smart_plug",
              "value": "0.0",
              "value_eventable_id": "smart_plug:current_AMPs",
              "updated_at": "unavailable"
            }
          },
          {
            "terminal": {
              "id": "smart_plug:light_Lux",
              "name": "light_Lux",
              "device_id": "light_Lux",
              "connector_id": "smart_plug",
              "value": "115.0",
              "value_eventable_id": "smart_plug:light_Lux",
              "updated_at": "unavailable"
            }
          }
        ]
      }
    }
  ]
}

Querying for Device Terminals and Individual Terminal State

You can get the state of a Device's terminals or even a single terminal of a Device. Requests must be JSON gets, and results are returned as JSON strings. If your website's Device Explorer page is visible at: "localhost:4567/", and it has a Connector with an ID "front_porch", you can get the state of its Terminals by querying localhost:4567/connectors/front_porch/terminals?format=json. The printout below is a sample return value:

{
  "terminals" : [
    {
      "terminal" : {
        "id" : "front_porch:1",
        "name" : "1",
        "device_id" : "1",
        "connector_id" : "front_porch",
        "value" : "on",
        "value_eventable_id" : "front_porch:1",
        "updated_at" : "unavailable"
      }
    },
    {
      "terminal" : {
        "id" : "front_porch:1S",
        "name" : "1S",
        "device_id" : "1S",
        "connector_id" : "front_porch",
        "value" : "on",
        "value_eventable_id" : "front_porch:1S",
        "updated_at" : "unavailable"
      }
    }
  ]
}

If you want to get the state of terminal "1" of the "front_porch" connector, query localhost:4567/connectors/front_porch/terminals/front_porch:1?format=json. The printout below is a sample return value:

{
  "terminal" : {
    "id" : "front_porch:1",
    "name" : "1",
    "device_id" : "1",
    "connector_id" : "front_porch",
    "value" : "on",
    "value_eventable_id" : "front_porch:1",
    "updated_at" : "unavailable"
  }
}

Posting Events to the System

System state, Device state and terminal state can be queried and changed by posting Events to the System. When an Event is posted to the System or a Device, the Event value calls a System or Device method, the same way you might do it when poking from within the Console page. If an Event is posted to a Device terminal, the Event value is placed on the Device's terminal, the same way values are placed on Device terminals when clicking on them within the Device Explorer page.

To post an event, one posts to the events page. The events page is a write only page used for generating events within the System. To create an Event, one posts an Event with 2 or 3 required fields (depending on the Event type). The Event field names are the value field, the eventable_id field, and the eventable_type field.

The Event value field contains the value for the Event. If the Event is for the System or a Device, the value is a method call. If the Event is for a Device terminal, the value gets placed on the Device's terminal.

The Event eventable_id field says which Device or Device terminal the Event is for. For Device Events, the eventable_id is another name for the Device ID, which is the name used when creating Devices and to identify Devices in the System. If a Device with ID "switch" were created in the System, its eventable_id would be "switch". The eventable_id for a Device terminal is the terminal's Device ID followed by a colon and then the Device's terminal name. So if we wanted to send an Event to terminal "1" on the Device with ID "switch", its eventable_id is "switch:1". Events for the System have no eventable_id field.

The Event eventable_type field says what type of Event we are sending. There are three possible values: "User", "Connector" and "Terminal". We use "User", if we are generating an Event for the System. We use "Connector", if we are creating an Event for a Device. We use "Terminal", if we are creating an Event for a Device's terminal.

As an example, we'll create a curl command which turns on the XBee Smart Plug device in the system we queried earlier. We'll use the command line program curl, because it's often pre-installed on *nix systems, and if it is not, it can easily be installed. You can also use most any programming language (C, C++, Javascript, Python, Perl, Ruby, ...) to create Events. In this example, we are sending an Event with the value "on" to terminal "1" of the Smart Plug Device.

curl -X POST http://localhost:4567/events -H 'Accept: application/json' -d 'event[value]=on' -d 'event[eventable_id]=smart_plug:1' -d 'event[eventable_type]=Terminal'

Here, we send a do_AT command to the "coordinator" Device asking for its identifier (the NI command).

curl -X POST http://localhost:4567/events -H 'Accept: application/json' -d 'event[value]=do_AT "NI"' -d 'event[eventable_id]=coordinator' -d 'event[eventable_type]=Connector'

Here, we ask the System for its Devices. As we mentioned earlier, there is no eventable_id field when talking to the System.

curl -X POST http://localhost:4567/events -H 'Accept: application/json' -d 'event[value]=devices' -d 'event[eventable_type]=User'