From 5237c6464de96d02ecfbad09194f065c6ee71c60 Mon Sep 17 00:00:00 2001
From: Gabriel Nascimento <gaabrielns@gmail.com>
Date: Wed, 6 Jun 2018 08:21:20 -0300
Subject: [PATCH] [#1] First protocol suggestion

---
 Communication/sloth_protocol.h  | 55 +++++++++++++++++++++++++++++++++
 Communication/sloth_protocol.md | 46 ++++++++++++++++++++++-----
 2 files changed, 93 insertions(+), 8 deletions(-)
 create mode 100644 Communication/sloth_protocol.h

diff --git a/Communication/sloth_protocol.h b/Communication/sloth_protocol.h
new file mode 100644
index 0000000..931d5ca
--- /dev/null
+++ b/Communication/sloth_protocol.h
@@ -0,0 +1,55 @@
+/* Adding an offset to enums cause it to start
+   with a value that represents an ASCII character,
+   so the communication is readable through serial terminal */
+#define ENUM_OFFSET	0x21 // Adding an offset to enums
+
+typedef enum sloth_opcode
+{
+	SLOTH_OPCODE_INC = ENUM_OFFSET,
+	SLOTH_OPCODE_DEC,
+	SLOTH_OPCODE_SET,
+	SLOTH_OPCODE_CONFIG,
+	SLOTH_OPCODE_START,
+	SLOTH_OPCODE_STOP,
+	SLOTH_OPCODE_EOF  //!< Marks the largest value for opcode
+}sloth_opcode_t;
+
+// for now, maybe status isn't a big deal
+#if 0
+typedef enum sloth_op_status
+{
+	SLOTH_STATUS_SUCCESS = ENUM_OFFSET,
+	SLOTH_STATUS_BUSY,
+	SLOTH_STATUS_INVALID_PARAM,
+	SLOTH_STATUS_ERROR,
+	SLOTH_STATUS_EOF
+}sloth_op_status_t;
+#endif
+
+typedef enum sloth_ctrl_var
+{
+	SLOT_VAR_KP = ENUM_OFFSET,
+	SLOT_VAR_KI,
+	SLOT_VAR_KD,
+	SLOT_VAR_EOF,
+}sloth_ctrl_var_t
+
+typedef struct sloth_config
+{
+	uint32_t kp;
+	uint32_t ki;
+	uint32_t kd;
+}sloth_config_t
+
+/*  Defining a type for the structure of a command. */
+typedef struct sloth_cmd
+{
+	sloth_opcode_t 		cmd;
+	// sloth_op_status_t 	status;	// for now, maybe status isn't a big deal
+	union
+	{
+		sloth_ctrl_var_t variable;
+		sloth_config_t	 config;
+	}
+	// uint16_t crc; // for now we dont need CRC
+}slot_cmd_t;
\ No newline at end of file
diff --git a/Communication/sloth_protocol.md b/Communication/sloth_protocol.md
index 033634e..65e872d 100644
--- a/Communication/sloth_protocol.md
+++ b/Communication/sloth_protocol.md
@@ -15,23 +15,51 @@ Os comandos podem ter basicamente 5 componentes essenciais, listados abaixo
 
 ## Lista de comandos
 
-|Comando | OPCODE | Descrição|
-| -----  | ------ | ------ |
-| Increment | | Incrementa uma variável utilizada no controle (KP, KI, KD, etc) |
-| Decrement | | Decrementa a mesma coisa|
-| Set | | Define um valor específico para as variáveis utilizadas no controle |
-| Full config | | Define um conjunto de valores: kp, ki e kd ao mesmo tempo |
-| Start | | Inicia algum ciclo no robô |
-| Stop | | Para o que o robô está fazendo |
+|Comando | OPCODE | TAG| Descrição|
+| -----  | ------ | ------ | --- |
+| Increment | 0x21 | SLOTH_OPCODE_INC | Incrementa uma variável utilizada no controle (KP, KI, KD, etc) |
+| Decrement | 0x22 | SLOTH_OPCODE_DEC | Decrementa a mesma coisa|
+| Set | 0x23 | SLOTH_OPCODE_SET | Define um valor específico para as variáveis utilizadas no controle |
+| Full config | 0x24 | SLOTH_OPCODE_CONFIG | Define um conjunto de valores: kp, ki e kd ao mesmo tempo |
+| Start | 0x25 | SLOTH_OPCODE_START | Inicia algum ciclo no robô |
+| Stop | 0x26 | SLOTH_OPCODE_STOP | Para o que o robô está fazendo |
+
+## Definições de Payloads
+
+### Sloth Control Var
+
+Os comandos: Increment, Decrement e Set possuem um payload determinado "variable", uma estrutura de dados que possui um código pra variável e um valor, que define qual variável ele irá modificar. Atualmente, há uma lista com as seguintes variáveis identificadas na lista a seguir:
+
+| Variável | Código | Tag |
+| -------  |  ----- | --- |
+| KP 	| 0x21 | SLOT_VAR_KP |
+| KI 	| 0x22 | SLOT_VAR_KI |
+| KD 	| 0x23 | SLOT_VAR_KD |
+
+Exemplos de comandos codificados
+
+| Comando | Byte array | obs|
+| ----    | ---- | -- |
+| Inc KP | 0x02 0x21 0x21 | Observe que o campo "value" não é preenchido/transmitido |
+| Dec KP | 0x02 0x22 0x21 | Observe que o campo "value" não é preenchido/transmitido |
+| Dec KD | 0x02 0x22 0x23 | Observe que o campo "value" não é preenchido/transmitido |
+| Set KI | 0x06 0x23 0x22 0x00 0x00 0x25 0x31 | Depois temos que ver como fica o endian disso aqui! |
+| Set KD | 0x06 0x23 0x23 0x00 0x00 0x02 0x15 | Depois temos que ver como fica o endian disso aqui! |
+
+### Config
+
+O comando de configuração receve uma estrutura de dados do tipo "slot_config_t" que possui valores definidos para kp, ki e kd.
 
 ### Exemplo
 Os comandos Increment e Decrement podem possuir o seguinte payload: KP, KI ou KD. Numa "metalinguagem" o comando ficaria algo do tipo (excluindo crc):
 
 Requisição:
+
 |2 | Increment | KP |
 | -----  | ------ | ------ |
 
 Resposta:
+
 |2 | Increment | SUCCESS |
 | -----  | ------ | ------ |
 
@@ -39,10 +67,12 @@ Resposta:
 O comando Set poderia ter um conjunto de argumentos:
 
 Requisição:
+
 |4 | Set | KP Value | KI Value | KD Value |
 | -----  | -- | ---- | --- | --- |
 
 Resposta:
+
 |2 | Set | SUCCESS |
 | -----  | ------ | ------ |