API - DeeEmm/DIY-Flow-Bench GitHub Wiki

API Overview

The controller can be interrogated via a simple serial API. All functions that are available in the WebUI are also accessible via the API using a simple state interrogation > response protocol.

You can access these responses by simply sending the appropriate character via the Serial Monitor in the Arduino IDE. Make sure that you don't send additional line endings (CR/LF).

The full command list is included below. There are also some additional debug functions that are only available to the API.

Using the serial monitor when initially putting your project together makes project testing much easier than having to use the WebUI

The API can easily be interrogated by third party applications.

NOTE: CRC is disabled by default but can be enabled in the configuration file

API Command List

API functions are accessed using the following commands. NOTE: API commends are case sensitive!

DIYFB API Commands
  ==============================
  API Response Format
  Command : Value : Checksum
  ==============================
  3 : 3.3V Voltage Value
  5 : 5V Voltage Value
  A : ADC Voltage Values Maf:pRef:pDiff:Pitot
  a : ADC Raw Values Maf:pRef:pDiff:Pitot
  B : Barometric Pressure
  C : configuration.json
  D : Differential Pressure value inH2O
  E : Enum1 Flow:Ref:Temp:Humidity:Baro
  e : Enum2 Pitot:Swirl
  F : Flow Value in CFM
  f : Flow Value in KG/H
  H : Humidity Value (%)
  I : IP Address
  J : JSON Status Data
  j : JSON Configuration Data
  K : MAF Data Key Value
  k : MAF Data Lookup Value
  L : Leak Test Calibration
  l : Leak Test
  M : MAF.json
  N : Hostname
  o : Active Orifice
  P : Pitot Value inH2O
  Q : MAF Data Max Value
  q : MAF Data Key Max Value
  R : Reference Pressure Value inH2O
  S : Status
  T : Temperature in Celcius
  t : Temperature in Fahrenheit
  U : Uptime in hhhh.mm
  V : Version
  v : Valve lift data in JSON format
  W : WiFi SSID
  X : xTask memory usage   
  ? : Help
  / : SPIFFS File List
  ~ : Restart ESP
  $ : Reset WiFi
  @ : Stream Status
  ! : Debug Mode
  + : Verbose Mode
  = : Status Mode
  < : Last Error
  ============================== 

NOTE: The above key can be viewed in the serial monitor by sending a '?' character

NOTE: A reduced command set is available whilst in boot loop mode.

API Response Format

The API response is standardised to allow easy decoding by third party applications. The response can be validated by both the response code and the checksum appended to the end of the response. The checksum can be disabled in the configuration settings.

The data portion of the response is delimited by the colon character (':') to allow the data to be more easily extracted using standard string manipulation functions. This technique also allows for variable data lengths and floating point responses to be used.

Example API request

API Request for software version ('V')

API Response 'V:1.1.20080705: 36095'

Response anatomy

The response comprises of two elements. The message data and the checksum

V:1.1.20080705:   36095

|-------------|   |---|  
 Message Data      CRC

The message data can be further broken down as follows: 'V' + ':' + '1.1.20080705' + ':'

Where:

• Response Code: 'V'
• Delimiter: ':'
• Data: '1.1.20080705'
• Delimiter: ':'

NOTE: The delimiter character can be set in the configuration file.

Checksum calculation

The checksum is calculated using a simple CRC function based on the built-in CRC functions of the ESP32 ROM CRC Library, which is the main library of the ESP3 software. It is calculated from the message data.

The checksum function is shown below

uint32_t API::calcCRC (const char* str) {

  CRC = (crc32_le(0, (const uint8_t*)str, 4));

  return CRC;
}

The checksum is then appended to the end of the message data.

A typical message data using the example above would comprise of 'V:1.1.20080705:'

The checksum is calculated and added using the code below:

      if (*apiResponseBlob != 0) {
        _message.blobPrintf("%s\n", apiResponseBlob);     
      } else if (*apiResponse != 0) {
        _message.serialPrintf("%s\n", apiResponse);    
      }else {
        //invalid response
        _message.serialPrintf("%s\n", "Invalid Response");
      }

The checksum is then appended to the message data and sent to the serial port which results in a response similar to the example we used above

V:1.1.20080705:36095

Checksum Validation

After receiving an API response, to validate the checksum it first needs to be split from the end of the response and stored for later comparison.

Using the example we used above:

V:1.1.20080705:   36095

|-------------|   |---|  
 Message Data      CRC

If decoding using an ESP32 the message data portion of the response can then be used to create a new checksum using the same function listed above.

newCRC = calcCRC(messageData);

The new checksum can then be compared to the stored checksum to validate that the data received has not changed or become corrupted.