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. An EC reading can be taken by sending ec for example. In response, a JSON response of {"ec":1.24} will be sent. Alternatively, a MsgPack response could be chosen instead.

Calibration can also be done. Some commands will take a parameter, for example, eo will return the single-point offset of an EC probe, but eo 1.413 will perform a single-point calibration using 1.413 as the calibration solution. The calibration data 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 an EC 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_EC_JSON.h>

uFire_EC_JSON ec;
String json_response = ec.processJSON("ec");

ec.begin(new uFire_EC);
ec.begin(new uFire_EC(0x3e));

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

or

#include <uFire_EC_MP.h>

uFire_EC_MP ec;

ec.begin(new uFire_EC);

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

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

ec

Used to start an EC measurement:

Command:

ec

Parameters:

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

ec 22.3

Response

A float value will be returned.

{"ec":1.2}

ect

Used to start a temperature measurement:

Command:

ect

Parameters:

None

Response

A float value will be returned.

{"ect":23.2}

ecc

Returns true or false if the board is connected.

Command:

ecc

Parameters:

None

Response

A float value will be returned.

{"ecc":true} or {"ecc":false}

ecr

Resets all calibration information to default values.

Command:

ecr

Parameters:

None

Response

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

{"ecr":"ecr"}

eo

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

Command:

eo

Parameters:

The EC of the calibration solution.

eo 1.413

Response

A float value will be returned with the calibration information.

{"eo":0.86}

ehrf

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:

ehrf

Parameters:

The EC of the calibration solution.

ehrf 12.88

Response

A float value will be returned with the calibration information.

{"ehrf":12.88}

ehr

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

Command:

ehr

Parameters:

None

Response

A float value will be returned with the calibration information.

{"ehr":12.11}

elrf

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:

elrf

Parameters:

The EC of the calibration solution.

elrf 1.413

Response

A float value will be returned with the calibration information.

{"elrf":1.413}

elr

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

Command:

elr

Parameters:

None

Response

A float value will be returned with the calibration information.

{"elr":1.22}

etc

Returns the temperature EC readings are compensated to. Sets the compensation temperature if passed as a parameter.

Command:

etc

Parameters:

None

Response

A float value will be returned.

{"etc":1.22}

eco

Returns the temperature coefficient that readings are compensated with. Sets the compensation coefficient if passed as a parameter.

Command:

eco

Parameters:

None

Response

A float value will be returned.

{"eco":0.019}