OiS Serial Data Protocol

Version: 1, Game Min Version: 0.8.7

CHANGES

First version.

FORMAT

The OiS Serial Protocol (SP) is text-based. This is for two reasons: one, it means it is human-readable, making debugging a bit easier. And two, because it allows a human to create a fake I/O client via a virtual serial port to test the way the system runs.

All lines are text that end in a \n (char 13) delimiter, and are either three uppercase characters to indicate the command, or three uppercase characters to indicate the command followed by an equals sign, and a value.

Sample valid lines include:

ACK
EXC=14
NIB=1,MAIN_ENGINE_BURNING
CMD=4,BURN_MAIN_ENGINE

STATES

There are three basic states each individual Serial IO client can have:

  • HANDSHAKING is when the game is listening for a Sync request from a serial client
  • SYNCING is when the game is waiting for all required inputs and outputs to be defined
  • ACTIVE is when the game is sending live data to the client and is prepared to receive command requests

HANDSHAKING

The default state, the only valid thing to be done here is that the client sends a Sync request command.

Client Commands:

SYN – client is identifying itself as an Arduino, with the parameter being the protocol version. While waiting for a response, our consoles tend to send these requests every few seconds until they get a response from the server. The only parameter is the protocol version.

Example: SYN=1
Server Commands:

ACK – the server received the SYN request and acknowledges it, moving on to the Synchronisation state.

DEN – the server received the SYN request but does not know this protocol version. Will remain in the HANDSHAKING state.

SYNCHRONISATION

In this state, the server waits for the client to define all the inputs and outputs it has, and to be told to move into an active state.

Client commands:

CMD – the client will execute a command on a given channel. Parameters are the numerical command channel (an integer >= 0), and the text command to be executed.

Example: CMD=4,BURN_MAIN_ENGINE

NIB – the client requests a boolean bit of live data on a given channel. Parameters are the numerical input channel (an integer >= 0), and the text command to be executed.

Example: NIB=1,MAIN_ENGINE_BURNING

NIN – the client requests a whole number value on a given channel. Parameters are the numerical input channel (an integer >= 0), and the text command to be executed.

Example: NIN=2,POWER_LEVEL

NIF – the client requests a decimal number value on a given channel. Parameters are the numerical input channel (an integer >= 0), and the text command to be executed.

Example: NIF=2,CURRENT_SPEED

ACT – the client is done configuring the commands and wants to enter an ACTIVE state. No parameters.

Server commands:

nil

ACTIVE MODE

In this state, the server will send live updates of data requested by the client, and the client may send commands to execute when buttons are pushed.

Client commands:

EXC – the client wishes to execute a previously-defined command. The only parameter is the command channel (an integer >= 0).

Example: EXC=4

DBG – the client wishes to send debug information to go into the server’s logs. The parameter is all text following the equals symbol.

Example: DBG=Hello, Debug World!
Server commands:

All data coming from the server is in a very simple k/v pair in this mode. The key is always the input channel, followed by the value, with an equals symbol between them.

Valid keys:

The input channel. Example: 1

Valid values:

Boolean: 1/0 for True/False
Numerical: [whole number], eg ‘400’ or ‘4’
Float: The value represented without a decimal point, with two places. For instance, 4.23 would be ‘423’, and 1024.89 would be ‘102489’

DATA REQUESTS

Boolean
NAV_TARGET_SELECTED
IS_MOVING
MAIN_ENGINE_BURNING
HAS_SELECTED_DIRECTION
HAS_COURSE_PLOTTED
AUTO_PILOT_ENGAGED
AUTO_PILOT_NOT_ENGAGED
DOCKED_WITH_JUMPGATE
HAS_SELECTED_OBJECT
MAP_LOCKED_TO_SHIP
MAP_IN_SECTOR_MODE
PWR_CURRENT_MODULE_ON
PWR_CURRENT_MODULE_OFF
PWR_CURRENT_MODULE_EMCON_ON
PWR_CURRENT_MODULE_EMCON_OFF
PWR_CURRENT_MODULE_CAN_SCRAM
PWR_REACTOR_ON
PWR_REACTOR_OFF
IS_STATIONARY
RCS_BURNING
EMCON_MODE
HAS_SELECTED_DESTINATION
STATUS_WARNING
STATUS_DANGER
STATUS_NOMINAL
IN_ASTEROID_FIELD
IN_NEBULA
TUBE_HAS_MISSILE
TUBE_HAS_MINE
TUBE_HAS_PROBE
TUBE_CAN_SPIN_UP
TUBE_CAN_FIRE
TUBE_CAN_LAUNCH
TUBE_LAUNCHED
TUBE_EMPTY
TUBE_SPINNING_UP
TUBE_LINKED
TUBE_HAS_EXP
TUBE_HAS_EMP
TARGET_AND_WEAPON_SELECTED
CAN_ROTATE
PCE_ALARM
CLUSTER_MODE
IS_IN_ORBIT
IS_IN_STANDARD_ORBIT
IS_IN_HIGH_ORBIT
IS_IN_POLAR_ORBIT
NOT_IN_STANDARD_ORBIT
NOT_IN_HIGH_ORBIT
NOT_IN_POLAR_ORBIT
IS_IN_FREE_SPACE
IS_CHANGING_ORBIT
IS_LEAVING_ORBIT
IS_ENTERING_ORBIT
IS_CORRECTING_ORBIT
IS_IN_STABLE_ORBIT
NOT_DOCKED
IS_DOCKED_OR_DOCKING
IS_DOCKED
IS_DOCKING
IS_FULLY_DOCKED
IS_UNDOCKING
NOT_DOCKING
NOT_UNDOCKING
CAN_OPEN_AIRLOCK
HAS_DOCKING_PERMISSION
NEEDS_DOCKING_PERMISSION
HAS_UNDOCKING_PERMISSION
NEEDS_UNDOCKING_PERMISSION
ANY_AIRLOCK_OPEN
ALL_AIRLOCKS_SEALED
AIRLOCKS_CLOSED_BUT_NEEDS_UNDOCK_PERMISSION
CAN_UNDOCK
IFF_ACTIVE
SELECTED_OBJECT_CAN_COMMUNICATE
OWES_MONEY_TO_DOCKED_STATION
IS_DOCKED_WITH_STATION
IS_DOCKED_WITH_JUMPGATE
NEED_TO_PAY_FOR_JUMPGATE
CAN_ACTIVATE_JUMPGATE
NOT_DOCKED_WITH_STATION
AUTO_REPAIR_ENABLED
AUTO_REPAIR_IDLE
MODULE_REACTOR_UNDAMAGED
MODULE_REACTOR_DAMAGED
MODULE_REACTOR_DESTROYED
MODULE_REACTOR_CONNECTED
MODULE_REACTOR_FUNCTIONING
MODULE_MAINDRIVE_UNDAMAGED
MODULE_MAINDRIVE_DAMAGED
MODULE_MAINDRIVE_DESTROYED
MODULE_MAINDRIVE_CONNECTED
MODULE_RCS_UNDAMAGED
MODULE_RCS_DAMAGED
MODULE_RCS_DESTROYED
MODULE_RCS_CONNECTED
MODULE_COMMS_UNDAMAGED
MODULE_COMMS_DAMAGED
MODULE_COMMS_DESTROYED
MODULE_COMMS_CONNECTED
MODULE_BATT1_UNDAMAGED
MODULE_BATT1_DAMAGED
MODULE_BATT1_DESTROYED
MODULE_BATT1_CONNECTED
MODULE_BATT2_UNDAMAGED
MODULE_BATT2_DAMAGED
MODULE_BATT2_DESTROYED
MODULE_BATT2_CONNECTED
MODULE_BATT3_UNDAMAGED
MODULE_BATT3_DAMAGED
MODULE_BATT3_DESTROYED
MODULE_BATT3_CONNECTED
MODULE_HELM_UNDAMAGED
MODULE_HELM_DAMAGED
MODULE_HELM_DESTROYED
MODULE_HELM_CONNECTED
MODULE_SENSORS_UNDAMAGED
MODULE_SENSORS_DAMAGED
MODULE_SENSORS_DESTROYED
MODULE_SENSORS_CONNECTED
MODULE_NAVCOM_UNDAMAGED
MODULE_NAVCOM_DAMAGED
MODULE_NAVCOM_DESTROYED
MODULE_NAVCOM_CONNECTED
MODULE_WEAP_UNDAMAGED
MODULE_WEAP_DAMAGED
MODULE_WEAP_DESTROYED
MODULE_WEAP_CONNECTED
MODULE_JUMPDRIVE_UNDAMAGED
MODULE_JUMPDRIVE_DAMAGED
MODULE_JUMPDRIVE_DESTROYED
MODULE_JUMPDRIVE_CONNECTED
SHOW_SPACE_DISC
DONT_SHOW_SPACE_DISC
TUBE_1_SELECTED
TUBE_2_SELECTED
TUBE_3_SELECTED
TUBE_4_SELECTED
TUBE_5_SELECTED
ENG_MODULE_ON
ENG_MODULE_OFF
ENG_MODULE_CAN_OPEN
ENG_MODULE_OPEN
ENG_NO_MODULE_OPEN
ENG_CAN_CLOSE_CURRENT_MODULE
ENG_MODULE_CAN_BE_CONNECTED
ENG_NO_TRAY_OBJECT_SELECTED
ENG_CAN_REPAIR_COMPONENT
ENG_IS_REPAIRING
JMP_CAN_SET_JUMP_DESTINATION
JMP_CAN_SPIN_UP_JUMP_DRIVE
JMP_CAN_CALC_JUMP
JMP_CAN_JUMP
JMP_CAN_DISCHARGE_JUMP_DRIVE
JMP_HAS_JUMP_DRIVE
JMP_IS_SPINNING_UP
JMP_IS_CALCULATING_JUMP
JMP_IS_SPUN_UP
JMP_IS_CALCULATED
PWR_LOW_POWER_WARNING
PWR_IS_DRAINING
PWR_IS_GENERATING
IS_TURNED_ON
IS_TURNED_OFF
Numerical
POWER_LEVEL
POWER_DRAIN
POWER_DRAW_PERCENT
DESIRED_DIRECTION
MOTION_ANGLE
DIRECTION
CURRENT_SPEED
CURRENT_SPEED_PERCENT
PRESSURE_EXTERIOR
PRESSURE_INTERIOR
PRESSURE_AIRLOCK
CURRENT_TEMPERATURE
CURRENT_DISTANCE
ASTEROID_DENSITY
NEBULA_DENSITY
TUBE_SELECTED
AMOUNT_OWED_TO_DOCKED
AMOUNT_OWED_VIA_COMMS
AUTO_REPAIR_PERCENT
CURRENT_TUBE_SPIN_UP_PERCENT
ENG_CURRENT_REPAIR_PERCENT
ENG_CURRENT_SPARE_PARTS
ENG_MAX_SPARE_PARTS
JMP_SOLUTION

(full descriptions TBA)

NOTES

The game will send a full batch of updates at the beginning, with all the current states. Thence, they will be changed every few seconds or whenever the value changes. In this way, any issues where some data gets corrupted or lost should be rectified within a short period of time. The time each data point will force itself to update is random, so that you don’t get a huge flood of data every X seconds. Instead, you should get a steady stream of data updates.