Pattern projection protocol

Pattern projection protocol

We want to use a simple and standard communication protocol. We don't require super-fast communication either.

In a previous project I used JSON-RPC and it was easy to use and debug, and did the job just fine. So at least initially we'll use this for communication between the computer and projector.

JSON-RPC

The official JSON-RPC specification is pretty clear and concise, but we'll repeat here some basic details.

A request message looks like this:

{
	"jsonrpc": "2.0",
	"method": "subtract", 
	"params": [42, 23], 
	"id": 1
}

And the result might be:

{
	"jsonrpc": "2.0", 
	"result": 19, 
	"id": 1
}

If a method call fails the server will return an error response instead:

{
    "jsonrpc": "2.0",
    "id": 1
    "error": {
        "code": -32601,
        "message": "Method not found"
    }
}

Methods

We basically need only two methods, one to send the patterns and other to project them.

Set patterns data

This sets the data of the patterns that will be available for use later. Afterwards we'll use them just by id.

Request

{
	"jsonrpc": "2.0",
	"id": 2
	"method": "projector.setPatterns",
	"params": {
		"patterns": [
			{
				"id": 10,
				"width": 1,
				"height": 1,
				"data": "<Base64 encoded binary RGBA 8 bit data>"
			},
			{
				"id": 41,
				"width": 1280,
				"height": 1,
				"data": "<Base64 encoded binary RGBA 8 bit data>"
			}
		]
	}
}

Response

If the request is executed correctly the result will be just null (if it fails you'll get the standard error response!).

{
	"jsonrpc": "2.0",
	"id": 2
	"result": null
}

Project sequence of patterns

This will display a sequence of patterns specified by their ids. Extra parameters can also be used to indicate offset or wrapping mode (somewhat similar to OpenGL textures).

Request

{
	"jsonrpc": "2.0",
	"id": 2
	"method": "projector.projectPatterns",
	"params": {
		"patterns": [
			{
				"id": 0, // id is the only mandatory parameter
				// other optional parameters like:
				"offset": { 
					// where should the pattern be positioned
					"x": 640, // default == 0
					"y": 360 // default == 0
				},
				"wrap": { 
					// how should the pattern be extended to fill the screen?
					"vertical": "clamp", // default == repeat
					"horizontal": "repeat", // default == repeat
				},
				"delay": 400, // override delay to use for this pattern
			}, {
				"id": 1
				// will use defaults for other parameters
			}, {
				"id": 22
				// will use defaults for other parameters
			}
		],
		"delay": 200, // default delay between patterns, in msecs
		// other optional parameters?
	}
}

Response

If the request is executed correctly the result will be just null (if it fails you'll get the standard error response!).

{
	"jsonrpc": "2.0",
	"id": 2
	"result": {}
}