Check out the examples for different use cases.
This library is meant to assist in interfacing with your hardware, either through a uint8_t buffer, or a Stream, such as a Serial interface object.
Class output is enabled by defining a buffer, the class methods format the buffer into useful human readable information. ih::Input (the input parser) will function as normal without an output buffer.
Command length has no restrictions, any printable char or control char that is not your end of line character, token delimiter, or c-string delimiter is a valid commandString. You can have up to config.h:IH_MAX_ARGS_PER_COMMAND number of arguments. At runtime, ih::Input:addCommand() scans ih::Parameters and determines the maximum number of arguments you intend to use, it then allocates a dynamically sized array of flags (bit flags in a future feature) which lives for the duration of the process (one allocation per invocation of ih::Input::begin())
User-defined commands have a general tree structure, each command has its own ih::Parameters struct which is stored in non-volatile program memory (PROGMEM on Arduino platforms).
Individual commands that do not contain a wildcard character (each call to ih::Command) use 8 bytes of RAM (on avr). Commands that contain wildcards use more, how much they use depends on the placement of the wildcard characters, and the command length.
The ih::Command ih::Parameters target function will not execute if the input does not match the ih::Command ih::Parameters ih::Parameters::command, if any arguments are type-invalid, or if an unexpected amount of arguments are received.
To make input matching more performant, ih::Parameters::command that contain one or more ih::WildcardChar have their memcmp ranges computed at runtime for each command containing a wildcard char, each memcmp range that needs to be remembered uses ((1 + (1 + 1*n_wcc_containing_prm) + 1) + n_memcmp_ranges*2)
bytes. ****
, 8***
, *8**
, **8*
, ***8
would compute one memcmp range 8**8
computes as two, 8888
doesn't have any wcc, so it would undergo "length of input" memcmp. Memcmp ranges are command-wide, if you have a nested command it will only have one associated ih::CommandRuntimeCalc struct.
InputHandler uses C++11 Aggregate initialization for ih::Parameters and ih::InputParameters structs.
Class output is enabled by defining a buffer, the class methods format the buffer into useful human readable information.
Default InputHandler Input constructor initialization with no output:
/*
InputHandler default Input constructor uses InputParameters variables defined in the namespace ihc src/config/utility/namespace.h
*/
#include <InputHandler.h>
using namespace ih;
Input inputHandler;
Default InputHandler Input constructor initialization with output buffer:
/*
InputHandler default Input constructor uses InputParameters variables defined in the namespace ihc src/config/utility/namespace.h
This constructor will output messages into `output_buffer`, you can check to see if there's a message with ih::Input::isOutputAvailable()
*/
#include <InputHandler.h>
using namespace ih;
char output_buffer[512] = {'\0'}; // output buffer
Input inputHandler(output_buffer, buffsz(output_buffer)); // Input constructor with output buffer and buffer length
Many aspects of InputParameters are customizable:
#include <InputHandler.h>
using namespace ih;
// char array typdef aliases
const PROGMEM ProcessName process_name = "_test_"; // process name
const PROGMEM EndOfLineChar process_eol = "\r\n"; // end of line characters
const PROGMEM ControlCharSeq process_ccseq = "##"; // input control character sequence
const PROGMEM WildcardChar process_wcc = "*"; // process wildcard character
// ih_auto::size_t, {ih_auto::size_t,...}, {ih_auto::char_array,...}
const PROGMEM DelimiterSequences process_delimseq = {
1, // number of delimiter sequences
{1}, // delimiter sequence lens
{" "} // delimiter sequences
};
// ih_auto::size_t, {ih_auto::size_t,...}, {ih_auto::char_array,...}
const PROGMEM StartStopSequences process_ststpseq = {
1, // num start stop sequence pairs
{1, 1}, // start stop sequence lens
{"\"", "\""} // start stop sequence pairs
};
const PROGMEM InputParameters input_prm[1] = {
&process_name,
&process_eol,
&process_ccseq,
&process_wcc,
&process_delimseq,
&process_ststpseq
};
char output_buffer[512] = {'\0'}; // output buffer
Input inputHandler(input_prm, output_buffer, buffsz(output_buffer)); // Input constructor
A valid command string would look like this with the above InputParameters:
your_command arg_1 arg_2 arg... "arguments enclosed with start/stop delimiter sequences can have any char value 0-255, you can memcpy these argument types directly into a recipient struct (size - 1 to remove the null terminator) as uint8_t"
your_command subcommand_1 subcommand_2 ... subcommand_N subcommand_N_arg1 subcommand_N_arg2 ...
y*ur_co***** ...
ih::Input's input methods are:
void getCommandFromStream(Stream &stream, size_t rx_buffer_size = IH_MAX_PROC_INPUT_LEN);
Or, if you don't want to use a Stream object use this method instead:
void readCommandFromBuffer(uint8_t *data, size_t len);
This method will output to any initialized stream (hardware or software Serial):
void ih::Input::outputToStream(Stream &stream);
or, you can check to see if ihout output is available with:
bool ih::Input::outputIsAvailable();
and then when you are done with the output buffer, it needs to be reinitialized with:
void ih::Input::clearOutputBuffer();
Please report any bugs in InputHandler/src/ using bug_report.md at InputHandler/src/ bug report forum
Made with PyInstaller
Ease of use.
Implementation and platform flexibility.
Feature rich.
Low memory use.
Parse uint8_t, any value 0-255 char array.
Inter equipment interfacing.
Construct complex commands with subcommands, and enforce the input type.
Nested commands with no wildcards use 8 bytes or less of sram (avr).
See the releases' descriptions on the library's release page for a list of changes.
Not supported:
ATTiny85 -- memory/flash
ATMegaNG -- flash
adafruit:samd:adafruit_neotrinkey_m0 -- doesn't build
adafruit:samd:adafruit_pybadge_airlift_m4 -- doesn't build
arduino:samd:nano_33_iot -- doesn't build
If your board is not listed as not supported open an issue if you'd like it added to build coverage.
NOTE: vsnprintf and
dtostrf implemented on the following platforms:
(see: src/config/noedit.h for your platform's implementation)
SAMD,
MBED,
arduino DUE
Build coverage:
Arduino
platformIO
The docs use a feature not supported by every browser to jump to C++ source text. Source links will still take you to the source file, but to take advantage of url-scroll-to-text-fragment you need to use a supported browser, like chrome. Alternatively you can install an addon into firefox auto find text fragment to enable the functionality.
Generated by auto-changelog
.
d33e0e9
a4e877d
de55c84
2289102
bd7c4a1
89d16e7
4dd1c60
a073c78
8d221a2
7d0d097
6cf604d
7ca42e8
1f790b4
8def221
365f8d9
39e7eec
09c6246
417009c
056bdf3
da81b57
4806767
1f5959b
90792d6
f0e659d
3c44528
895ac2a
f7078b1
22bc0ae
b451ad7
5e53f49
264b563
70ebdb9
3e15aa8
21b36dc
69bdb22
9072774
8c4efd8
6cf0974
9d2f2c1
cadcf6a
b2c22ff
440a70e
52ea0d8
63fa1d3
43642b7
25ec2da
a08b99c
2462937
4d0856c
2531183
fb08dce
3d6150a
0aba2b1
150f3dd
e3169f2
8569029
21cb6c4
ee02127
7266b33
8a1a212
e51a49f
315ea90
115838c
fc67bef
849fbe0
72ea79a
ccf1c8c
6697063
5b2bcd2
3b04c5f
d7e65f1
99d95b5
5719d6c
46a902f
fffa68b
a42b01d
2981a8e
3b3f462
0761161
0067547
aa5c9af
e691d11
28c95f6
033f47c
7a8d03d
dc9361d
b0d9a2e
3149afb
94b88f8
be291f3
a77f6e8
0ac9230
19fca91
025d809
4e5c079
5a7e526
f4cc103