|
Home
| pfodApps/pfodDevices
| WebStringTemplates
| Java/J2EE
| Unix
| Torches
| Superannuation
| CRPS Treatment
|
| About
Us
|
|
|
pfod™ Parser Library
|
by Matthew Ford 29th October 2023 (originally posted
4th January 2015)
© Forward Computing and Control
Pty. Ltd. NSW Australia
All rights reserved.
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.
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 OLIMEX – see
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.
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 Sketch
→ Import Library → Add 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.
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.
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
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
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.
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.
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
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
See the example sketches included with the library. They include a UNO bluetooth sketch, pfodEthernet and pfodEthernetWithPassword Also see A Simple WiFi/Arduino pfodDevice.
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.
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.
See the pfodSMS_SIM900 example sketch included with the library. It connects with pfodApp via SMS using a SIM900 based GPRS shield.
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
The General Purpose Android/Arduino Control App.
pfodDevice™ and pfodApp™ are trade marks of Forward Computing and Control Pty. Ltd.
Contact Forward Computing and Control by
©Copyright 1996-2024 Forward Computing and Control Pty. Ltd.
ACN 003 669 994