Home | pfodApps/pfodDevices | WebStringTemplates | Java/J2EE | Unix | Torches | Superannuation | CRPS Treatment | | About Us
 

Forward Logo (image)      

pfod™ Parser Library
for Arduino/non-Arduino microprocessors

by Matthew Ford 29th October 2023 (originally posted 4th January 2015)
© Forward Computing and Control Pty. Ltd. NSW Australia
All rights reserved.

pfod™ Parser Libraries V3.63.1
(Protocol For Operations Discovery)
Libraries for Arduino/non-Arduino to parse pfodApp messages.

This page describes the library for Arduino/non-Arduino microprocessors which you can use to parse pfod messages sent from the pfodApp. The code generated by pfodGUIdesigner needs pfodParser library V3.61+.

For Arduino based microprocessors, e.g. UNO, ESP8266, ESP32, Nano 33 BLE/Sense, etc, use the pfodParser and pfodDwgControls libraries as described below.
For Arduino Nano 33 IoT also install the pfodWiFiGenericBufferedClient.zip

For writing non-blocking Arduino Delays, use the millisDelay library (or pfodDelay included in the pfodParser.zip) See How to write Timings and Delays in Arduino for a tutorial.
For non-blocking serial output use pfodBufferedStream, for non-blocking user input use pfodNonBlockingInput from the pfodParser.zip library

For ESP32 the pfodParser.zip now includes pfodESPBufferedClient. NOTE: ESP32 V2.0.0 works, ESP32 V2.0.2 to V2.0.5 have problems loosing connections, but eventually work. ESP32C3 V2.0.5 works as does ESP8266 V3.0.2

For ESP8266 pfodParser.zip now includes pfodESPBufferedClient.

Some older examples like the SimplifiedUARTtoWiFiBridge example included, need the pfodESP8266BufferedClient.zip library as well. This this library is used for the pfodDesigner ESP8266 generated code. You need to install the pfodESP8266BufferedClient library, as well as the pfodParser.zip, in order to compile the ESP8266 code generated by pfodDesignerV2. See the Installation instructions below. The pfodESP8266BufferedClient library is also used in the Cheap/Simple Wifi Shield and ESP8266-01 Wifi Shield

For non-blocking ESP8266 WIFI use pfodESP8266WiFi_2.2.0.zip, but note this library only works with ESP8266 Arduino IDE V2.0

For BBC micro:bit programmed via Arduino IDE use pfodParser.zip and pfodDwgControls.zip as described below

For BBC micro:bit programmed via Netbeans C++ use the pfodParserMicroBit library. That page describes how to install the library. For non-Arduino based microprocessors, e.g. PIC etc, use the pfodParserC library. That page has detailed installation instructions and examples. There is also a pfodLinkIt library available here for the LinkIt ONE card.

Which pfod #includes to use for Arduino based microprocessors?

For example Drawing Controls install the pfodDwgControls.zip libraries and #include <pfodDwgControls.h> See this page for a detailed tutorial on DwgControls.
Also install the pfodParser library as described below and then

for the basic pfodParser for bluetooth and wifi/ethernet connections without security use (pfodDwgControls.h only need is using one of the pre-built dwg controls)
#include <pfodEEPROM.h>
#include <pfodParser.h>
#include <pfodDwgControls.h>

OR Also see note below about initializing the EEPROM for pfodSecurity
for pfod parser with optional 128bit security use (also use this for
ESP8266 OLIMEXsee example sketch) (pfodDwgControls.h only needed if using one of the pre-built dwg controls)
#include <pfodEEPROM.h>
#include <pfodSecurity.h>
#include <pfodDwgControls.h>

OR
for pfod SMS parser with optional 128bit security use (pfodDwgControls.h only need is using one of the pre-built dwg controls)

#include <pfodEEPROM.h>
#include <pfodSMS_SIM900.h>

#include <pfodSecurity.h>
#include <pfodDwgControls.h>

See the example sketches included with the library or use the free pfodDesignerV3 app to generate the Arduino code for you.

Installation:

If you have previously installed any version of the libraries, pfodParser, pfodCmdParser, pfodCHAP or pfodESP8266WiFi, then find them in your libraries directory and delete their folders completely.

a) Then download the pfodParser.zip, pfodDwgControls.zip zip files to your computer, move them to your desktop or some other folder you can easily find
For older example code, if using ESP8266 the pfodESP8266BufferedClient.zip as well. If using ESP32 the pfodESP32BufferedClient.zip as well. Otherwise for newer example code pfodParser library already includes the pfodESPBufferedClient class.
If using Arduino Nano 33 IoT also install pfodWiFiGenericBufferedClient.zip

b) Then use Arduino 1.8.2 IDE menu option SketchImport LibraryAdd Library to install them.
(If Arduino does not let you install it because the library already exists then find and delete the older
pfodParser, pfodCmdParser or pfodCHAP etc folders and then import these ones)

c) Stop and restart the arduino IDE and under File->Examples you should now see pfodParser, pfodDwgControls and pfodESP2866BufferedClient libraries and a number of examples.

LibraryVersions.txt

Modifications need to Compile with mbed (i.e. Redbear NanoV2)

Because there is a name conflict between Arduino's Stream class and mbed's Stream class, in Order to use pfodParser library with NanoV2 you have to replace
the
platform.txt file in directory
.....\packages\RedBear\hardware\nRF52832\0.0.2

with the platform.txt file from the pfodParser\examples\SampleRedbearBLENanoV2Screens directory.

This modified platform.txt adds a __MBED__ define so that pfodStream.h can include the correct stream header and rename the conflicting class.

Library Reference:

For pfodDwgs and pfodDwgControls libraries see this tutorial page. pfodDelay in the pfodParser library is a duplicate of the millisDelay library. See How to write Timings and Delays in Arduino for a tutorial

pfodParser

Description
pfodParser for Arduino, Parses commands of the form {cmd} or { cmd ` arg1`arg2 ... } or { cmd ~ arg1 ~ arg2 … }
The args are optional.

This is a complete parser for ALL commands a pfodApp will send to a pfodDevice
pfodParser adds about 500 bytes to the program and uses about 280 bytes RAM

Methods

pfodParser – no argument constructor, see example code.

pfodParser.connect(Stream*) – connects the parser to an input stream. E.g parser.connect(&Serial); This is usually called from setup().

pfodParser.parse() – parses commands from the connected stream. This is called from loop().
Return: return 0 if complete message not found yet else return first char of cmd when see closing } or ignore msg if pfodMaxCmdLen bytes after {
On non-zero return args[] contains the cmd null terminated followed by the args null terminated argsCount is the number of args
Check isRefresh() to see if this is a refresh command.

isRefresh()returns bool, true or false. Returns true if last command started with {: indicating pfodApp is requesting a refresh of the menu associated with the cmd.
This method only returns true if the refresh interval of the current menu is < 0. See the pfodSpecification.pdf for details.

pfodParser.closeConnection() – closes the connection to this parser by clearing out any partial commands being parsed.
This is usually called when the CloseCommand, {!}, is received or when the pfodDevice sends a CloseCommand to the pfodApp.
NOTE: The Stream connected to the parser is not cleared. So there is no need to call connect again if the Stream has not changed.

pfodParser inherits from Print so you can use all the Print methods to write the responses back to pfodApp

pfodParser.getCmd() – returns pointer to null terminated parsed command.

pfodParser.getFirstArg() – returns pointer to null terminated first arg if any, else if no args returns pointer to null.

pfodParser.getNextArg(byte*) – returns pointer to start of next arg or pointer to null is reached end of args. Need to call getFirstArg() to get byte * to pass to this method.

pfodParser.getArgsCount() – returns the number of args in the last message parsed.

pfodParser.parseLong(byte* idxPtr, long *result) – parses a null terminated bytes into a long, returns pointer to next byte after terminating null. Long result is returned via long *

Stream* pfodParser.getPfodAppStream()returns a pointer to the Stream that is connected to this parser.

pfodParser.setIdleTimeout(unsigned long timeout)set the connection timeout in seconds. Does nothing in pfodParser, but is essential for pfodSecurity and is included here for code compatible. NOTE: for the deprecated ESP8266_AT this method does nothing, use ESP8266_AT.setIdleTimeout(...) instead.

pfodParser.setDebugStream(Stream* debugOut)sets the debug output stream. This must be called before any other method in this class is called. It is only used if you modify the library code to turn on debugging.


Examples

The UnoStarter sketch lets you test out your Uno board's I/O from your Android mobile via bluetooth. There is also a pfodBluetooth example that uses Serial to connect via IteadStudio Bluetooth sheild.

pfodSecurity

Note: pfodSecurity uses EEPROM (if available) to store the power cycles count to prevent an attacker from just turning the power on and off to reset the message hashes.
The EEPROM needs to be initialized first by adding
pfodMAC::resetPowerCycles() to the setup() and running the sketch which will initialize the power cycles and then hang at that point. Remove the resetPowerCycles() call to run normally.
For microprocessors without EEPROM additional random numbers make it very very unlikely the hashes will repeat after a power cycle. See Secure Challenge and Response for all the details

Description
pfodSecurity for Arduino, Parses commands of the form {cmd} hashcode or { cmd ` arg1`arg2 ... } hashcode or { cmd ~ arg1 ~ arg2 … } hashcode
The args are optional.
It supports an optional challenge and response security, via a 128 bit secret password, which protects against unauthorized connections. Each message from the pfodDevice has a encryption strength hash code added to it and the hash code of every incoming command is checked for validity. If any of these fail, the connection is closed.
Generate you own secret password (and QR code) using the
SecretKeyGenerator
See Challenge and Response Security for Internet connected pfodDevices™ for the details of security provided by this library.

This is a complete paser for ALL commands a pfodApp will send to a pfodDevice
pfodSecurity adds about 6300 bytes to the program and uses about 400 bytes RAM and 19 bytes of EEPROM

Methods

pfodSecurity – no argument constructor

pfodSecurity.connect(Stream* io)connects the parser to an input stream, with no password specified. E.g parser.connect(&Serial); This is usually called from setup().

pfodSecurity.connect(Stream* io, const __FlashStringHelper *hexKey) – connects the parser to an input stream, with a password specified. E.g pfodSecurity.connect(&Serial, F("173057F7A706AF9BBE65D51122A14CEE")); This is usually called from setup(). The password can be upto 32 hex digits in length. It is stored in EEPROM starting at location 0 and uses the next 19 bytes of EEPROM for persistent storage.

pfodSecurity.connect(Stream* io, const __FlashStringHelper *hexKey, int eepromAddress) – connects the parser to an input stream, with a password specified. E.g pfodSecurity.connect(&Serial, F("173057F7A706AF9BBE65D51122A14CEE"), 20); This is usually called from setup(). The password can be upto 32 hex digits in length. It is stored in EEPROM starting at the given location (20 in this example) and uses the next 19 bytes of EEPROM for persistent storage.

pfodSecurity.connect(pfod_Base* io)connects the parser to an SMS or ESP8266_AT input stream, with no password specified. E.g parser.connect(pfodSMS); This is usually called from setup().

pfodSecurity.connect(pfod_Base* io, const __FlashStringHelper *hexKey) – connects the parser to an SMS or ESP8266_AT input stream, with a password specified. E.g pfodSecurity.connect(pfodSMS, F("173057F7A706AF9BBE65D51122A14CEE")); This is usually called from setup(). The password can be upto 32 hex digits in length. It is stored in EEPROM starting at location 0 and uses the next 19 bytes of EEPROM for persistent storage.

pfodSecurity.connect(pfod_Base* io, const __FlashStringHelper *hexKey, int eepromAddress) – connects the parser to an SMS or ESP8266_AT input stream, with a password specified. E.g pfodSecurity.connect(pfodSMS, F("173057F7A706AF9BBE65D51122A14CEE"), 20); This is usually called from setup(). The password can be upto 32 hex digits in length. It is stored in EEPROM starting at the given location (20 in this example) and uses the next 19 bytes of EEPROM for persistent storage.

pfodSecurity also has all the pfodParser methods as well. Only the differences are noted below.

pfodSecurity.closeConnection() – closes the connection to this parser by clearing out any partial commands being parsed AND disables the sending of rawData. This prevents filling up transmission buffers with data when there is no connection.
This is usually called when the CloseCommand, {!}, is received or when the pfodDevice sends a CloseCommand to the pfodApp.
NOTE: The Stream connected to the parser is not cleared. So there is no need to call connect again if the Stream has not changed.
Also once another command is received the rawData output is re-enabled.

pfodSecurity.setIdleTimeout(unsigned long timeout)set the timeout in seconds, which closes the connection if no commands received from the pfodApp and no raw data is being sent. Default is 15sec. Set to >0 if you want the connection to timeout (recommended). This closes the connection after the timeout and returns ! from the parser. The sketch code should then do any clean up necessary to allow another connection. There is also an authentication time out.

pfodSecurity.setAuthorizationTimeout(unsigned long timeout)set the authorization timeout in seconds. Default is 15sec. Not used if no password set. If a password is set and the pfodApp send the start authorization command, {_}, then authorization process must be completed within this time out otherwise the pfodDevice will return return ! from the parser. The sketch code should then do any clean up necessary to allow another connection.

pfodSecurity.setDebugStream(Stream* debugOut)sets the debug output stream. This must be called before any other method in this class is called. It is only used if you modify the library code to turn on debugging by uncommenting the #define DEBUG...s at the top of the code

pfodMAC::resetPowerCycles(int eepromAddress)resets the power cycles to 0xffff. eepromAddress defaults to 0 if omitted. sets the debug output stream. NOTE: This static method call NEVER returns. Put it at the top of setup() to reset the power cycles and then remove it for normal operation

Example

See the example sketches included with the library. They include a UNO bluetooth sketch, pfodEthernet and pfodEthernetWithPassword Also see A Simple WiFi/Arduino pfodDevice.

pfodSMS_SIM900 (pfodSMS_SIM5320 is similar check the .h file)

Description
pfodSMS_SIM900 for Arduino is a subclass of pfod_Base and handles the SMS messages to and from a SIM900 based shield.
See Reliable Remote Control via SMS with pfodSMS for the details of the design.

This class is designed to be passed to pfodSecurity in place of the io Stream pointer.
pfodSMS_SIM900 together with pfodSecurity adds about 16300 bytes to the program and uses about 3000 bytes RAM and 19 bytes of EEPROM
Because of the RAM requirements pfodSMS_SIM900 cannot be used on an UNO. You need to use a Mega2560 or similar with more then 4K of RAM.

Methods

pfodSMS_SIM900 – no argument constructor

pfodSMS_SIM900.init(Stream* io)connects the pfodSMS_SIM900 to the GPRS input stream E.g pfodSMS.init(&Serial); This is usually called from setup().

pfodSMS_SIM900.init(Stream* io, int powerResetPin) – connects the pfodSMS_SIM900 to the GPRS input stream and uses Digital pin powerResetPin to turn the GPRS shield on. E.g pfodSMS.init(&Serial, 9); This should be called from setup(). If the power up process fails it just tries again. It can fail if the SIM card is not inserted or if it has a pin number set. If you see the GPRS shield power led cycle on and off every 20secs then that indicates the shield is not initializing correctly.

pfodSMS_SIM900.setIdleTimeout(unsigned long timeout)set the timeout in seconds, default 600 (10mins). This should not be set to 0.
For a SMS connection the idle time out functions differently. Once a user has connected with pfodApp, that connection registered by the pfodDevice and is maintained forever until it is closed by a CloseCommand,
{!}
However after the idle time out, i.e. no new SMS messages from the pfodApp for 10mins, the pfodDevice will accept a new connection from another pfodApp and close the old connection. The old pfodApp will now not not be able to connect until the new connection either closes its connection or does not send any SMS msgs for 10mins.

pfodSMS_SIM900.setDebugStream(Stream* debugOut)sets the debug output stream. This must be called before any other method in this class is called. It is only used if you modify the library code to turn on debugging.

Example

See the pfodSMS_SIM900 example sketch included with the library. It connects with pfodApp via SMS using a SIM900 based GPRS shield.

pfodESP8266BufferedClient – V2.3 (Works with ESP8266.com IDE plugin V2.0+)

Description
pfodESP8266BufferedClient provides buffering and other utilities for Ivan Grokhotkov et al's ESP8266WiFi library
If you have installed the pfodESP8266WiFi library, delete it completely as it is not compatible with the ESP8266WiFi library V2.0+

Methods

pfodESP8266BufferedClient – Additional class, extends from Stream and provides buffered non-blocking TCP writes via WiFiClient.
You must call one of this classes' methods each loop to ensure the last data is written.
pfodESP8266BufferedClient.peek() or pfodESP8266BufferedClient.available() are often used.

pfodESP8266BufferedClient() – constructor

pfodESP8266BufferedClient.connect(WiFiClient*) – attaches an ESP8266 WiFiClient for TCP reads and buffered non-blocking writes.

pfodESP8266BufferedClient.write(..) – preforms a buffered write to the TCP/IP WiFi connection. Bytes are buffered in a 1460 byte buffer until either the buffer is full OR there have been not bytes added for 10mS.

pfodESP8266BufferedClient.flush() – writes any buffered data to the WiFi connection. This will block if the ESP2866 is still waiting for the previously send packet be ACKed by the remote client.

pfodESP8266BufferedClient.setDebugStream(Stream* debugOut)sets the debug output stream. This must be called before any other method in this class is called. It is only used if you modify the library code to turn on debugging.

pfodESP8266Utils – Additional static support methods

pfodESP8266Utils.strncpy_safe(char* dest, const char* src, size_t maxLen) – copies at most maxLen-1 chars from src to dest and terminates with a null.

pfodESP8266Utils.urldecode2(char *dst, const char *src) – Decodes url escaped chars.

pfodESP8266Utils.parseLong(uint8_t* idxPtr, long *result) – parses chars to a long, stores long in result. Will parse between -2,147,483,648 to 2,147,483,647

int pfodESP8266Utils.isEmpty(const char* str) – returns 1 if all chars in string <= space (i.e. spaces, tabs, ctrl chars etc) or strlen == 0

char * pfodESP8266Utils.isEmpty(const char* str) – removes leading and trailing chars that are <= space (i.e. spaces, tabs, ctrl char etc)

pfodESP8266Utils.ipStrToNum(const char* ipStr) – returns uint32_t for passing to ipAddress( ), works for IPV4 only, parses "10.1.1.200" and "10,1,1,200" strings, extra spaces ignored eg "10, 1, 1, 200" is OK.

pfodESP8266Utils.encryptionTypeToStr(uint8_t type) – returns const char* to the name of the ESP8266 encryption type.

pfodESP8266Utils.scanForStrongestAP(char* result, size_t resultLen) – scans for Access Points and returns the name of the one with the strongest signal.

pfodESP8266WebConfigprovides class for setting network parameters via a webpage. See HomeAutomation -- InlineWiFiPowerSwitch -- Adding Web Page Network Configuration for an example if its use.



AndroidTM is a trademark of Google Inc, For use of the Arduino name see http://arduino.cc/en/Main/FAQ


The General Purpose Android/Arduino Control App.
pfodDevice™ and pfodApp™ are trade marks of Forward Computing and Control Pty. Ltd.


Forward home page link (image)

Contact Forward Computing and Control by
©Copyright 1996-2024 Forward Computing and Control Pty. Ltd. ACN 003 669 994