diff options
Diffstat (limited to 'client')
| -rw-r--r-- | client/cmd.h | 140 | ||||
| -rw-r--r-- | client/pbc.1 | 90 | ||||
| -rw-r--r-- | client/readme.md | 23 | ||||
| -rw-r--r-- | client/rl.cpp | 7 | ||||
| -rw-r--r-- | client/sock.h | 1 |
5 files changed, 142 insertions, 119 deletions
diff --git a/client/cmd.h b/client/cmd.h index e2c412a..eac9834 100644 --- a/client/cmd.h +++ b/client/cmd.h @@ -5,10 +5,6 @@ * \defgroup pbc_cmd Commands * \brief Commands within \ref pbc * - * \note A manpage is available containing end-user usage instructions inside - * the \ref client folder in the source code repository. This page contains the - * internal code documentation for the commands defined in \c pbc. - * * \{ */ @@ -45,13 +41,149 @@ typedef struct { cmd_complete_t * complete; //!< Completion function (optional = NULL) } cmd_t; +/** + * \anchor pbc_cmd_usage + * \name Command usage + * \{ + */ + +/** + * \brief \c exit command + * + * ``` + * (pbc) exit + * ``` + * + * Disconnect from the puzzle box and exit \c pbc. This command takes no + * arguments. + */ cmd_handle_t cmd_exit; +/** + * \brief \c test command + * + * ``` + * (pbc) test + * ``` + * + * Send a test command containing the ASCII string "Hello world!" to I2C + * address 0x39. This command takes no arguments. + */ cmd_handle_t cmd_test; +/** + * \brief \c help command + * + * ``` + * (pbc) help + * ``` + * + * Print a list of available commands with descriptions. This command takes no + * arguments. + */ cmd_handle_t cmd_help; +/** + * \brief \c reset command + * + * ``` + * (pbc) reset <mod> + * ``` + * + * Set a specific puzzle module's global state to *idle*. *mod* is the I2C + * address of the puzzle module to reset. This parameter may be specified in + * hexadecimal using a *0x* prefix or decimal. + * + */ cmd_handle_t cmd_reset; +/** + * \brief \c send command + * + * ``` + * (pbc) send <addr> <data> + * ``` + * + * Send arbitrary data specified by *data* to the I2C address specified by + * *addr*. *data* may consist of multiple arguments separated by \ref IFS, in + * which case the arguments are concatenated. + * + * The main controller will initiate an I2C write command if the address + * specified in *addr* does not match that of the main controller. If the + * addresses do match, the main controller interprets the message as if it were + * being addressed by another I2C controller. + * + * \par Example + * ``` + * ADDRESS DATA + * v~~~ v~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * (pbc) send 0x39 68:65:6c:6c:6f 44 0x20 'world' 33 + * ^~~~~~~~~~~~~~ ^~ ^~~~ ^~~~~~~ ^~ + * HEXSTR NUMBER NUMBER STRING NUMBER + * (binary) (dec) (hex) (literal) (dec) + * ``` + * + * \par Datatypes + * \parblock + * - **NUMBER** + * + * Numbers can be specified as decimal or hexadecimal using a "0x" prefix. + * All numbers are unsigned. Decimal literals are always cast to 8-bit + * integers, while hexadecimal literals are cast to the smallest type that + * will fit the specified number. Numbers are always sent as little endian. + * + * Examples: `0` `123` `255` `0x10` `0x1245` `0xdeadBEEF` + * + * - **HEXSTR** + * + * Hexadecimal string literals are specified by hexadecimal bytes separated + * by colons. Each byte must be exactly 2 hexadecimal characters long and + * followed by a colon (except for the last byte). The minimum length of a + * hexstr is 2 bytes, as it must include at least a single colon. + * + * Examples: `de:ad:be:ef` `00:00` + * + * - **STRING** + * + * A string literal starts and ends with a single quote. All characters within + * this literal are sent as-is, and no escaping is possible. + * + * Examples: <code>'Hello world!'</code> <code>'string'</code> <code>' hello + * '</code> + * + * When double quotes are used instead of single quotes, the following escape + * sequences are recognised and replaced with special characters: + * |input|replacement|meaning| + * |-|-|-| + * |`\0`|0x00|null| + * |`\t`|0x09|tab| + * |`\n`|0x0a|newline| + * |`\r`|0x0d|carriage return| + * |`\\`|0x5c|backslash| + * |`\"`|0x22|double quote| + * |<code>\'</code>|0x27|single quote| + * + * Examples: `"Hello world!\\0"` `"foo\\nbar"` + * \endparblock + */ cmd_handle_t cmd_send; +/** + * \brief \c skip command + * + * ``` + * (pbc) skip <mod> + * ``` + * + * Set a specific puzzle module's global state to *solved*. *mod* is the I2C + * address of the puzzle module to skip. This parameter may be specified in + * hexadecimal using a *0x* prefix or decimal. + * + */ cmd_handle_t cmd_skip; +/** + * \brief \c dump command + */ cmd_handle_t cmd_dump; + +/// \} + +//! \c dump completion function cmd_complete_t cmd_dump_complete; //! Commands diff --git a/client/pbc.1 b/client/pbc.1 deleted file mode 100644 index a85b03a..0000000 --- a/client/pbc.1 +++ /dev/null @@ -1,90 +0,0 @@ -\# vim: ft=groff -.de I2C -I\*{2\*}C -.. -.TH pbc 1 -.SH NAME -pbc \- puzzle box client -.SH SYNPOSIS -pbc <addr> [port] -.SH DESCRIPTION -Connect to a puzzle box at the IPv4 address specified by \fIaddr\fP and -optionally port specified by \fIport\fP. The default port is 9191. Once -connected, a -.MR readline 3 -based -CLI is started, and commands can be sent. -.SH COMMANDS -.TP -exit -Disconnect from the puzzle box and exit pbc. This command takes no arguments. -.TP -help -Print a list of available commands with descriptions. This command takes no -arguments. -.TP -reset [mod ...] -Set the main controller or specific puzzle module's global state to \fIidle\fP. -If no modules are specified, the main controller's state is updated. One or -more modules can be specified to update them at once. -.TP -skip [mod ...] -Set the main controller or specific puzzle module's global state to -\fIsolved\fP. If no modules are specified, the main controller's state is -updated. One or more modules can be specified to update them at once. -.SH DEBUG COMMANDS -The commands detailed under this section are only available in version of pbc -compiled with debug support. -.TP -send <addr> <data> -Send arbitrary data specified by \fIdata\fP to the -.I2C -address specified by \fIaddr\fP. \fIdata\fP may consist of multiple arguments -separated by IFS, in which case the arguments are concatenated. -.TP -test -Send a test command containing the ASCII string "Hello world!" to -.I2C -address 0x39. This command takes no arguments. -.SH DATA FORMATS -.TP -number -Numbers can be specified as decimal or hexadecimal using a "0x" prefix. All -numbers are unsigned. Decimal literals are always cast to 8-bit integers, while -hexadecimal literals are cast to the smallest type that will fit the specified -number. Numbers are always sent as little endian. - -Examples: 0 123 255 0x10 0x1245 0xdeadBEEF -.TP -hexstr -Hexadecimal string literals are specified by hexadecimal bytes separated by -colons. Each byte must be exactly 2 hexadecimal characters long and followed by -a colon (except for the last byte). The minimum length of a hexstr is 2 bytes, -as it must include at least a single colon. - -Examples: de:ad:be:ef 00:00 -.TP -string -A string literal starts and ends with a single quote. All characters within -this literal are sent as-is, and no escaping is possible. - -Examples: 'Hello world!' 'string' ' hello ' - -When double quotes are used instead of single quotes, the following escape -sequences are recognised and replaced with special characters: - -\\0 -> 0x00 (null) -.br -\\t -> 0x09 (tab) -.br -\\n -> 0x0a (newline) -.br -\\r -> 0x0d (carriage return) -.br -\\\\ -> 0x5c (backslash) -.br -\\" -> 0x22 (double quote) -.br -\\' -> 0x27 (single quote) - -Examples: "Hello world!\\0" "foo\\nbar" - diff --git a/client/readme.md b/client/readme.md index b9e0b09..d99991f 100644 --- a/client/readme.md +++ b/client/readme.md @@ -18,31 +18,12 @@ arbitrary data over the puzzle bus. - Request puzzle box state - Debug: send arbitrary messages -## Building - -PBC is a standard CMake project. - -## Using - -See ./pbc.1 for usage. - -## Send data - -``` - ADDRESS DATA - v~~~ v~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -send 0x39 68:65:6c:6c:6f 44 0x20 'world' 33 - ^~~~~~~~~~~~~~ ^~ ^~~~ ^~~~~~~ ^~ - HEXSTR NUMBER NUMBER STRING NUMBER - (binary) (dec) (hex) (literal) (dec) -``` - -The data is concatenated, and may contain mixed types of literals +## Usage +See \ref pbc_cmd_usage "command usage" for individual command usage. ## WIP TODO - add enum to string functions in CLIENT ONLY - bug: tab completion for `dump` seems to print garbage sometimes -- bug: the send command with an address but no data causes a segmentation fault diff --git a/client/rl.cpp b/client/rl.cpp index 493f753..82d1412 100644 --- a/client/rl.cpp +++ b/client/rl.cpp @@ -128,18 +128,17 @@ int rl_word(const char * line, int cursor) { return word; } -/// \internal typedef struct { const char * word; const char ** options; -} __rl_complete_list_data_t; +} _rl_complete_list_data_t; char** rl_complete_list(const char * word, const char ** options) { - __rl_complete_list_data_t data = { + _rl_complete_list_data_t data = { .word = word, .options = options, }; return rl_completion_matches((char *) &data, [](const char * text, int state) -> char * { - __rl_complete_list_data_t data = *(__rl_complete_list_data_t *) text; + _rl_complete_list_data_t data = *(_rl_complete_list_data_t *) text; static size_t i = 0; if (state == 0) i = 0; diff --git a/client/sock.h b/client/sock.h index 792123e..5b62861 100644 --- a/client/sock.h +++ b/client/sock.h @@ -18,6 +18,7 @@ class PBSocket { public: PBSocket(); + //! Constructor that immediately calls \c set_server() PBSocket(const char * addr, uint16_t port); virtual ~PBSocket(); |