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

Forward Logo (image)      

pfod™ Parser Libraries
for Arduino

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

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

This page describes three libraries for Arduino which you can use to parse pfod messages sent from the pfodApp.

Which Library ZIP file to use?

For Version 2 of the library there is only one zip file which contains all the library files, pfodParser.zip It is code compatible with Version 1 of pfodParser.

Installation:

If you have previously installed any of the Version 1 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.

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.
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(pfodSMS* io)connects the parser to an SMS input stream, with no password specified. E.g parser.connect(&Serial); This is usually called from setup().

pfodSecurity.connect(pfodSMS* io, const __FlashStringHelper *hexKey) – connects the parser to an SMS 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(pfodSMS* io, const __FlashStringHelper *hexKey, int eepromAddress) – connects the parser to an SMS 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 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. 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 by returning ! from the parser. The sketch code should then close the connection to allow another connection to be authenticated. 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 close the connection to allow another connection to be connect and start authorization.

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



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