HOW TO: Control GPICommander with the REST API

The documentation is organised per object (Sources, Destinations, …) that can be accessed through the API.

The fields of each object are described with their type and a comment followed by the list of all the methods that the object has. Each method has an HTTP verb (GET, POST, …) and an unique URL.

REST API Quick start guide

Here is an example of request that you can use in a simple browser :

http://127.0.0.1:8088/devices/

This will return a dictionary with the list of GPICommander devices available on that Mac (oyou can have multiple connected), which should look like this:

[
	{
		"input_count" : 24,
		"serial_number" : "10005CF7",
		"output_count" : 8
	}
]

Note that in this document, instead of writing the url that you can type in a browser (http://localhost:8080/sources), we will indicate the REST command and it will look something like this :

GET /devices

Unique id or index ?

Each GPICommander can be addressed using either its serial_number, or its index :

• The serial_number is the safest way to talk to a GPICommander as it will not change and remain unique, but you have to request first its value before being able to send arguments.
• The index is the (zero based) position of that GPICommander. It is easy to work with as you can just send arguments to the device "0". If there is only one GPICommander connected, it is maybe the easiest way.

Each input and output can be addressed using its index :

• The index is the (zero based) position of an input or output.

Working with Devices

The API allows you to manipulate the devices. The following keys are the JSON object representation of a source :

Name	Type	Content
input_count	integer	The number of inputs available on the GPICommander
serial_number	string	The serial number of the GPICommander
output_count	integer	The number of outputs available on the GPICommander

Accessing the information

GET /devices

Returns a list of devices.

Example response:

[
		{ 
			"input_count" : 24, 
			"serial_number" : "10005CF7", 
			"output_count" : 8
		}
]

Working with Outputs

The API allows you to manipulate the output. You can access their information, modify their state to on or off. The following keys are the JSON object representation of an output :

Name	Type	Content
index	string	The index of the output
state	boolean	True if the output is "on", false if the output is "off"

Accessing the information

GET /devices/{serial_number or index}/outputs

Returns a list of outputs.

Example response:

{
	"index" : 0, 
	"state" : false
}, 
{
	"index" : 1, 
	"state" : false
}, 
{
	"index" : 2, 
	"state" : false
},
{
	"index" : 3, 
	"state" : true
},
{
	"index" : 4, 
	"state" : false
},
{
	"index" : 5, 
	"state" : false
},
{
	"index" : 6, 
	"state" : false
},
{
	"index" : 7, 
	"state" : false
},
{
	"index" : 8, 
	"state" : false
},
{
	"index" : 9, 
	"state" : false
},
{
	"index" : 10, 
	"state" : false
},
{
	"index" : 11, 
	"state" : false
},
{
	"index" : 12, 
	"state" : false
},
{
	"index" : 13, 
	"state" : false
},
{
	"index" : 14, 
	"state" : false
},
{
	"index" : 15, 
	"state" : false
},
{
	"index" : 16, 
	"state" : false
},
{
	"index" : 17, 
	"state" : false
},
{
	"index" : 18, 
	"state" : false
},
{
	"index" : 19, 
	"state" : false
},
{
	"index" : 20, 
	"state" : false
},
{
	"index" : 21, 
	"state" : false
},
{
	"index" : 22, 
	"state" : false
},
{
	"index" : 23, 
	"state" : false
},

Control the Outputs

PUT /devices/{serial_number or index}/Outputs/{index}/

Pass a dictionary with the state (true or false). For example:

{ "state" : false },

 

GET /devices/{serial_number or index}/Outputs/{index}/pulse

Pass a dictionary with the keys index and state, for just one output specified by the index.

Working with Inputs

The API allows you to get the state of inputs (not change them). The following keys are the JSON object representation of an input :

Name	Type	Content
index	string	The index of the input
state	boolean	True if the input is "on", false if the input is "off"

Accessing the information

GET /devices/{serial_number or index}/inputs

Returns a list of inputs.

Example response:

{
	"index" : 0,
	"state" : false
}, 
{
	"index" : 1,
	"state" : false
}, 
{
	"index" : 2, 
	"state" : false
},
{
	"index" : 3, 
	"state" : true
},
{
	"index" : 4, 
	"state" : false
},
{
	"index" : 5, 
	"state" : false
},
{
	"index" : 6, 
	"state" : false
},
{
	"index" : 7, 
	"state" : false
},