takeone-kicker/SIGNALS.md

# Kicker Signaling
details about communication protocol between mobile phone app and kicker

## How To Connect To KICKER ?
in order to connect to kicker, you need to enable ***Bluetooth*** connection. and try to connect via two methods

* Scan For Bluetooth Devices And Add Manually
* Scan A QR Code With JSON Content

### QR Code JSON Content
```
{"request":"pair_kicker","device-name":"KICKER","device-mac":"98:D3:31:60:4E:A5"}
```

### Fixed Messages, Responses, Commands
Here we will discuss all sorts of fixed commands, messages, responses - what do they do and what do they mean, and how to use them in our firmware. Ghassan Yusuf built this protocol carefully for high accuracy data arbitration.

#### Game Selection Indicators
When the user selects a game and the data is being sent to the kicker, the kicker confirms the selection and responses back with a message to indicate the game type selected.

*When counter game is selected*
```
{"gm":"COUNTER"}
```

*When time attack game is selected*
```
{"gm":"TIME ATTACK"}
```

*When reaction game is selected*
```
{"gm":"REACTION"}
```

*When decision game is selected*
```
{"gm":"DECISION"}
```

*When stamina game is selected*
```
{"gm":"STAMINA"}
```

#### Messages
These messages are for notifying the mobile device with the status of the events occurring within its firmware, like reporting back specific events.

*When you power on the first thing it does is to send the following signal informing the user that the kicker is on. (Note) at the moment of powering on the Bluetooth goes off to so its no longer connected this message will show on the serial terminal only.*
```
{"status":"POWER UP"}
```

*When the user sends a game selection or command, if the signal was recognized and understood by the firmware it send back the following response*
```
{"status":"OK"}
```

*When the user sends a game selection or command, if the signal JSON data get corrupted due to lack of memory or interference then it send back the following response*
```
{"status":"ERROR JSON"}
```

*When the user playes a game and the game ends because the user didnt cach up with the limits he set or the user send a quit command {"cm":"STOP"}, Then it send the following command - it means you quit the game or you could not keep up with the game and ended in loss*
```
{"status":"GAME OVER"}
```

*When the user sends a JSON formated signal in game selection routine, if the signal was not recognized or not understood by the firmware it send back the following response*
```
{"status":"UNKNOWN GAME"}
```

#### Commands

```
{"cm":"START"}
```

```
{"cm":"RESET"}
```

```
{"cm":"STOP"}
```

<HR>

## Games Selection
In order to select a specific game, the kicker should be not engaged with any running game, Then only it can receive game selection signal and pass the game parameters.

<HR>

### Counter Game
* Open Counter
* Close Counter With Count Trials

#### The JSON Format (setting is a nested JSON)
```
{"gm":"ct", "set": {"le":true, "lm": 10}}

ct  : Kick Counter Game
le  : Previous Games Results (Action One Result, Action Two Result)
lm  : Kick Limit Amount
```
This mean that the player wants to play a counter game with limit feature enabled, limited number of kicks are 10, then the game stops counting.

#### Strike Signal
```
{"ct":1,"st":5.215}

ct  : Kick Count
st  : Time Of The Kick In Milliseconds
```

#### Result Calculations
```
number of kicks = maximum number of kicks the user made on the target
```

<HR>

### Time Attack Game
Open Kick Counter Limited By Time Window
Closed Kick Counter Limited By Trials Count Or Time Window

#### The JSON Format (setting is a nested JSON)
```
{"gm":"ta", "set": {"tm": 60, "lm": 10, "le": true}}

ta  : Decision Time Measurement Game
tm  : Game Play Time
lm  : Kick Trial Amount
le  : Enable End Game When Limits It Meet
```
This mean that the player wants to play a Time Attack game for 60s and enabled kick limits to 200 kicks.

#### Strike Signal
```
{"tm":5,"ct":2,"st":0.289,"dl":0.289}

tm  : Count Down Display Time (in Seconds)
ct  : Kick Count (Number Of Kicks)
st  : Time Of Each Strike (In Milliseconds)
dl  : Diviation Between Kicks (In Milliseconds)
```

#### Result Calculations
```
timeattack = (number of kicks)/(time taken to finish the game) = Kicks Per Second
```

<HR>

### Reaction Game
Open Reaction Game With No Trials Limit
Open Reaction Game With No Trials Limit With Time Limit
Closed Reaction Game With Trials Limit Without Time Limit

#### The JSON Format (setting is a nested JSON)
```
{"gm":"ra", "set": {"lm": 10, "mn": 1, "mx": 3}}

ra  : Reaction/Reflex Measurement Game
lm  : Kick Trial Amount
mn  : Minimum Delay Between Signals
mx  : Maximum Delay Between Signals
```
This mean that the player wants to play a reaction game for a strike named “Front Kick” with enables trials of 10 kicks with delay spacing between trials (1s up to 3s) without time limits.

#### Strike Signal
```
{"ct":3,"pw":65467,"sd":3,"re":0.005}

ct  : kick count
pw  : kick power
sd  : sconds delay between light trigger
re  : reaction time in milli seconds
```

#### Result Calculations
```
avarage reaction=  (sum of all reaction time (sum re))/(total number of trials (max⁡〖ct)〗 )=milli seconds
```

<HR>

### Decision Making Game
( This game is locked & unlock only if you have records with different kinds of reaction trials with different actions )
Closed Decision Making Game With Trials Limit
Closed Decision Making Game With Time Limit

#### The JSON Format (setting is a nested JSON with action array)
```
{"gm":"de", "set":{“pr”: [<action1>, <action2>], "lm": 10, "mn": 1, "mx": 3}}

de  : Decision Time Measurement Game
pr  : Previous Games Results (Action One Result, Action Two Result)
lm  : Kick Trial Amount
mn  : Minimum Delay Between Signals
mx  : Maximum Delay Between Signals
```
This mean that the player wants to play a reaction game for a strike named “Front Kick” with enables trials of 10 kicks with delay spacing between trials (1s up to 3s) without time limits.

<HR>

### Stamina Measurement Game
* Open stamina measurement
* Closed stamina measurement to Time Limit

#### The JSON Format (setting is a nested JSON with action array)
```
{"game":"st", "set":{“le”: true, “lm”: 20, “tm”: 30, "mx":120 }}

st  : Stamina Measurement Game
le  : Enable Limit Number Of Kicks
lm  : Kick Limit Amount
tm  : Game Time In Seconds
mx  : Max Strike Deviation in Milliseconds (Spacing Between Strikes)
```
This mean that the player wants to play a stamina game for a strike named “Front Kick” with enables time limit of 120s.