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

Forward Logo (image)      

pfod™ Parser Libraries
for Arduino

by Matthew Ford 22nd April 2014 (original 29th September 2012) – updated parser library, added pfodCHAP, corrected Multi-Language in pfodCHAP examples
© Forward Computing and Control Pty. Ltd. NSW Australia
All rights reserved.

pfod™ Parser Libraries
(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.
(Updated libraries, 27
th March 2014, to handle new “close connection” message)
(Updated libraries, 22
nd April 2014, to correct multi-language example screen)

Which Library ZIP file to use?

There are 4 zip files on this page.

The first three zip files contain one library each and can be installed using Arduino 1.5.5 IDE menu option SketchImport LibraryAdd Library
pfodCmdParser.zip contains the smallest library nd only parses single byte commands and ignores all arguments. This is suitable for most bluetooth projects which only used navigation and menu buttons. It has no message security.
pfodParser.zip contains the a complete parser library that only parses multi-char cmds with arguments. Use this for any project that needs user input apart from menu buttons.
pfodCHAP.zip contains the a complete parser library with optional 128 bit security. Use this for any wifi and internet projects that need security. See A Simple WiFi Arduino pfodDevice for an example of its use. See Challenge and Response Security for Internet connected pfodDevices for the details on how the security is provided.

The last zip file is pfod_ArduinoLibaries.zip. This zip contains all of the above 3 libraries in one file, but has to be manually unzipped to your arduino/libaries directory. (Open the Arduino IDE File->preferences window to see where your local Arduino directory is). Do NOT use the Arduino IDE Add Library command. It does not work with this zip file.

Installation:

For pfodCmdParser.zip, pfodParser.zip and pfodCHAP.zip download them to your computer, move them to your desktop or some other folder you can easily find and then use Arduino 1.5.5 IDE menu option SketchImport LibraryAdd Library to install them. If you are not using Arduino 1.5.5 IDE, or if you are updating a previously installed library, you have to manually unzip the zip file to your arduino/libaries directory. (Open the Arduino IDE File->preferences window to see where your local Arduino directory is).

For pfod_ArduinoLibaries.zip file, download it and unzip it to your arduino/libaries directory. (Open the Arduino IDE File->preferences window to see where your local Arduino directory is). Do NOT use the Arduino IDE Add Library command. It does not work with this zip file and does not allow existing libraries to be updated. Unzipping the file manually, overwriting any existing files, is safest.

In both cases, stop and restart the arduino IDE and under File->Examples you should now see pfodCmdParser and pfodParser and pfodCHAP. Run the pfodCmdParser and pfodParser examples to test out these parsers. To test pfodCHAP parser using 128 security, you need wifi module for your Arduino board.

Library Reference:

pfodCmdParser

Description
pfodCmdParser for Arduino, parses { cmd } and return cmd found (first byte only) when receives }, otherwise return 0 if no complete msg yet. pfodCmdParser adds about 152 bytes to the program and uses about 3 bytes RAM

Methods

pfodCmdParser – no argument constructor, see example code

pfodCmdParser.parse(byte in) – parser, Parameters: byte, Returns: 0 if message not complete, else the first byte of the cmd.

Example

This pfodCmdParserTest illustrates its use and allows you to test it out. Also see Android Controlled Garage Door Remote

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 482 bytes to the program and uses about 260 bytes RAM

Methods

pfodParser – no argument constructor, see example code.

pfodParser.parse(byte in) – parses commands of the form {cmd} or { cmd ` arg1`arg2 ... } or { cmd ~ arg1 ~ arg2 … }
Parameters: byte in -- byte read from Serial port
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.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.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 *

pfodParser.writeToSerial(Stream* io_arg, byte* idxPtr) – writes null terminated bytes to the Serial stream.

Examples

This pfodParserTest illustrates its use and allows you to test it out. Also see Android Controlled LCD/LED Display.
The UnoStarter sketch lets you test out your Uno board's I/O from your Android mobile via bluetooth.

pfodCHAP

Description
pfodCHAP 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 challenge and response security, via a 128 bit secret password, which protects against unauthorized connections. Also 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
pfodCHAP adds about 2100 bytes to the program and uses about 400 bytes RAM

Methods

pfodCHAP – no argument constructor, see example code. PfodCHAP extends from Print and so supports all the print and write calls to write to the wifi link
pfodCHAP.init(Stream* io_arg, int eepromAddress, const __FlashStringHelper *hexKey)sets the output stream that writes to the wifi device, the eeprom address where the secret key and power cycle information is stored and the secret key (stored in Flash, program, memory)
pfodCHAP.setDebugStream(Stream* debugOut)sets the debug output stream, only used if you modify the library code to turn on debugging.
pfodCHAP.setIdleTimeout(unsigned long timeout)set the timeout in mS, which closes the connection if no commands received from the pfodApp. Default is 0. That is never timeout. Set to >0 if you want the connection to timeout (recommended).
pfodCHAP.getPfodAppStream()returns a pointer to the wifi output stream being used by pfodCHAP. Used for sending disconnection commands to the wifi device.
pfodCHAP.disconnected()call this after you forcibly disconnect the wifi link to let the parser know to expect a new connection.
pfodCHAP.connected()call this when a new connection is made, if you have a hardware indication of a new connection. It is not essential to call this method.

pfodCHAP.parse() – call this every loop of loop(). It reads any available bytes from the wifi stream and parses commands of the form
{cmd} hashcode or { cmd ` arg1`arg2 ... } hashcode or { cmd ~ arg1 ~ arg2 … } hashcode
It returns 0 if a complete message (with hashcode) has not been received yet.
It returns pfodCHAP::DisconnectNow (0xff) if the hash check fails and the link should be forcibly disconnected
Otherwise it returns the first byte of the parsed command.
If the return is non-zero and not pfodCHAP::DisconnectNow (0xff), the following methods return valid results.

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

pfodCHAP.getFirstArg() – returns pointer to null terminated first arg if any, else if no args returns pointer to null. To access the second and following arguments read the first argument upto the terminating null, step over the null and you will be pointing to the start of the next argument. If you have reached the end of the arguments (getArgsCount()) then the start of the next argument will point to null (/0)

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

pfodCHAP.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 *

and all the print and write methods available from the Print class.

Example

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



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