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

Forward Logo (image)      

pfod™ Parser Library
for Arduino/non-Arduino microprocessors

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

pfod™ Parser Libraries V3.18
(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 pfodDesignerV3 V3.0.3000+ needs pfodParser library V3.1+.

For Arduino based microprocessors, e.g. UNO, ESP8266 etc, use the pfodParser and pfodDwgControls libraries as described below.

For BBC micro:bit 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.

For ESP8266 use there is additional special pfodESP8266BufferedClient library (V2.2) which provides buffering TCP writes to WiFi clients and some utility methods.
See the SimplifiedUARTtoWiFiBridge example included. 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
Note: If you have previously installed the pfodESP8266WiFi library, delete that library directory completely as it is not compatible with ESP8266.com IDE plugin V2.0+
There is also a pfodLinkIt library available here for the LinkIt ONE card.

Which #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
for pfod parser with optional 128bit security use (also use this for
ESP8266 OLIMEXsee example sketch) (pfodDwgControls.h only need is 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 pfodDesignerV2 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 and, if using ESP8266 the pfodESP8266BufferedClient.zip, zip files to your computer, move them to your desktop or some other folder you can easily find

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

Library Reference:

For pfodDwgs and pfodDwgControls libraries see this tutorial page.

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 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

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.

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

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.

pfodESP8266WebConfig – provides 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


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-2017 Forward Computing and Control Pty. Ltd. ACN 003 669 994