openEMSstim

# 1. Applications & APIs

## 1.1. Android Apps

We provide one simple android app that controls up to two channels of your EMS device, i.e., controls the two channels available in one openEMSstim board. 

Here's a few screenshots that illustrate how the application works:


## 1.2. Unity3D Plugin/Scene/Demo/Asset

We provide you with a Unity Scene that features code to send commands to the openEMSstim board. Here's the Unity controller that handles the EMS communication: 

 				 		
# 2. 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 potentciometer, 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.

## 2.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.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. 

## 2.3. Exemplary command

For example, when the message “C0I100T1000G” is sent to the service, channel 0 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.

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

Simply use the android app supplied here in this repository and print out the generated commands to your console (e.g., while your android phone is connected to the computer for debug via USB).  This way you can iteratively see how the commands are generated. 

## 3. Next version of the protocol

Right now, the protocol is the same as on the board by the original authors. We plan to simplify it soon. The plan is:

1. command generation is handled by a function, never by raw text
2. there will be no time expiration for a command
3. commands will be shorter, here's a preview (work in progress):

| Command       | Values   | Sample  	| Description | Lenght (bits) | 
| ------------- |:--------:| ---------:|------------:|------------:|
| Channel 		|0-1		|0  		|Set channel 0 or 1| 1 | 
| Intensity		|0-100 		|100		|Set intensity in steps of digipot | ? |  
| Ack needed?   |0-1 (N/Y) 	|0			|Writes back via the BT channel an ACK| 1 |
| Checksum	    |       	|0			|(Checksum of Channel + Intensity + Ack Needed) modulus 8| ? |  

**Why: ** Overall this simplifies the protocol, and generates a smaller payload too. The programmer must keep an eye for commands arriving/etc. Because the time-expiration will not be per command, it can be added to the device directly or on top by adding a "keep alive" protocol. 

### License and Liability

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