uploading kicker terminology

SIGNALS.md

@@ -0,0 +1,217 @@
+# Kicker Signaling
+details about communication protocol between mobile phone app and kicker
+<hr>
+
+## 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 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"}
+```
+
+
+```
+{"status":"TARGET MEET"}
+```
+
+```
+{"status":"GAME OVER"}
+```
+
+```
+{"status":"TIME OVER"}
+```
+
+```
+{"status":"UNKNOWN GAME"}
+```
+
+#### Commands
+
+```
+{"cm":"START"}
+```
+
+```
+{"cm":"RESET"}
+```
+
+```
+{"cm":"STOP"}
+```
+
+```
+{"cm":"EXIT"}
+```
+
+<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}
+```
+
+#### Result Calculations
+```
+number of kicks = (max⁡ct) = kicks
+```
+
+<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}
+```
+
+#### Result Calculations
+```
+timeattack = (number of kicks (max⁡ct))/(total time in (max⁡tm)) = ks
+```
+
+<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}
+```
+
+#### 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.