aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorlonkaars <loek@pipeframe.xyz>2022-10-30 16:52:29 +0100
committerlonkaars <loek@pipeframe.xyz>2022-10-30 16:52:29 +0100
commit64d742443bfacf5b1fad29f44642780b623f9a15 (patch)
tree176f2f65cdbfb13a4236e7964e21cb62e2d1e6c3
parent0c8e3c7e6cdc99a14b38edd747d07d7b03fb294c (diff)
add documentation in header files
-rw-r--r--shared/protocol.h2
-rw-r--r--shared/util.h2
-rw-r--r--stm32f091/server.h65
-rw-r--r--stm32f091/setup.h8
-rw-r--r--stm32f091/util.h3
5 files changed, 55 insertions, 25 deletions
diff --git a/shared/protocol.h b/shared/protocol.h
index 96c039a..e5ddf05 100644
--- a/shared/protocol.h
+++ b/shared/protocol.h
@@ -148,4 +148,6 @@ static ws_protocol_res_handler_t* g_ws_protocol_res_handlers[WS_PROTOCOL_CMD_AMO
[WS_PROTOCOL_CMD_LAST_RECORDS] = &ws_protocol_res_last_records,
};
+/** @brief return length of custom protocol header */
unsigned short ws_protocol_get_header_size(ws_s_protocol_res* response);
+
diff --git a/shared/util.h b/shared/util.h
index 94a3dfe..690a999 100644
--- a/shared/util.h
+++ b/shared/util.h
@@ -3,4 +3,6 @@
#define WS_MIN(a, b) (((a) < (b)) ? (a) : (b))
#define WS_MAX(a, b) (((a) > (b)) ? (a) : (b))
+/** @brief take the log base 16 of `x` */
unsigned int ws_log16(unsigned int x);
+
diff --git a/stm32f091/server.h b/stm32f091/server.h
index 07c49d9..ba92b78 100644
--- a/stm32f091/server.h
+++ b/stm32f091/server.h
@@ -4,6 +4,7 @@
#include <stdint.h>
#include <stdbool.h>
+/** @brief store kind of AT command response the server is expecting */
typedef enum {
WS_SERVER_LM_CMD_ECHO, /** @brief listen for echo of sent command */
WS_SERVER_LM_STATUS_CODE, /** @brief listen for busy, ERROR or OK */
@@ -12,39 +13,43 @@ typedef enum {
WS_SERVER_LM_CIPSEND_LISTENING, /** @brief AT+CIPSEND sent, now reading data */
} ws_e_server_listen_mode;
+/** @brief state machine for parsing +IPD command fields */
typedef enum {
WS_SERVER_CL_CHANNEL_ID, /** @brief listen channel id */
WS_SERVER_CL_DATA_LENGTH, /** @brief listen for data byte length */
WS_SERVER_CL_DATA_READ, /** @brief listen for data and pipe to ws_protocol_parse_req_byte */
} ws_e_channel_listen_mode;
+/** @brief AT command status codes */
typedef enum {
- WS_SERVER_RC_NONE = -1,
- WS_SERVER_RC_BUSY,
- WS_SERVER_RC_ERR,
- WS_SERVER_RC_OK,
+ WS_SERVER_RC_NONE = -1, /** @brief initial value */
+ WS_SERVER_RC_BUSY, /** @brief status code busy p... */
+ WS_SERVER_RC_ERR, /** @brief status code ERROR */
+ WS_SERVER_RC_OK, /** @brief status code OK */
} ws_e_server_response_code;
+/** @brief counters for byte-by-byte string comparison of AT response codes */
typedef struct {
- uint8_t s_ok; /** @brief status code OK */
- uint8_t s_error; /** @brief status code OK */
- uint8_t s_fail; /** @brief status code OK */
- uint8_t s_busy; /** @brief status code OK */
- uint8_t i_ipd; /** @brief idle +IPD, */
- uint8_t i_prompt; /** @brief idle > */
- uint8_t l_send_ok; /** @brief ipd listen SEND OK */
- uint8_t l_error; /** @brief ipd listen ERROR */
+ uint8_t s_ok; /** @brief counter for status code OK */
+ uint8_t s_error; /** @brief counter for status code OK */
+ uint8_t s_fail; /** @brief counter for status code OK */
+ uint8_t s_busy; /** @brief counter for status code OK */
+ uint8_t i_ipd; /** @brief counter for idle +IPD, */
+ uint8_t i_prompt; /** @brief counter for idle > */
+ uint8_t l_send_ok; /** @brief counter for ipd listen SEND OK */
+ uint8_t l_error; /** @brief counter for ipd listen ERROR */
} ws_s_server_parser_response_counter;
+/** @brief server parser statue struct */
typedef struct {
- ws_e_server_listen_mode mode;
- ws_e_server_response_code last_response;
- unsigned int current_channel;
- unsigned int channel_data_length;
- unsigned int channel_data_counter;
- ws_e_channel_listen_mode channel_listen_mode;
- bool channel_data_ignore;
- ws_s_server_parser_response_counter rc;
+ ws_e_server_listen_mode mode; /** @brief expected AT response kind */
+ ws_e_server_response_code last_response; /** @brief response code for last AT command */
+ unsigned int current_channel; /** @brief TCP channel for last +IPD command */
+ unsigned int channel_data_length; /** @brief data length for last +IPD command */
+ unsigned int channel_data_counter; /** @brief amount of parsed data bytes for last +IPD command */
+ ws_e_channel_listen_mode channel_listen_mode; /** @brief +IPD command parse state */
+ bool channel_data_ignore; /** @brief whether last TCP request should be ignored because it's too long */
+ ws_s_server_parser_response_counter rc; /** @brief response counters for byte-by-byte string comparison */
} ws_s_server_parser;
/** @brief global server parser struct */
@@ -62,11 +67,6 @@ extern ws_s_server_parser g_ws_server_parser;
*/
void ws_server_req_incoming(uint8_t* data, size_t size);
-// /** @brief send AT response header for incoming request on specific channel */
-// void ws_server_req_respond_start(unsigned int channel);
-// /** @brief send AT tcp close on specific channel */
-// void ws_server_req_respond_end(unsigned int channel);
-
/** @brief send data to esp, waiting until server returns to idle mode */
void ws_server_send(uint8_t* data, size_t size);
@@ -93,7 +93,22 @@ void ws_server_req_parse_byte(unsigned int channel, uint8_t byte, bool ignore);
*/
void ws_server_req_finish(unsigned int channel, bool ignore);
+/**
+ * @brief append data to the tx buffer for sending response in chunks
+ *
+ * the esp8266 becomes unreliable when sending large tcp responses, so this
+ * function buffers the complete response, and sends it in chunks broken up by
+ * a newline ('\n') character
+ *
+ * to send data buffered using this function, refer to
+ * `ws_server_buffer_request_chunk_send` and `ws_server_buffer_send_chunk`.
+ *
+ * @param data pointer to data array
+ * @param size size of data array
+ */
void ws_server_buffer_send_append(uint8_t* data, size_t size);
+/** @brief send AT+CIPSEND with size of next chunk to the esp8266 */
void ws_server_buffer_request_chunk_send();
+/** @brief send data chunk for last AT+CIPSEND command */
void ws_server_buffer_send_chunk();
diff --git a/stm32f091/setup.h b/stm32f091/setup.h
index d459635..2d34952 100644
--- a/stm32f091/setup.h
+++ b/stm32f091/setup.h
@@ -6,17 +6,25 @@
#include "consts.h"
+/** @brief glbal HAL i2c-1 state */
extern I2C_HandleTypeDef hi2c1;
+/** @brief glbal HAL uart-1 state */
extern UART_HandleTypeDef huart1;
+/** @brief glbal HAL uart-1 state */
extern UART_HandleTypeDef huart2;
+/** @brief glbal HAL DMA state for uart-1's RX channel */
extern DMA_HandleTypeDef hdma_usart1_rx;
+/** @brief glbal HAL DMA state for uart-1's TX channel */
extern DMA_HandleTypeDef hdma_usart1_tx;
+/** @brief "main" setup function */
void ws_io_setup();
+// required HAL setup functions
void NMI_Handler();
void HardFault_Handler();
void SysTick_Handler();
void HAL_MspInit();
void HAL_I2C_MspInit(I2C_HandleTypeDef* hi2c);
void HAL_UART_MspInit(UART_HandleTypeDef *huart);
+
diff --git a/stm32f091/util.h b/stm32f091/util.h
index 9c15f8b..100b877 100644
--- a/stm32f091/util.h
+++ b/stm32f091/util.h
@@ -34,6 +34,7 @@
#define WS_DBG_TTY_COLOR_TX WS_DBG_TTY_COLOR_GRN
#define WS_DBG_TTY_COLOR_RX WS_DBG_TTY_COLOR_RED
+// allow `debugger;` statement like in JS
#define debugger asm("nop")
// unused
@@ -43,12 +44,14 @@
// #define WS_DBG_TTY_COLOR_IPD_LISTENING WS_DBG_TTY_COLOR_GRN
// #define WS_DBG_TTY_COLOR_CIPSEND_LISTENING WS_DBG_TTY_COLOR_RED
+/** @brief `printf()` over uart2 (usb) */
#define ws_usb_printf(fmt, ...) { \
char temp[255]; \
snprintf(temp, 255, fmt, ##__VA_ARGS__); \
HAL_UART_Transmit(&huart2, (uint8_t*) temp, sizeof(char) * strlen(temp), HAL_MAX_DELAY); \
}
+/** @brief print VT100 escape code over uart2 to set tty color */
#define ws_dbg_set_usart2_tty_color(color) { \
uint8_t sgr[] = { 0x1b, 0x5b, 0x33 + (color > 7 ? 6 : 0), 0x30 + (color & 0b111), 0x6d }; \
HAL_UART_Transmit(&huart2, sgr, sizeof(sgr), 100); \