Ondřej Hruška / ESPTerm

Support library for the ESP8266 Wireless Terminal. Can also be used for communicating with any VT100-compatible terminal.

espterm.hpp@4:294e8f53ebcd, 2017-03-19 (annotated)

Committer:
MightyPork
Date:
Sun Mar 19 17:19:16 2017 +0000
Revision:
4:294e8f53ebcd
Parent:
3:1114012184bf
Child:
5:7379bd37f3e2
Added bunch of new features and a parser

Who changed what in which revision?

UserRevisionLine numberNew contents of line
MightyPork 0:20fb68233f89 1 #ifndef ESPTERM_H
MightyPork 0:20fb68233f89 2 #define ESPTERM_H
MightyPork 0:20fb68233f89 3 #include "mbed.h"
MightyPork 0:20fb68233f89 4
MightyPork 3:1114012184bf 5 /*
MightyPork 3:1114012184bf 6 * ESP8266 Wireless Terminal interfacing library
MightyPork 3:1114012184bf 7 * ---------------------------------------------
MightyPork 3:1114012184bf 8 *
MightyPork 3:1114012184bf 9 * Tested with ESP firmware v0.5.4
MightyPork 3:1114012184bf 10 *
MightyPork 3:1114012184bf 11 * This library provides simplified
MightyPork 1:09dfc9fd55f4 12 */
MightyPork 4:294e8f53ebcd 13
MightyPork 4:294e8f53ebcd 14 // Max nr of CSI parameters
MightyPork 4:294e8f53ebcd 15 #define CSI_N_MAX 3
MightyPork 4:294e8f53ebcd 16 #define OSC_BUF_LEN 16
MightyPork 1:09dfc9fd55f4 17
MightyPork 1:09dfc9fd55f4 18 /**
MightyPork 1:09dfc9fd55f4 19 * ESP8266 Wireless Terminal interface
MightyPork 0:20fb68233f89 20 *
MightyPork 1:09dfc9fd55f4 21 * Can also be used for sending ANSI sequences to a regular serial terminal
MightyPork 0:20fb68233f89 22 */
MightyPork 1:09dfc9fd55f4 23 class ESPTerm
MightyPork 1:09dfc9fd55f4 24 {
MightyPork 4:294e8f53ebcd 25 /**
MightyPork 4:294e8f53ebcd 26 * Status flag set by the rx handler when device responds with "device OK".
MightyPork 4:294e8f53ebcd 27 * Cleared before sending Device Status Request.
MightyPork 4:294e8f53ebcd 28 */
MightyPork 4:294e8f53ebcd 29 bool device_ok;
MightyPork 4:294e8f53ebcd 30
MightyPork 4:294e8f53ebcd 31
MightyPork 4:294e8f53ebcd 32 /** Serial comm used to talk to the ESP */
MightyPork 0:20fb68233f89 33 Serial* ser;
MightyPork 0:20fb68233f89 34
MightyPork 4:294e8f53ebcd 35
MightyPork 4:294e8f53ebcd 36 /** Internal init func, called from constructor */
MightyPork 4:294e8f53ebcd 37 void init(Serial* ser);
MightyPork 4:294e8f53ebcd 38
MightyPork 4:294e8f53ebcd 39
MightyPork 4:294e8f53ebcd 40 /** Internal rxchar handler with parser */
MightyPork 4:294e8f53ebcd 41 void ser_rx_char(void);
MightyPork 4:294e8f53ebcd 42
MightyPork 4:294e8f53ebcd 43 // ---- Ragel parser variables ----
MightyPork 4:294e8f53ebcd 44 int cs;
MightyPork 4:294e8f53ebcd 45
MightyPork 4:294e8f53ebcd 46 // The CSI code is built here
MightyPork 4:294e8f53ebcd 47 char csi_leading; //!< Leading char, 0 if none
MightyPork 4:294e8f53ebcd 48 int csi_ni; //!< Number of the active digit
MightyPork 4:294e8f53ebcd 49 int csi_n[CSI_N_MAX]; //!< Param digits
MightyPork 4:294e8f53ebcd 50 char csi_char; //!< CSI action char (end)
MightyPork 4:294e8f53ebcd 51
MightyPork 4:294e8f53ebcd 52 char osc_buff[OSC_BUF_LEN];
MightyPork 4:294e8f53ebcd 53 int osc_i;
MightyPork 4:294e8f53ebcd 54
MightyPork 4:294e8f53ebcd 55 // Ragel parser funcs
MightyPork 4:294e8f53ebcd 56 void ansi_parser(const char *newdata, size_t len);
MightyPork 4:294e8f53ebcd 57 void apars_handle_plainchar(char c);
MightyPork 4:294e8f53ebcd 58 void apars_handle_csi(char lead, const int* nums, char keychar);
MightyPork 4:294e8f53ebcd 59 void apars_handle_osc(const char *c);
MightyPork 4:294e8f53ebcd 60 void apars_handle_badseq(void);
MightyPork 4:294e8f53ebcd 61
MightyPork 4:294e8f53ebcd 62
MightyPork 4:294e8f53ebcd 63 public:
MightyPork 4:294e8f53ebcd 64
MightyPork 3:1114012184bf 65 /**
MightyPork 3:1114012184bf 66 * ANSI colors supported by the ESP Terminal
MightyPork 3:1114012184bf 67 */
MightyPork 3:1114012184bf 68 enum Color {
MightyPork 3:1114012184bf 69 BLACK = 0, RED, GREEN, YELLOW, BLUE, PURPLE, CYAN, GRAY_LT,
MightyPork 3:1114012184bf 70 GRAY, RED_LT, GREEN_LT, YELLOW_LT, BLUE_LT, PURPLE_LT, CYAN_LT, WHITE,
MightyPork 3:1114012184bf 71
MightyPork 3:1114012184bf 72 // aliases
MightyPork 3:1114012184bf 73 RED_DK=1, GREEN_DK=2, YELLOW_DK=3, BLUE_DK=4, PURPLE_DK=5, CYAN_DK=6, SILVER=7,
MightyPork 3:1114012184bf 74 };
MightyPork 3:1114012184bf 75
MightyPork 3:1114012184bf 76
MightyPork 3:1114012184bf 77 /**
MightyPork 3:1114012184bf 78 * Argument for screen or line clear commands
MightyPork 3:1114012184bf 79 */
MightyPork 3:1114012184bf 80 enum ClearMode {
MightyPork 3:1114012184bf 81 CLEAR_TO_CURSOR = 0,
MightyPork 4:294e8f53ebcd 82 CLEAR_FROM_CURSOR = 1,
MightyPork 3:1114012184bf 83 CLEAR_ALL = 2,
MightyPork 3:1114012184bf 84 };
MightyPork 3:1114012184bf 85
MightyPork 4:294e8f53ebcd 86
MightyPork 4:294e8f53ebcd 87 enum CtlKey {
MightyPork 4:294e8f53ebcd 88 KEY_LEFT=0, KEY_RIGHT, KEY_UP, KEY_DOWN
MightyPork 4:294e8f53ebcd 89 };
MightyPork 4:294e8f53ebcd 90
MightyPork 4:294e8f53ebcd 91
MightyPork 4:294e8f53ebcd 92 /** Fired when user taps the screen at the given coords */
MightyPork 4:294e8f53ebcd 93 void (*on_mouse_click)(int row, int col);
MightyPork 4:294e8f53ebcd 94
MightyPork 4:294e8f53ebcd 95
MightyPork 4:294e8f53ebcd 96 /** Fired when the user presses one of the blue buttons (index is 1 thru 5) */
MightyPork 4:294e8f53ebcd 97 void (*on_button)(int index);
MightyPork 4:294e8f53ebcd 98
MightyPork 4:294e8f53ebcd 99
MightyPork 4:294e8f53ebcd 100 /** Fired on rx of the "ESP reset notification" byte */
MightyPork 4:294e8f53ebcd 101 void (*on_esp_reset)(void);
MightyPork 4:294e8f53ebcd 102
MightyPork 4:294e8f53ebcd 103
MightyPork 4:294e8f53ebcd 104 /** Fired on each received plain character */
MightyPork 4:294e8f53ebcd 105 void (*on_char_rx)(char c);
MightyPork 4:294e8f53ebcd 106
MightyPork 4:294e8f53ebcd 107
MightyPork 4:294e8f53ebcd 108 /** Fired on each key press (keyboard arrows etc) */
MightyPork 4:294e8f53ebcd 109 void (*on_key_press)(CtlKey key);
MightyPork 4:294e8f53ebcd 110
MightyPork 4:294e8f53ebcd 111
MightyPork 4:294e8f53ebcd 112 /** Handle generic OSC command (may be used in the future) */
MightyPork 4:294e8f53ebcd 113 void (*on_osc_rx)(const char *str);
MightyPork 4:294e8f53ebcd 114
MightyPork 3:1114012184bf 115
MightyPork 0:20fb68233f89 116 /**
MightyPork 1:09dfc9fd55f4 117 * @brief Create a terminal instance from already initialized serial port
MightyPork 0:20fb68233f89 118 *
MightyPork 0:20fb68233f89 119 * Example:
MightyPork 3:1114012184bf 120 * Serial ser(PA_2, PA_3, 115200); // eg. for STM32F042
MightyPork 0:20fb68233f89 121 * ESPTerm term(&ser);
MightyPork 0:20fb68233f89 122 */
MightyPork 0:20fb68233f89 123 ESPTerm(Serial *s);
MightyPork 1:09dfc9fd55f4 124
MightyPork 4:294e8f53ebcd 125
MightyPork 4:294e8f53ebcd 126 /**
MightyPork 4:294e8f53ebcd 127 * @brief Create a terminal instance with given params
MightyPork 4:294e8f53ebcd 128 */
MightyPork 4:294e8f53ebcd 129 ESPTerm(PinName txPin, PinName rxPin, int baud=115200);
MightyPork 4:294e8f53ebcd 130
MightyPork 4:294e8f53ebcd 131
MightyPork 4:294e8f53ebcd 132 /**
MightyPork 4:294e8f53ebcd 133 * @brief Create a terminal instance with given params & 115200 baud
MightyPork 4:294e8f53ebcd 134 */
MightyPork 4:294e8f53ebcd 135 //ESPTerm(PinName txPin, PinName rxPin);
MightyPork 4:294e8f53ebcd 136
MightyPork 1:09dfc9fd55f4 137
MightyPork 1:09dfc9fd55f4 138 /**
MightyPork 1:09dfc9fd55f4 139 * @brief Create with Serial at (PA_2, PA_3, 115200)
MightyPork 1:09dfc9fd55f4 140 */
MightyPork 1:09dfc9fd55f4 141 ESPTerm(void);
MightyPork 1:09dfc9fd55f4 142
MightyPork 1:09dfc9fd55f4 143
MightyPork 4:294e8f53ebcd 144 // ----- Printing -----
MightyPork 4:294e8f53ebcd 145
MightyPork 4:294e8f53ebcd 146
MightyPork 1:09dfc9fd55f4 147 /**
MightyPork 1:09dfc9fd55f4 148 * @brief printf() over the Serial
MightyPork 1:09dfc9fd55f4 149 *
MightyPork 1:09dfc9fd55f4 150 * Use for raw strings without formatting, or with custom escape sequences.
MightyPork 1:09dfc9fd55f4 151 */
MightyPork 1:09dfc9fd55f4 152 int printf(const char *fmt, ...);
MightyPork 1:09dfc9fd55f4 153
MightyPork 1:09dfc9fd55f4 154
MightyPork 1:09dfc9fd55f4 155 /**
MightyPork 1:09dfc9fd55f4 156 * @brief Alias for printf()
MightyPork 1:09dfc9fd55f4 157 */
MightyPork 1:09dfc9fd55f4 158 int print(const char *fmt, ...);
MightyPork 1:09dfc9fd55f4 159
MightyPork 1:09dfc9fd55f4 160
MightyPork 1:09dfc9fd55f4 161 /**
MightyPork 3:1114012184bf 162 * @brief Print with no args
MightyPork 3:1114012184bf 163 */
MightyPork 4:294e8f53ebcd 164 int puts(const char *str)
MightyPork 4:294e8f53ebcd 165 {
MightyPork 4:294e8f53ebcd 166 return ser->puts(str);
MightyPork 4:294e8f53ebcd 167 }
MightyPork 4:294e8f53ebcd 168
MightyPork 4:294e8f53ebcd 169
MightyPork 4:294e8f53ebcd 170 /**
MightyPork 4:294e8f53ebcd 171 * @brief Print a single char
MightyPork 4:294e8f53ebcd 172 */
MightyPork 4:294e8f53ebcd 173 void putc(const char c)
MightyPork 4:294e8f53ebcd 174 {
MightyPork 4:294e8f53ebcd 175 ser->putc(c);
MightyPork 4:294e8f53ebcd 176 }
MightyPork 3:1114012184bf 177
MightyPork 3:1114012184bf 178
MightyPork 3:1114012184bf 179 /**
MightyPork 2:f9f27e2b64a7 180 * printf() over the Serial, followed by a newline (\\r\\n)
MightyPork 1:09dfc9fd55f4 181 *
MightyPork 1:09dfc9fd55f4 182 * Use for raw strings without formatting, or with custom escape sequences.
MightyPork 1:09dfc9fd55f4 183 * Especially useful for log messages, automatically terminating the line.
MightyPork 1:09dfc9fd55f4 184 */
MightyPork 1:09dfc9fd55f4 185 int println(const char *fmt, ...);
MightyPork 1:09dfc9fd55f4 186
MightyPork 1:09dfc9fd55f4 187
MightyPork 4:294e8f53ebcd 188 // ----- Colors -----
MightyPork 4:294e8f53ebcd 189
MightyPork 4:294e8f53ebcd 190
MightyPork 1:09dfc9fd55f4 191 /**
MightyPork 1:09dfc9fd55f4 192 * @brief Set foreground text color
MightyPork 1:09dfc9fd55f4 193 * @param c - color
MightyPork 1:09dfc9fd55f4 194 */
MightyPork 3:1114012184bf 195 void fg(Color c);
MightyPork 1:09dfc9fd55f4 196
MightyPork 1:09dfc9fd55f4 197
MightyPork 1:09dfc9fd55f4 198 /**
MightyPork 1:09dfc9fd55f4 199 * @brief Set background text color
MightyPork 1:09dfc9fd55f4 200 * @param c - color
MightyPork 1:09dfc9fd55f4 201 */
MightyPork 3:1114012184bf 202 void bg(Color c);
MightyPork 1:09dfc9fd55f4 203
MightyPork 1:09dfc9fd55f4 204
MightyPork 1:09dfc9fd55f4 205 /**
MightyPork 1:09dfc9fd55f4 206 * @brief Set both text colors
MightyPork 1:09dfc9fd55f4 207 * @param fg - foregorund color
MightyPork 1:09dfc9fd55f4 208 * @param bg - background color
MightyPork 1:09dfc9fd55f4 209 */
MightyPork 4:294e8f53ebcd 210 void colors(Color fg, Color bg)
MightyPork 4:294e8f53ebcd 211 {
MightyPork 4:294e8f53ebcd 212 this->fg(fg);
MightyPork 4:294e8f53ebcd 213 this->bg(bg);
MightyPork 4:294e8f53ebcd 214 }
MightyPork 1:09dfc9fd55f4 215
MightyPork 1:09dfc9fd55f4 216
MightyPork 1:09dfc9fd55f4 217 /**
MightyPork 2:f9f27e2b64a7 218 * @brief Send \\e[0m - reset all attributes
MightyPork 1:09dfc9fd55f4 219 */
MightyPork 1:09dfc9fd55f4 220 void reset_attribs(void);
MightyPork 1:09dfc9fd55f4 221
MightyPork 1:09dfc9fd55f4 222
MightyPork 1:09dfc9fd55f4 223 /**
MightyPork 1:09dfc9fd55f4 224 * @brief Reset all attributes (alias)
MightyPork 1:09dfc9fd55f4 225 */
MightyPork 4:294e8f53ebcd 226 void rst(void)
MightyPork 4:294e8f53ebcd 227 {
MightyPork 4:294e8f53ebcd 228 this->reset_attribs();
MightyPork 4:294e8f53ebcd 229 }
MightyPork 4:294e8f53ebcd 230
MightyPork 4:294e8f53ebcd 231
MightyPork 4:294e8f53ebcd 232 // ----- Cursor & clearing -----
MightyPork 1:09dfc9fd55f4 233
MightyPork 1:09dfc9fd55f4 234
MightyPork 1:09dfc9fd55f4 235 /**
MightyPork 1:09dfc9fd55f4 236 * @brief Move cursor to a given position
MightyPork 1:09dfc9fd55f4 237 *
MightyPork 1:09dfc9fd55f4 238 * Screen coordinates are 1-based, starting left-top,
MightyPork 1:09dfc9fd55f4 239 * growing down and right.
MightyPork 1:09dfc9fd55f4 240 *
MightyPork 1:09dfc9fd55f4 241 * @param y - row
MightyPork 1:09dfc9fd55f4 242 * @param x - column
MightyPork 1:09dfc9fd55f4 243 */
MightyPork 1:09dfc9fd55f4 244 void go_to(int y, int x);
MightyPork 1:09dfc9fd55f4 245
MightyPork 1:09dfc9fd55f4 246
MightyPork 1:09dfc9fd55f4 247 /**
MightyPork 1:09dfc9fd55f4 248 * @brief Clear screen
MightyPork 1:09dfc9fd55f4 249 *
MightyPork 1:09dfc9fd55f4 250 * Replace part of the screen with spaces (ASCII 32) of the currently
MightyPork 1:09dfc9fd55f4 251 * selected foregorund and background colors.
MightyPork 1:09dfc9fd55f4 252 *
MightyPork 1:09dfc9fd55f4 253 * @param mode - what to clear: part or all
MightyPork 1:09dfc9fd55f4 254 */
MightyPork 1:09dfc9fd55f4 255 void clear_screen(ClearMode mode);
MightyPork 1:09dfc9fd55f4 256
MightyPork 1:09dfc9fd55f4 257
MightyPork 1:09dfc9fd55f4 258 /**
MightyPork 1:09dfc9fd55f4 259 * @brief Clear in line
MightyPork 1:09dfc9fd55f4 260 *
MightyPork 1:09dfc9fd55f4 261 * Replace part of the current line with spaces (ASCII 32) of the
MightyPork 1:09dfc9fd55f4 262 * currently selected foregorund and background colors.
MightyPork 1:09dfc9fd55f4 263 *
MightyPork 1:09dfc9fd55f4 264 * @param mode - what to clear: part or all
MightyPork 1:09dfc9fd55f4 265 */
MightyPork 1:09dfc9fd55f4 266 void clear_line(ClearMode mode);
MightyPork 1:09dfc9fd55f4 267
MightyPork 1:09dfc9fd55f4 268
MightyPork 1:09dfc9fd55f4 269 /**
MightyPork 1:09dfc9fd55f4 270 * @brief Clear the whole screen and move cursor to 1,1
MightyPork 1:09dfc9fd55f4 271 */
MightyPork 1:09dfc9fd55f4 272 void screen_reset(void);
MightyPork 1:09dfc9fd55f4 273
MightyPork 1:09dfc9fd55f4 274
MightyPork 1:09dfc9fd55f4 275 /**
MightyPork 1:09dfc9fd55f4 276 * @brief Set cursor visibility
MightyPork 1:09dfc9fd55f4 277 *
MightyPork 1:09dfc9fd55f4 278 * If hidden, there will be no blinking square on the screen,
MightyPork 1:09dfc9fd55f4 279 * but the cursor still works (ie. go_to works).
MightyPork 1:09dfc9fd55f4 280 *
MightyPork 1:09dfc9fd55f4 281 * Hiding the cursor is useful for ASCII-art GUIs (dialog boxes etc)
MightyPork 1:09dfc9fd55f4 282 */
MightyPork 1:09dfc9fd55f4 283 void show_cursor(bool yes);
MightyPork 1:09dfc9fd55f4 284
MightyPork 1:09dfc9fd55f4 285
MightyPork 4:294e8f53ebcd 286 // ----- System cmds -----
MightyPork 4:294e8f53ebcd 287
MightyPork 4:294e8f53ebcd 288
MightyPork 1:09dfc9fd55f4 289 /**
MightyPork 1:09dfc9fd55f4 290 * @brief Perform a factory reset of the ESP Terminal
MightyPork 1:09dfc9fd55f4 291 *
MightyPork 1:09dfc9fd55f4 292 * This clears any saved WiFi config, restores the default AP name
MightyPork 1:09dfc9fd55f4 293 * and switches to AP mode. The module will reset itself.
MightyPork 1:09dfc9fd55f4 294 *
MightyPork 1:09dfc9fd55f4 295 * Expect some ASCII output from the module (and a burst of garbage
MightyPork 1:09dfc9fd55f4 296 * during the reset).
MightyPork 1:09dfc9fd55f4 297 */
MightyPork 1:09dfc9fd55f4 298 void factory_reset(void);
MightyPork 1:09dfc9fd55f4 299
MightyPork 1:09dfc9fd55f4 300
MightyPork 1:09dfc9fd55f4 301 /**
MightyPork 1:09dfc9fd55f4 302 * @brief Set screen size
MightyPork 1:09dfc9fd55f4 303 *
MightyPork 1:09dfc9fd55f4 304 * The total number of characters (rows*cols) is limited by the Terminal
MightyPork 1:09dfc9fd55f4 305 * firmware, at v0.5.2 that is 2000 characters (25x80)
MightyPork 1:09dfc9fd55f4 306 *
MightyPork 1:09dfc9fd55f4 307 * @param rows - number of rows (screen height)
MightyPork 1:09dfc9fd55f4 308 * @param cols - number of columns (screen width)
MightyPork 1:09dfc9fd55f4 309 */
MightyPork 1:09dfc9fd55f4 310 void set_screen_size(int rows, int cols);
MightyPork 4:294e8f53ebcd 311
MightyPork 4:294e8f53ebcd 312
MightyPork 4:294e8f53ebcd 313 /**
MightyPork 4:294e8f53ebcd 314 * Clear the Device OK flag
MightyPork 4:294e8f53ebcd 315 */
MightyPork 4:294e8f53ebcd 316 void clear_status(void)
MightyPork 4:294e8f53ebcd 317 {
MightyPork 4:294e8f53ebcd 318 device_ok = false;
MightyPork 4:294e8f53ebcd 319 }
MightyPork 4:294e8f53ebcd 320
MightyPork 4:294e8f53ebcd 321
MightyPork 4:294e8f53ebcd 322 /**
MightyPork 4:294e8f53ebcd 323 * Query device status, clears "device_ok" and it'll be set by
MightyPork 4:294e8f53ebcd 324 * the response message.
MightyPork 4:294e8f53ebcd 325 *
MightyPork 4:294e8f53ebcd 326 * To use the query function, call clear_status() first, and then poll
MightyPork 4:294e8f53ebcd 327 * query_status() with some delays in between.
MightyPork 4:294e8f53ebcd 328 *
MightyPork 4:294e8f53ebcd 329 * @return the status flag, from a previous query
MightyPork 4:294e8f53ebcd 330 */
MightyPork 4:294e8f53ebcd 331 bool query_status(void);
MightyPork 0:20fb68233f89 332 };
MightyPork 0:20fb68233f89 333
MightyPork 3:1114012184bf 334
MightyPork 3:1114012184bf 335 /** Convenience alias for using class enums etc */
MightyPork 3:1114012184bf 336 typedef ESPTerm VT;
MightyPork 3:1114012184bf 337
MightyPork 0:20fb68233f89 338 #endif /* ESPTERM_H */