sights-server HTTP API

[Conr86]

Here are my thoughts so far, for a new sights-server API, to which the sights-web client (and potentially other clients) connect to.

Also to be created, is be a python api (would be especially useful for autonomy)

Some notes:

• Any 'get' requests will return JSON.
• Any 'post' requests will return the appropriate HTTP status code.
• The specifics of syntax and how the requests are formatted is up for discussion, this is just a rough idea of the sort of functionality I want to expose

Sensors

Get sensors

Pretty straightforward stuff

get: /sensors/472294
returns: {
	"guid": 472294,
	"type": "MLX90640",
	"address" : 0x5C,
	"data": { // or maybe not include this here (only include with /data)
		"object": 27.3,
		"ambient": 24.6
	}
}

Save a bit of bandwidth, and have a data-only call:

get: /sensors/472294/data
returns: {
	"object": 27.3,
	"ambient": 24.6
}

Getting a list of sensors would be handy:

get: /sensors
returns: {
	sensors: [
		472294,
		678222
	]
}

Might be useful to filter also:

get: /sensors?type="mlx90614"
returns: {
	sensors: [
		472294
	]
}

Motor controller

Get controller

get: /controllers/3/
returns: {
	"guid": 3,
	"type": "Dynamixel",
	"port": "/dev/ttyACM0",
	"baudrate" : 152000,
	"motors" : [
		743,
		756
	]
	etc.
}

Motors

I have chosen to not have the URI contain the motor controller (e.g. /controllers/1/motor/233) since you rarely need to actually know what controller it's on
And you would have to lookup which controller it's on to use it.

Get motors

Individual motors are straightforward:

get: /motors/743/
returns: {
	"guid": 743,
	"type": "Dynamixel AX-12A",
	"dynamixel_id" : 1,
	"current_speed": 64,
	"torque_enabled" : "true",
	etc.
}

get: /motors/285/
returns: {
	"guid": 285,
	"type": "Sabertooth",
	"sabertooth_id" : 1,
	"current_speed": 0,
	etc.
}

But getting a list of motors would be handy:

get: /motors/
returns: {
	motors: [
		744,
		285,
		743
	]
}

Set motors

Sets the speed to 64 for motor with guid 743

post: /motors/743/set_speed?speed=64 // or similar
returns: OK

Motor groups

I actually think it might be a good idea to define groups as part of the server (not as part of the client as occasionally discussed), so groups can be reused between the manual interface and autonomy, for example.

get: /motors/groups/drive_left
returns: {
	"name": "drive_left",
	"current_speed": 0,
	"motors" : [
		743,
		744
	}
}

Cameras

Of course, integrated camera streams are an important part of Sights 2.0

Get camera data

A basic 'get list of cameras' would be useful:

get: /cameras/
returns: {
	cameras: [
		1,
		2,
		3,
		4
	]
}

Getting information about a camera:

get: /cameras/1/
returns: {
	"guid": 1,
	"name": "Front",
	"fps": 30,
	"resolution": "640x480",
	"encoding": "MJPEG"
}

And of course, getting the stream:

get: /cameras/1/stream
returns: MJPEG stream

Set camera data

Something like this

post: /cameras/1/settings?resolution=640x480
returns: OK

Other useful endpoints:

• Get i2c devices: should return a list of i2c devices
• Create new sensor: takes a sensor configuration and adds it to the database
• Create new motor / motor controller controller / motor group: same as above but for motor types
• Get and set settings for network and other important configuration options

If sights-web is installed, a plugin (completely different sort of plugin to sensor and motor plugins) should be enabled that adds the additional endpoints:

• Get active profile: returns the active interface profile (including layout files, graph configuration, control mappings, etc)
• Get and set profile options: pretty self explanatory, all the configuration options for the sights interface

If the user installs sights-web or a sights-mobile app (if ever developed) on their device (not the robot), then should all profile information (this does not include hardware configuration) be stored on the user's device or the robot?

If we are to store it on the robot, then it should be done through the additional endpoints created by the relevant plugin (sights-web or sights-mobile), and should be completely seperate from the robot's configuration.
This is keeping in line with the proposal to seperate the robot's configuration (mainly hardware stuff (sensors, motors) but also network configuration for example) from the user profiles (which handle layout, graphs, etc in each client).