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

Forward Logo (image)      

pfod™ Parser Library
for Arduino

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

pfod™ Parser Libraries V2.6
(Protocol For Operations Discovery)
Libraries for Arduino to parse pfodApp messages.

This page describes the library for Arduino which you can use to parse pfod messages sent from the pfodApp.
The code generated by pfodDesigner V1.2.573+ needs pfodParser library V2.4+.

There is also a pfodLinkIt library available here for the LinkIt ONE card

Which includes to use?

Install the pfodParser library as described below and then

for the basic pfodParser for bluetooth and wifi/ethernet connections without security use
#include <EEPROM.h>
#include <pfodParser.h>

OR
for pfod parser with optional 128bit security use
#include <EEPROM.h>
#include <pfodSecurity.h>

OR
for pfod SMS parser with optional 128bit security use

#include <EEPROM.h>
#include <pfodSMS_SIM900.h>

#include <pfodSecurity.h>

OR
for pfod parser for use with ESP8266 AT command driven (with optional 128bit security) use

#include <EEPROM.h>
#include <pfodESP8266_AT.h>

#include <pfodSecurity.h>

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

Version 2.6 improves ESP8266_AT support, does not timeout if sending rawdata.
Version 2.5 allows more time for SMS/GPRS shield to connect to the network after powering up and fixes complier warnings and protects against enabling debugging without setting a debugOut stream. Adds support for ESP8266 AT command driven.
Version 2.4 fixes the getNextArg() method. This method is not used by the pfod code.
Version 2.3, this version, uses EEPROM.h and needs that include added to your sketch, as shown above.

Version 2.2 removes all the Atmel AVR 8bit assembler code and replaces it with C code. The library now compiles on all Arduino processors.
Version 2 has only one zip file which contains all the library files, pfodParser.zip

Installation:

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

a) Then download this pfodParser.zip zip file to your computer, move it to your desktop or some other folder you can easily find

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

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

Library Reference:

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

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 0, i.e never timeout 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 10sec. 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 for ever 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.

pfodESP8266_AT

Description
pfodESP2866 is designed for use with ESP8266-01 boards using the AT command set and connected to a hardware serial UART of an Arduino compatible board. Actual test hardware is Teensy LC using Serial1 at 9600 to connect to ESP8266-01 version no 0018000902-AI03 (i.e. AT cmd version No 0018), Vendor:www.ai-thinker.com Version:0.9.2.4. This version of the AT command set does NOT support static IP settings, only DHCP is supported

This version of the AT command performs a hardware reset before trying to connect to the AP. In testing the board eventually connected after a number of attempts. This library keeps retrying until the ESP8266-01 connects. When the ESP8266-01 connects to the AP the blue indicator flashes at 5 sec intervals.

The AT command set is difficult to use and although this library allows sending rawdata back to the pfodApp, it is not recommended as errors occur frequently. When an error is detected or the ESP8266-01 stops responding, this library performs hardware reset performed and the ESP8266-01 is re-initialized and re-connected to the AP.

To enable the hardware reset you need to connect one digital output to the ESP8266-01 reset pin and pass digital output pin number to the init(..) method.

Although ESP8266 supports up to 4 connections in server mode, only the first connection (number 0) has it data processed. Data from any other connection is just dropped, since pfod protocol only supports a single connection to the pfodDevice at a time.

This class is designed to be passed to pfodSecurity in place of the io Stream pointer.

pfodESP8266_AT together with pfodSecurity adds about 16600 bytes to the program and uses about 3000 bytes RAM and 19 bytes of EEPROM
Because of the RAM requirements pfodESP8266_AT cannot be used on an UNO. You need to use a Mega2560 or similar with more then 4K of RAM. This library was tested using an TeensyLC board.

Methods

pfodESP8266_AT – no argument constructor

pfodESP8266_AT.init(Stream* io, const char* ssid, const char* pw, int portNo, int resetPinNo)connects the ESP8266 board UART to the io stream of the Arduino, and sets the ssid and pw for the local network to connect to. It also sets the portNo for the ESP8266 to listen on for connections from pfodApp and specifies the digital output that drives the ESP8266 reset pin.
If the portNo is less than 1 or greater than 65534, port 23 is set as the server listen port.
If the reset pin of ESP8266 is not connected (
it is recommended that you DO connect the reset pin) then pass -1 for the resetPinNo and the software will only perform ESP8266 software resets.
E.g.
esp8266_at.init(&Serial1,"myNetwork","networkPassword",23, 2); // ESP8266 reset connected to digital pin D2.

pfodESP8266_AT.setIdleTimeout(unsigned long timeout)set the timeout in seconds, default 40. This should not be set to 0.
For connections to ESP8266 boards using the AT command set, if there is no pfod command, or raw data, for this many seconds (default 40) the connection is closed. If you want to keep the pfodApp connection open, you can specify a refresh interval in the pfod menu message or send raw data at intervals less than the timeout. See the pfodSpecification for details of the menu refresh. The pfodDesigner can also be used to set a refresh interval for a menu.

pfodESP8266_AT.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 pfodESP8266_AT example sketch included with the library. It connects with pfodApp via WiFi. You need to edit the sketch to set your WiFi network's ssid and password.



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