diff --git a/README.md b/README.md index b587a64..52592ab 100644 --- a/README.md +++ b/README.md @@ -62,4 +62,73 @@ void loop() } ``` -The code above will automatically generate the command packet and send it, and process the incomming acknowledge or repeat packets from the receiver. \ No newline at end of file +The code above will automatically generate the command packet and send it, and process the incomming acknowledge or repeat packets from the receiver. + +## Registering A New Command + +Registering new commands is by far the most difficult part of using the library, however it is still quite easy to do. Since the library works on the principle of event based call-back functions they need to be created and registered. The way that is done is by first creating the definitions for the handler functions and the and their registration functions. + + +### Creating handler definitions +To do that first open the `serialConnector.h` file and go to the `Command Handlers` section near the top of the file. This is where you need to create a function pointer which takes in a string as an argument and follows the naming convention `Handler`. So if we were to register a handler for a function called error it would look something like this. + +```cpp +void (*errorHandler)(String args); +``` + +***NOTE: Make sure that you surround the function name with brackets*** + + +Then you also need to create the definition for the registration function. This is done in the `Command Handlers Registers` section near the bottom of the document. Here create a function which function with a return type of `void` and takes in an argument of `void (*handler)(String args)`. Here there is also a naming convention of `on` so for the error function it would look like this. + +```cpp +void onError(void (*handler)(String args)); +``` + +### Defining the registration functions + +Now it's time to make the registration functions work. For this first open the `serialConnector.cpp` file and go near the bottom to the `Command Handlers Registers` section and assign each handler a callback function like this + +```cpp +void SerialConnector::onError(void (*handler)(String args)) +{ + errorHandler = handler; +} +``` + +### Calling the handler + +Now it's time to make sure the handler gets called whenever the `cycle` function receives a command for it. To do that go in to the `Command Dispatcher` section of the `cycle` function in the `serialConnector.cpp` file and in the else-if statement which is there put the name of your command and in the if statemnt call the handler with the `args` argument. For the `ERR` command it would look like this. + +```cpp + if (cmd == "ERR") + { + if (errorHandler) + errorHandler(args); + } + else + { + // Unknown/unused command + } +``` + +To add on any extra commands just add another else to that else-if statement. + +### Assigning a callback function + +Finally it's time to make the command do stuff. This is done by passing in a callback function to the registration command created earlier. Here is an example of how that would look like in the `main.cpp` file. + +```cpp +#include + +SerialConnector *conn = new SerialConnector() + +void error(String args) {} + +void setup() +{ + conn->onError(&error); +} +``` + +What this code does is it executes the `error` function any time an `ERR` command is received and passes on any of the received arguments in to the `error` functions `args` argument for the user to use in the `error` function. \ No newline at end of file diff --git a/include/serialConnector.h b/include/serialConnector.h index 894800e..6d68904 100644 --- a/include/serialConnector.h +++ b/include/serialConnector.h @@ -20,7 +20,9 @@ private: String received; String command; - // Callback handlers for specific commands + /////////////////////////////////////////// + /// Command Handlers /// + ///////////////////////////////////////// void (*calibrationBeginHandler)(String args); void (*calibrationInteruptHandler)(String args); @@ -102,7 +104,9 @@ public: */ void cycle(); - // Register a callbacks for specific commands. + /////////////////////////////////////////// + /// Command Handlers Registers /// + ///////////////////////////////////////// void onCalibrationBegin(void (*handler)(String args)); void onCalibrationInterupt(void (*handler)(String args)); diff --git a/src/serialConnector.cpp b/src/serialConnector.cpp index 73ffac9..79ed35d 100644 --- a/src/serialConnector.cpp +++ b/src/serialConnector.cpp @@ -39,6 +39,9 @@ void SerialConnector::cycle() acknowledge(getCheckBitFromIncomming(raw).toInt()); // Dispatch known commands to their handlers if present. + /////////////////////////////////////////// + /// Command Dispatcher /// + ///////////////////////////////////////// if (cmd == "CAL-BGN") { if (calibrationBeginHandler) @@ -322,6 +325,9 @@ void SerialConnector::afterSendCheck(String cmd) } } +/////////////////////////////////////////// +/// Command Handlers Registers /// +///////////////////////////////////////// void SerialConnector::onCalibrationBegin(void (*handler)(String args)) { // Register the callback invoked when a CAL-BGN message is received.