Open Interactivity System

Custom user input/output devices for games.

View this file with a night/dark theme here.

Goals

By adding support for the OIS protocol to your game, your users can create their own physical input devices using hobbyist hardware such as Arduino.

Use cases:

• Physical installations / arcades / trade show booths
• Immersive simulations
• Unique games designed for custom input devices
• Accessibility for users who are not comfortable with traditional inputs
• This was build with video games in mind, but anyone who wants to create custom physical buttons / sliders / knobs / LEDs / etc and control them from a PC could also find this project useful.

This project defines a communication specification, plus reference implementations that can be dropped into your games / input devices.

Implementations

TODO: How to use / configure

• cpp
  • Use if adding support to your game/app to act as a host.
  • Use if making a controller where C++ is applicable.
• arduino
  • Use if making a physical controller based on Arduino hardware
• javascript
  • Use if making a Web-browser based controller.

Examples

• javascript/example/example_uil
  • A HTML virtual controller using Websockets
• javascript/example/example_pixi
  • Another HTML virtual controller using Websockets
• arduino/example
  • Example Arduino IDE project
• app_ois_hub
  • A C++ host (e.g. as you would use in a game) using serial (COM) ports and Websockets
  • A C++ client / virtual controller using serial (COM) ports
  • A virtual direct input device (translate OIS commands to vJoy commands)
  • A GUI to visualize OIS state / communication

TODO

This library is a work in progress. Contributors welcome!

• Usable features:
  • C++ host (for use in your games)
  • C++ client (for use in controllers)
  • Arduino client (for use in physical controllers)
  • JavaScript client (for use in web controllers)
  • Example GUI application
  • Game compatibility
    • Objects in Space
    • 22 Racing Series
• Documentation!
  • README files
  • ASCII protocol description
    • Backus–Naur form?
  • Binary protocol description
  • State diagram
• Test compatibility with the "v1" spec:
  • Test the Arduino device code against Objects In Space game.
  • Test the C++ host code against other arduino libraries (e.g. Arduinos In Space).
• Collaborate with the community to nail down an ideal "v2" spec.
  • Extra data type support -- strings, 32bit int + real float?
  • More testing of the binary communication mode.
• Example implementations in other languages
  • C++
  • Javascript
  • C#
• Other transport mechanisms
  • Serial ports
  • Websockets
  • TCP, HTTP, pipes, shared memory?
• Port to platforms other than Windows.
• Game Engine examples (Unity, Unreal?).
• Example apps
  • Translate data from an OIS device into a virtual Direct Input device using vJoy (allow OIS devices to work on non-OIS-compatible games)

Background

This project is inspired by an an extension of the serial protocol developed by Flat Earth Games for Objects In Space, described here:

• http://objectsgame.com/the-controllers/arduino-tutorial/
• http://objectsgame.com/the-controllers/ois-serial-data-protocol/

And with existing library support here:

• https://github.com/Segwegler/OIS_Library
• https://bitbucket.org/pjhardy/arduinosinspace/src/master/

These existing libraries and specification are referred to as "v1" here, with this project presented as a proposal for a possible "v2".

Protocol Overview

Protocol states

• Handshaking (HS)
  • Device requests a connection from the host, negotiates the protocol version.
• Synchronisation (SYN)
  • Device registers inputs, outputs and commands that it can send/receive.
• Active (ACT)
  • Device and host send/receive values and commands.

Data Types

• Boolean - true or false
  • 0 or 1
• Number - 16 bit signed integer
  • -32768 to 32767
• Fraction - 16 bit signed integer, scaled by 100 (i.e. The number 1.5 is encoded as 150)
  • -327.68 to 327.67

Transmission formats

TODO: Binary / ASCII description

Protocol messages (ASCII)

Command		Host send	Device send	HS state	SYN state	ACT state
SYN	Begin Synchronisation stage		✓	✓	✓₂	✓₂
ACK	Acknowledge connection	✓		✓
DEN	Deny connection	✓		✓
PID	Register device name/ID		✓₂		✓₂
CMD	Register command		✓		✓	✓₂
NIB	Add numeric input (boolean) registration		✓		✓	✓₂
NIN	Add numeric input (number) registration		✓		✓	✓₂
NIF	Add numeric input (fraction) registration		✓		✓	✓₂
NOB	Add numeric output (boolean) registration		✓₂		✓₂	✓₂
NON	Add numeric output(number) registration		✓₂		✓₂	✓₂
NOF	Add numeric output (fraction) registration		✓₂		✓₂	✓₂
TNI	Toggle numeric input activity		✓₂		✓₂	✓₂
ACT	End synchronisation state / begin active state		✓		✓
EXC	Execute command		✓			✓
DBG	Debug messaging		✓	✓₂	✓₂	✓
#	Numeric input/output key/value	✓	✓₂			✓
END	Reset to handshake stage	✓₂	✓₂	✓₂	✓₂	✓₂

₂ = introduced in version 2

Protocol messages (binary)

Handshaking still occurs in ASCII; communication swtiches to binary after a request to use the binary protocol is accepted with an ACK message from the host.

Command	Header	Bytes		Host send	Device send	HS state	SYN state	ACT state
CL_CMD	0x01	3+string (\0 terminated)	Register command		✓		✓	✓
CL_NIO	0x02 / 0x12 / 0x22 / 0x42 / 0x52 / 0x62 /	3+string (\0 terminated)	Add numeric input or output registration		✓		✓	✓
CL_ACT	0x03	1	End sync state / begin active state		✓		✓
CL_DBG	0x04	1+string (\0 terminated)	Debug messaging		✓	✓	✓	✓
CL_TNI	0x05 / 0x15	3	Toggle numeric input activity		✓		✓	✓
CL_PID	0x06	9+string (\0 terminated)	Register device name/ID		✓		✓
CL_EXC	0x0C / 0x0D / 0x0E	1/2/3	Execute command		✓			✓
CL_VAL	0x08 / 0x09 / 0x0A / 0x0B	2/3/4/5	Numeric output key/value		✓			✓
SV_VAL	0x01 / 0x02 / 0x03 / 0x04	2/3/4/5	Numeric input key/value	✓				✓
END	0x45 / 'E' (END\n)	4	ASCII END command	✓	✓		✓	✓
SYN	0x53 / 'S' / (SYN=)	4+string (\n terminated)	ASCII SYN command		✓	✓	✓	✓

Even though handshaking must complete before binary communication begins, host implementations should correctly handle an ASCII SYN command, as these can occur if a controller is power-cycled after a connection is established.

ASCII Protocol in-depth

TODO - details

For now, see the Objects In Space specification, although it does contain some errata and no details on v2 commands... sorry.

Binary Protocol in-depth

Device to Host (Client) messages

Device to host messages take up 1 or more bytes, with a message type identifier in the lowest 4 bits of the first byte. The high 4 bits of some message types are used to store additional message data. Unless the message type contains a string, the size of a message in bytes can be determined from the type parameter alone.

| Byte 0        || Byte 1+       ||
|0|1|2|3|4|5|6|7||0|1|2|3|4|5|6|7||
| Type  | Extra || Data          ||

Some messages contain ASCII string data, which appears immediately after the regular message bytes, and is terminated with a NULL byte (0x00).

For example, a DBG message header is a single byte, followed by a string. A DBG message containing the two-byte string "Hi" would be encoded as the following 4 bytes:

| Byte 0        || B1 || B2 || B3 ||
|0|1|2|3|4|5|6|7||    ||    ||    ||
|CL_DBG |       ||'H' ||'i' ||'\0'||
| 0x4   | 0x0   ||0x48||0x69||0x00||
| 0x04          ||

Message byte layouts

Command	Type	Extra	Following bytes
CL_CMD	0x1	Must be 0	Byte 1: Low byte of channel ID Byte 2: High byte of channel ID Byte 3+: String event name (\0 terminated)
CL_NIO	0x2	Bitmask of: 0x1: Number (N*N) 0x2: Fraction (N*F) 0x4: Output (NO*)	Byte 1: Low byte of channel ID Byte 2: High byte of channel ID Byte 3+: String input/output name (\0 terminated)
CL_ACT	0x3	Must be 0	None
CL_DBG	0x4	Must be 0	Byte 1+: String debug message (\0 terminated)
CL_TNI	0x5	0x0: False / deactivate 0x1: True / activate	Byte 1: Low byte of hannel ID Byte 2: High byte of channel ID
CL_PID	0x6	Must be 0	Bytes [1-4]: Product ID (32bit little endian) Bytes [5-8]: Vendor ID (32bit little endian) Byte 9+: Device name (\0 terminated)
CL_EXC_0	0xC	Channel ID (low 4 bits)	None
CL_EXC_1	0xD	High byte of the channel ID (low 4 bits)	Byte 1: Low byte of hannel ID
CL_EXC_2	0xE	Must be 0	Byte 1: Low byte of hannel ID Byte 2: High byte of channel ID
CL_VAL_1	0x8	Value (low 4 bits)	Byte 1: Low byte of the channel ID
CL_VAL_2	0x9	High byte of value (low 4 bits)	Byte 1: Low byte of value Byte 2: Low byte of channel ID
CL_VAL_3	0xA	High byte of channel ID (low 4 bits)	Byte 1: Low byte of value Byte 2: High byte of value Byte 3: Low byte of channel ID
CL_VAL_4	0xB	Must be 0	Byte 1: Low byte of value Byte 2: High byte of value Byte 3: Low byte of channel ID Byte 4: High byte of channel ID
END	ASCII	Byte 0: 'E' (0x45)	Byte 1: 'N' (0x4E) Byte 2: 'D' (0x44) Byte 3: '\n' (0x0A)
SYN	ASCII	Byte 0: 'S' (0x35)	Byte 1: 'Y' (0x59) Byte 2: 'N' (0x4E) Byte 3: '=' (0x3D)

ASCII Conflicts

The valid ASCII commands may conflict with some binary type values, and must be differentiated by looking at the entire Byte 0 value:

Type	Binary command	Byte 0	ASCII command	Byte 0
0x5	CL_TNI	0x05 / 0x15	END	0x45
0x5	CL_TNI	0x05 / 0x15	SYN	0x35

Host to Device (Server) messages

Device to host messages take up 1 or more bytes, with a message type identifier in the lowest 3 bits of the first byte. The high 5 bits of some message types are used to store additional message data. The size of a message in bytes can be determined from the type parameter alone.

| Byte 0        || Byte 1+       ||
|0|1|2|3|4|5|6|7||0|1|2|3|4|5|6|7||
| Type| Extra   || Data          ||

Message byte layouts

Command	Type	Extra	Following bytes
SV_VAL_1	0x1	Value (low 5 bits)	Byte 1: Low byte of the channel ID
SV_VAL_2	0x2	High byte of value (low 5 bits)	Byte 1: Low byte of value Byte 2: Low byte of channel ID
SV_VAL_3	0x3	High byte of channel ID (low 5 bits)	Byte 1: Low byte of value Byte 2: High byte of value Byte 3: Low byte of channel ID
SV_VAL_4	0x4	Must be 0	Byte 1: Low byte of value Byte 2: High byte of value Byte 3: Low byte of channel ID Byte 4: High byte of channel ID
END	ASCII	Byte 0: 'E' (0x45)	Byte 1: 'N' (0x4E) Byte 2: 'D' (0x44) Byte 3: '\n' (0x0A)

EXC and VAL commands

The EXC (execute command) and VAL (set numeric input/output value) commands have a total of 11 different variants which can be used to reduce message sizes. The limits of each of these commands is listed below. n.b. "value" here is the numeric value when interpreted as an unsigned integer (uint16_t in C/C++).

Command	Size in bytes	Limitation
CL_EXC0	1	channel < 16
CL_EXC1	2	channel < 4096
CL_EXC2	3	any channel
CL_VAL_1	2	channel < 256 AND value < 16
CL_VAL_2	3	channel < 256 AND value < 4096
CL_VAL_3	4	channel < 4096
CL_VAL_4	5	any channel / value
SV_VAL_1	2	channel < 256 AND value < 32
SV_VAL_2	3	channel < 256 AND value < 8192
SV_VAL_3	4	channel < 8192
SV_VAL_4	5	any channel / value

License

MIT