openEMSstim

# The communication protocol 

To talk to the EMS device over bluetooth (or serial) you can use the following protocol. This is responsible for controlling the hardware inside the device (digital potentiometer, mosfets and optocouplers) to react to the commands you provide.

You can obviously create your own protocol, but we encourage you to re-use, re-mix, improve this one or see it as a starting point for something better.

## 1. Communication protocol: how a message is structured

A serial command (sent via USB or bluetooth) must look like this: 

			
| Command       | Values   | Sample  	| Description | 
| ------------- |:--------:| ---------:|------------:|
| Channel 		|0-1		|C0 		|Set channel 0 or 1|
| Intensity		|0-100 		|I56		|Set intensity in| 
| On-Time 		|1-int32 	|T20000 	|Set the on time in ms|
| Activate/Go	|G 			|G			|Activate the command|

## 2. Important facts about the protocol design

This protocol assumes you are always sending messages with a time in ms that the command is valid for. This allows some extra level of safety. Your host device (the ones that runs your application and talks via bluetooth to the EMS controller) can simply resend messages on a timely basis to make sure the commands are run all the time, appearing to be continuous. 

More detailed shown below at the example of one command. 

## 3. Exemplary command

For example, when the message “C0I100T1000G” is sent to the service, channel 0  (first channel) activates at full intensity for 1000 ms (1 second). Resending “G” activates the same channel with the previous parameters again. Each parameter can be changed individually. If a new “on-time” message is received while a channel is active, the new time will be updated even if it is shorter. For example, if the signal is on and the new time is set to 50 ms, it will deactivated after 50 ms.

A few more command examples:

1. "C1I100T1000G”: channel 1 activates at full intensity for 1000 ms (1 second).
2. "C1I0T50G”: channel 1 goes off for 50 milliseconds but stays off after too (because once a command is done the channel is off).
3. "C0I50T7000G”: channel 0 goes at 50% intensity for 7 seconds.

Notes about channel numbers: on the hardware, the channels are denoted as channel 0 (first channel) and channel 1 (second channel). So the protocol is C0 = Channel 1 (first channel), and C1 = Channel 2 (first channel). The APIs and code examples abstract this, and you can directly type ``ems_command(1,100,2000)`` (sends intensity 100 to channel 1 for 2 seconds) or ``ems_command(2,100,2000)`` (sends intensity 100 to channel 2 for 2 seconds).

## 4. What's the easiest way for me to generate commands?

### 4.1 over serial USB 
The simplest way is using one of our applications that functions over USB. For instance the python app [send_single_command.py](../apps/python/send_single_command.py) allows you to specify the command as channel+intensity+duration and will output the string needed.

### 4.2 over bluetooth
The simplest way is using the [openEMSstim-control app](../apps/android-apps/openEMSstim-control/) and it will print the generated commands to your console. To do this: open the debugger (Log console) on Android Studio, this way you can iteratively see how the commands are generated. 

### License and Liability

Please refer to the liability waiver (in documentation/liability_waiver.md).
Please refer to the license (in /license.md)