DiveIno Serial API

Contents

1. 1. General commands
2. 2. Logbook related commands
3. 3. Settings management commands
4. 4. Diagnostics mode commands
5. 5. Emulator mode commands
6. 6. Replay mode commands
7. 7. Difference
8. 8. Examples

Development, testing and communication with DiveIno is not an easy task to do. Let me cite some major activities, which needs to be done regularly:

1. Check sensors
2. Simulate dives to perform tests
3. Adjust settings
4. Download logbook and dive profile data
5. Reset DiveIno to default state

Of course DiveIno logs some data to the serial output, which can be monitored with the Serial Monitor, but it does not solve all problems. For instance if I would like to download my dive profile data, I have to disassemble the Arduino board and the TFT LCD display. Then I can remove the SD card from the slot and plug it into a card reader, which is connected to my PC. At this point I can download the files from the SD card. It is quite cumbersome! A better solution is needed!

It is quite common that embedded devices offers a management API called AT commands. The input message starts with the AT - ATtention - characters. The rest of the message has a special syntax. For instance the AT+RST command resets the device. The communication usually happens through the serial line. Sometimes devices has a special command mode, where it handles AT commands.

Based on these I decided to implement a communication API for DiveIno, which mimics the well known AT commands based management API. It works through the serial communication line between the Arduino board the connected computer, therefore the built-in Arduino Serial Monitor can be used for interaction with DiveIno.

I wanted to increase the API readability and clearly indicate when a command was terminated, therefore each message starts with the @ (at) and ends with the # (hash mark) character. All keywords are in uppercase. For instance the @VERSION# command returns with the current DiveIno software version number.

The following commands constitutes DiveIno Serial API:

General commands

These commands turns on and off the emulator and replay modes, which are useful for testing. DiveIno reset can be solved with these commands as well as the current version number can be retrieved.

Received by DiveIno	Sent by DiveIno	Description
@EMULATOR ON/OFF#		Turn emulator mode on/off
@REPLAY ON/OFF#		Turn replay mode on/off
@VERSION#	@1.5.3#	Return DiveIno version
@RESET#		Completely reset DiveIno
@CLEAR#		Clear surface time

Logbook related commands

DiveIno logbook and dive profile data is stored in separate JSON files. These commands can download these files without disassembling DiveIno.

Received by DiveIno	Sent by DiveIno	Description
@LOGBOOK#	Logbook.json	Return logbook information
@PROFILE 2#	Dive0002.json	Return the given profile

Settings management commands

DiveIno settings are stored in a JSON file. This can be downloaded and managed by these commands.

Received by DiveIno	Sent by DiveIno	Description
@SETTINGS#	Settings.json	Return all settings
@DEFAULT#		Restore default settings
@AUTO#		Automatically set sea level pressure
@SOUND ON/OFF#		Turn sound on/off
@METRIC ON/OFF#		Switch between metric and imperial units
@PRESSURE 1012.5#		Set sea level pressure in millibars
@OXYGEN 0.32#		Set oxygen %
@DATETIME 2017-06-04 10:32#		Set date and time

Diagnostics mode commands

Several modules are connected to the Arduino board in DiveIno hardware setup. These can be monitored with these commands.

Received by DiveIno	Sent by DiveIno	Description
@DIAG TEMP#	@21.5#	Current temperature in celsius
@DIAG PRES#	@1023.4#	Current pressure in millibar
@DIAG BAT#	@68.2#	Battery charge percentage
@DIAG DATE#	@2017-04-12 10:32#	Current date and time
@DIAG TIMESTAMP#	@1483434812#	Current unix timestamp

Emulator mode commands

In this mode DiveIno performs a “dry” dive, which means that the emulator will provide the pressure and temperature information to DiveIno based on a preset profile.

By default the emulator mode is turned off. It has to be enabled with the @EMULATOR ON# Serial API call. The following steps emulates a real dive:

1. Turn on emulator mode by @EMULATOR ON# command
2. Switch DiveIno into Dive Mode
3. DiveIno will send the @START# command to start dive emulation
4. Periodically DiveIno issues a @GET# command in order to retrieve pressure and temperature information
5. The emulator sends back the requested temperature and pressure informations
6. Once the dive finished DiveIno will send the @STOP# command to the emulator. This will indicate the end of the dive emulation.
7. The emulator mode can be turned off with the @EMULATOR OFF# command

The table below demonstrates the Serial API calls during dive emulation:

Order	Sent by Emulator	Sent by DiveIno	Description
1.	@EMULATOR ON#		Turn on emulator mode
2.		@START#	Start the dive emulation
3.	2356.23, 22.3,	@GET#	Get the current pressure and temperature data of the dive profile
4.		@STOP#	Stop the dive emulation
5.	@EMULATOR OFF#		Turn off emulator mode

Replay mode commands

Dive emulation is a really handy feature, but sometimes it would be really good to be able to play back a particular dive on DiveIno in shorter time. For instance a 90 minutes dive can be played back in minutes. The replay mode can be used for that.

The typical dive replay flow looks like this:

1. Turn on replay mode with the @REPLAY ON# command
2. Switch DiveIno into Dive Mode
3. Send the following information to DiveIno:
   1. Pressure in millibar
   2. Depth in meter
   3. Dive duration in seconds
   4. Temperature in celsius
4. After the dive turn off replay mode with the @REPLAY OFF# command

The table below demonstrates the Serial API calls during dive in replay mode:

Order	Sent to DiveIno	Description
1.	@REPLAY ON#	Turn on replay mode
2.	1435, 4.2, 4, 15,	Send pressure, depth, duration and temperature information
3.	@REPLAY OFF#	Turn off replay mode

Difference

The main difference between emulator and replay modes is the duration of the dive. In emulator mode the simulated and the real dive duration is the same. In replay mode the simulated dive duration is significantly shorter that the real one.

The emulator mode can be considered as the same as the real dive, only the pressure information comes from a previously stored profile instead from the sensor.

The replay mode provides a quick and easy way to check decompression stops and algorithm performance during a dive.

Examples

The following sample interaction with DiveIno shows how the Serial API works in real life:

>>Send to COM9: "@version#"<<
@1.3.1#

>>Send to COM9: "@diag temp#"<<
@26.27#

>>Send to COM9: "@diag pres#"<<
@993.90#

>>Send to COM9: "@diag date#"<<
@2017-01-04 10:01:49#

>>Send to COM9: "@oxygen 0.32#"<<
SETTINGS - Saved to the SD Card.
OXYGEN - 0.32

>>Send to COM9: "@settings#"<<
@{
  "seaLevelPressure": 1.01320e3,
  "oxygenPercentage": 0.32,
  "soundEnabled": false,
  "isImperialUnits": false
}#

>>Send to COM9: "@logbook#"<<
@{
  "numberOfDives": 0,
  "loggedDiveHours": 0,
  "loggedDiveMinutes": 0,
  "maxDepth": 0.00,
  "lastDiveDate": "",
  "lastDiveTime": "",
  "numberOfStoredProfiles": 0
}#