JSON and MsgPack Interface

The library exposes a JSON and MsgPack interface. It makes developing a text-based interface extremely simple.

JSON is an easy way to send and receive formatted information. It is simple to use and human-readable.

MsgPack is like JSON, but uses binary serialization to achieve smaller messages than JSON (typically).

Overview

The library accepts simple text-based commands. A pH reading can be taken by sending ph for example. In response, a JSON response of {"ph":7.2} will be sent. Alternatively, a MsgPack response could be chosen instead.

Calibration can also be done. Some commands will take a parameter, for example, ps will return the single-point offset of a pH probe, but ps 7.0 will perform a single-point calibration using 7.0 as the calibration solution. The measured offset will then be sent back as a result.

Not every possible operation has a corresponding command, however the majority of things are covered. Adding functionality could easily be accomplished by looking at the class-implementation.

Why are there short, cryptic codes?

The messages were designed to be small, so they could fit in limited-space use cases like BLE characteristics, which can only be 20 bytes.

Example Use

Using any WiFi capable device, assume you have a WebSocket interface that can send and receive text. The device could listen for commands, such as to take a pH reading or perform a calibration routine. The device would receive and execute the command, and then return the result as a JSON or MsgPack response. The end-user application would receive the response, parse it, and update the information.

Class Use

Choose which resonse format, JSON or MsgPack and include the appropriate header files and declare an instance. Then run the ::begin() method. As a parameter, pass a uFire class. You can use any class initialization parameters you normally would.

When a command string is received, it is processed and executed by calling ::processJSON(String) or ::processMP(String).

processJSON() and processMP() both returns Arduino Strings with the response. Additionally, ::value contains a float-converted return value.

There is one option that can be set ::emptyPlaceholder which is an Arduino String type and used when a value would have been returned as NaN. For example, if there was no calibration information stored, it will by default return -. It can be changed by passing any alternate String. ::emptyPlaceholder = ".";

#include <uFire_pH_JSON.h>
#include <uFire_ORP_JSON.h>

uFire_pH_JSON ph;
uFire_ORP_JSON orp;
String json_response = ph.processJSON("ph");

ph.begin(new ISE_pH);
orp.begin(new ISE_ORP(0x3e));

String json_response = ph.processJSON("ph");

or

#include <uFire_pH_MP.h>
#include <uFire_ORP_MP.h>

uFire_pH_MP ph;
uFire_ORP_MP orp;

ph.begin(new ISE_pH);
orp.begin(new ISE_ORP(0x3e));

String mp_response = ph.processMP("ph");

pH Commands

The following is a list of the available commands, any parameters they take, and their return information.

Note the Response section gives the JSON response, if MsgPack is used instead, it is the equivalent information.

ph

Used to start a pH measurement:

Command:

ph

Parameters:

To take a temperature-compensated pH measurement, pass the temperature of the solution as a float value.

ph 22.3

Response

A float value will be returned.

{"ph":7.2}

pt

Used to start a temperature measurement:

Command:

pt

Parameters:

None

Response

A float value will be returned.

{"pt":23.2}

pc

Returns true or false if the board is connected.

Command:

pc

Parameters:

None

Response

A float value will be returned.

{"pc":true} or {"pc":false}

pr

Resets all calibration information to default values.

Command:

pr

Parameters:

None

Response

pr will be returned as an acknowledgment the command was received and executed.

{"pr":"pr"}

ps

Returns the single-point calibration information, if any. Performs a single point calibration if a parameter is passed.

Command:

ps

Parameters:

The pH of the calibration solution.

ps 7.0

Response

A float value will be returned with the calibration information.

{"ps":-12.4}

phrf

Returns the high reference calibration information. This is upper-end of a dual-point calibration procedure as the probe should read. If a parameter is passed, it performs a high-point calibration.

Command:

phrf

Parameters:

The pH of the calibration solution.

phrf 7.0

Response

A float value will be returned with the calibration information.

{"phrf":7.0}

phr

Returns the high reading calibration information. This is upper-end of a dual-point calibration procedure as read by the probe.

Command:

phr

Parameters:

None

Response

A float value will be returned with the calibration information.

{"phr":7.2}

plrf

Returns the low reference calibration information. This is lower-end of a dual-point calibration procedure as the probe should read. If a parameter is passed, it performs a low-point calibration.

Command:

plrf

Parameters:

The pH of the calibration solution.

plrf 4.0

Response

A float value will be returned with the calibration information.

{"plrf":4.0}

plr

Returns the low reading calibration information. This is lower-end of a dual-point calibration procedure as read by the probe.

Command:

plr

Parameters:

None

Response

A float value will be returned with the calibration information.

{"plr":4.3}

ORP Commands

o

Used to start an ORP measurement:

Command:

o

Parameters:

None

Response

A float value will be returned.

{"o":642.1}

ot

Used to start a temperature measurement:

Command:

ot

Parameters:

None

Response

A float value will be returned.

{"ot":23.2}

oc

Returns true or false if the board is connected.

Command:

oc

Parameters:

None

Response

A float value will be returned.

{"oc":true} or {"oc":false}

or

Resets all calibration information to default values.

Command:

or

Parameters:

None

Response

or will be returned as an acknowledgment the command was received and executed.

{"or":"or"}

oo

Returns the offset calibration information, if any. Performs a single point calibration if a parameter is passed.

Command:

oo

Parameters:

The pH of the calibration solution.

oo 400

Response

A float value will be returned with the calibration information.

{"oo":-12.4}

op

Returns the configured probe potential, if any. Records the probe potential if a parameter is passed. If there is probe-potential information stored, it is used to adjust the measured ORP value. This value is typically referred to as Eh.

Command:

op

Parameters:

The pH of the calibration solution.

op 245

Response

A float value will be returned with the calibration information.

{"op":245}