API

AirPointr Raspberry runs as a background service. A connection is established through UDP. All messages are formatted as JSON.

• Service discovery
• Register to a service
• Message format

---

## Service discovery

Each AirPointr instance annouces itself using a broadcast on port 8980. The broadcast message is sent every 5 seconds.

The data field of the broadcast message holds the following information structure:

• type: <string> "discovery"
• service: <string> "airpointr"
• hostname: <string> name of host
• tag: <string> user defined identifier
• version: <string> current application version
• services: List of <string> that are formatted "<string>:<optional_argument>:<uint16>"
  • udp: <uint16> udp-port of gesture server, default = 8980
  • http: <uint16> port of configuration webserver, default = 8080
  • ws: <string:uint16> name:port of websocket interface, default = airpointr:8081

Example message

{
	"type": "discovery",
	"service": "airpointr",
	"hostname": "raspberrypi",
	"tag": "",
	"version": "1.7.0",
	"services": [
		"udp:8980",
		"http:8080",
		"ws:airpointr:8081"
                ]
	}
}

## Registration

UDP

A client is registered to the AirPointr service by sending a UDP packet directed to the server using the UDP port published by the discovery message. The data field of the packet has to start with the string "register". Any further content as well as any packet not starting with "register" will be ignored. On recpetion of such register message, the server stores the IP address and originating port of the client and starts sending gesture data to this client. There is a limit of ten (10) simultanous UDP clients on one AirPointr appliance. If this limit is exceeded a negative registration confirmation is returned as lined out below.

Format of the response message

• op: <string> "register"
• success: <bool> - depending on the success of the registration procedure

Example response packet

{
	"op": "register",
	"success": true
}

Websocket

As WebSockets are based on a TCP/IP stream no explicit registration procedure is necessary. After opening the connection to the WebSocket server it will immediately respond with a welcome message formed like this:

{
   type:    "info",
   message: "MYESTRO AirPointr v1.0.0"
}

After this the server will send JSON messages identical to those of the UDP server on each pointer update.

## Pointer messages

On every update of the pointer application the server sends a UDP message to every enlisted client. This message contains the pointer information formated as follows:

• type: <string> "pointer"
• x: <string> x-coordinate [0..1]
• y: <string> y-coordinate [0..1]
• active: <boolean> true if an object is being tracked
• moving: <boolean> true if the object is moving
• events: list of <string>s. Possible entries: "lwipe", "rwipe"
• circle:
  • active: <boolean> true if the activation circle was detected
  • phi: <float> Angle on the circle in a range of [0..2Pi]
  • direction: <int> -1: clockwise, 1: counter-clockwise
  • rotation: <int> -1: clockwise, 0: no movement, 1: ccw
  • turns: <int> number of turn accumulated, <0 clockwise, >0 counter-clockwise
  • segment: <int> [0..7], (description below)
  • smart:
    • enabled: <boolean> true if smart circle is enabled
    • segment: <int> [0..3], up/north = 0, right/east = 1, down/south = 2, left/west = 3
    • actionSegment: <int> [0..3], segment that was active when the action select/left was triggered
    • actionSelect: <boolean> true if action select was triggered
    • actionLeft: <boolean> true if action left was triggered
• license: <string> "licensed", "demo" or "invalid"

Segments

Each of the segments correspond to 1/8 of the circle. Segment numbers increase counter-clockwise with segment 0 being centered around 12 'o clock, segment 1 at 10:30, segment 2 at 9 o'clock and so on.

Example message

{
	"type": "pointer",
	"x": 0.5,
	"y": 0.25,
	"active": true,
	"moving": false,
	"events": [],
	"circle": {
		"active": true,
		"phi": 0.0,
		"direction": 1,
		"rotation": 1,
		"turns": 0,
		"segment": 0
	        "smart": {
			"enabled": true,
			"segment": 3,
			"actionSegment": 3,
			"actionSelect": true,
			"actionLeft": false,
	        },
	},
	"license": "licensed"
}