mote API

Mote API
2014 Matti Vapa

This is a brief overview of the Mote API, used for communicating with http://hbar.kapsi.fi/ccserver/mote/ server. All of the API methods are accessed from that address, so let's call that the "base" for brevitys sake. So, if you need to access "base + put/" then the address is http://hbar.kapsi.fi/ccserver/mote/put/. Also note that the forward slashes at the end of the addresses are required.

NB! On successful operations the server will return a HttpResponse (response code 200) and on failed operations HttpResponseBadRequest (response code 400), usually containing a reason. Unfortunately in ComputerCraft the http-methods will return nil if the response code is 400, so it's impossible to figure out why the request failed. dan200, you should really fix/change this :/


Three things are needed to use the API:

	* controller
		Sends commands to the server via HTTP POST.

	* client
	    Queries the server for a new command and executes it.

	* session
		Each controller-client pair has a session to which send
		to and query from. These sessions are created on the server
		and are accessible with a session ID. Session expires
		if it is not used for an hour.

The server stores the sessions in an sqlite database. Each session has a "command" field that contains the last unaccessed command, or "null" if the command has already been sent to the client or no command has been received yet. This database is cleaned hourly to remove unactive connections. Using controller to send a command or a client to query for a command marks the session as active and it will not be removed for an hour.


Controller:

	The controller is responsible of sending the commands to the server. With Mote this is done with the HTML5 control pad, but you can write your own controllers as well. You can also use the HTML controllers code in your own projects freely.

	First, you need a session and a corresponding session ID. A new one can be generated by using HTTP GET to access "base+newID/". The server will return an eight character alphanumeric string as a HTTP response that is the ID of the newly generated session. Below you can see an example of how to do this in Lua.

		url = "http://hbar.kapsi.fi/ccserver/mote/newID/"

		response = http.get(url)

		sessionId = response.readAll()

	To send a command to the server, you need to use HTTP POST to access "base+put/", send the session ID as a data value "sessionId=XXXXXXXX" where XXXXXXXX is the session ID you got from the server and the command as a data value "command=COMMAND". Below is an example in Lua.

		url = "http://hbar.kapsi.fi/ccserver/mote/put/"

		command = "forward"

		response = http.post(url, "sessionId="..sessionId, "command="..command)

		if response then
			print("Command sent!")
		else
			print("Sending command failed :/")
		end

	If sending the command fails your session has probably expired and you need to create a new one.

	The command can be an arbitrary string up to 50 characters long.

Client:

	The client can access the commands sent to the server by accessing "base + get/" using HTTP POST and sending the session ID as a data value "sessionId=XXXXXXXX". The server will hold the connection open for up to 60 seconds until there is a command (or there already was one). If the controller sends a command during that time, it will be instantly passed to the client. If the server does not receive a command, the server will send "null" at the end of the 60 seconds. This way the client doesn't have to continuously poll the server for new commands which saves in bandwidth and improves responsivenes greatly (thanks hazzytje for the tip). A good trick is to use parallel.waitForAll in Lua to simultaneously execute the last command and wait for a new one (see the new sample client for an example http://pastebin.com/MmrwLcxS). Below is a basic example in Lua.

	url = "http://hbar.kapsi.fi/ccserver/mote/get/"

	response = http.post(url, "sessionId="..sessionId)

	if response then
		cmd = response.readAll()
		if cmd == "null" then
			print("No new commands in the last minute.")
		else
			print("Server sent the command: "..response.readAll())
		end
	else
		print("Receiving command failed :(")
	end

	If the http.post-method fails, check your session ID first. If you for some reason need the server to immediately respond whether there is a new command or not, access "base + oldget/" in the same way as above.


Please be considerate on how much traffic you send in the servers direction. It will probably hold, as it's a shared server adiministrated by people a lot more competent than I, but no need to test that. If you use this service for something, I wish that you make the codes public for others to learn from and mention my contribution somewhere. But thats a personal wish, not a requirement.

I take no responsibility for any outages in the service, but I'll try my best to keep it up and running. I also probably don't have the time, skill or motivation to implement any really major changes to the scheme (most things can be done with the current system with a bit of hacking anyway), but feel free to ask or suggest if you have some ideas on how to improve this.

For questions, comments and suggestions:
	twitter: @MattiJV
	reddit: /u/mattijv