pfod™ Parser Library for LinkIt ONE

by Matthew Ford 2^nd February 2015
© Forward Computing and Control Pty. Ltd. NSW Australia
All rights reserved.

pfod™ LinkIt ONE Parser Library V2.4
(Protocol For Operations Discovery)
Libraries for LinkIt ONE to parse pfodApp messages.

This page describes the library for LinkIt ONE which you can use to parse pfod messages sent from the pfodApp.
The code generated by pfodDesigner V1.2.573+ needs this version of the pfodLinkIt library.

Which includes to use?

Install the pfodLinkIt library as described below and then

for the basic pfodLinkIt for bluetooth and wifi/ethernet connections with optional security use
#include <LEEPROM.h>
#include <pfodLinkIt.h>

OR
for pfod SMS parser with optional 128bit security use
#include <LEEPROM.h>
#include <pfodSMS_LinkIt.h>
#include <pfodLinkIt.h>

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

Version 2.4 fixes the getNextArg() method. This method is not used by the pfod code.
Version 2.3, this version, uses LEEPROM.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

Installation:

If you have previously installed any version of the library, pfodLinkIt, then find it in your libraries directory and delete the folder completely.

a) Then download this pfodLinkIt.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 Sketch → Import Library → Add Library to install it.
(If Arduino does not let you install it because the library already exists then find and delete the older pfodLinkIt folder and then import this one)

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

Library Reference:

pfodLinkIt

Description
pfodLinkIt 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
pfodLinkIt adds about 6300 bytes to the program and uses about 400 bytes RAM and 19 bytes of EEPROM

Methods

pfodLinkIt – no argument constructor

pfodLinkIt.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().

pfodLinkIt.connect(Stream* io, const __FlashStringHelper *hexKey) – connects the parser to an input stream, with a password specified. E.g pfodLinkIt.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.

pfodLinkIt.connect(Stream* io, const __FlashStringHelper *hexKey, int eepromAddress) – connects the parser to an input stream, with a password specified. E.g pfodLinkIt.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.

pfodLinkIt.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().

pfodLinkIt.connect(pfodSMS* io, const __FlashStringHelper *hexKey) – connects the parser to an SMS input stream, with a password specified. E.g pfodLinkIt.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.

pfodLinkIt.connect(pfodSMS* io, const __FlashStringHelper *hexKey, int eepromAddress) – connects the parser to an SMS input stream, with a password specified. E.g pfodLinkIt.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.

pfodLinkIt inherits from Print so you can use all the Print methods to write the responses back to pfodApp

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

pfodLinkIt.getFirstArg() – returns pointer to null terminated first arg if any, else if no args returns pointer to null.

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

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

pfodLinkIt.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* pfodLinkIt.getPfodAppStream() – returns a pointer to the Stream that is connected to this parser.

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

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

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

pfodLinkIt.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. LinkItLedBluetooth, LinkItLedWifi

pfodSMS_LinkIt NOTE: this class is still under development...
and will be functional in a later version of this library

Description
pfodSMS_LinkIt for LinkIt ONE is a subclass of pfodSMS and handles the SMS messages to and from a LinkIt One.
See Reliable Remote Control via SMS with pfodSMS for the details of the design.

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

Methods

pfodSMS_LinkIt – no argument constructor

pfodSMS_LinkIt.init(Stream* io) – connects the pfodSMS_LinkIt to the GPRS input stream E.g pfodSMS.init(&Serial); This is usually called from setup().

pfodSMS_LinkIt.init(Stream* io, int powerResetPin) – connects the pfodSMS_LinkIt 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_LinkIt.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_LinkIt.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_LinkIt example sketch included with the library.

Android^TM 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