ESP SENSOR library

by Austin's Creations



This library wraps up an I2C bus scanner + MQTT handling for QWIIC/Stemma I2C sensors

The library Supports

  • BH1750 LUX sensor
  • SHT40 Temperature and Humidity Sensor
  • MCP9808 Temperature Sensor

Using this library means that config upon startup can be dynamic based on device configuration. All incoming and outgoing MQTT is handled by the library, minimizing required code in main sketch. The library also handles the JSON payload for the OXRS API/MQTT adoption code, saving from having to copy/paste extra code in your main sketch. The adopt code is also dynamic - disabling elements that aren't connected.


Library requires quite a few libraries

#include <Arduino.h>
#include <ArduinoJson.h>
#include <Wire.h>                     // For I2C
#include <Adafruit_MCP9808.h>         // For temp sensor
#include <Adafruit_SHT4x.h>           // For SHT40 Temp / humidity sensor
#include <BH1750.h>                   // For BH1750 lux sensor - non-adafruit library:


To use the library, ensure you have it downloaded/installed. The library is normally declared near the top of a sketch. After this is done the library instance needs to be called/set. Because the library uses I2C Wire.begin() should be called. You may need to include the SDA + SCL pin numbers in this declaration depending on hardware used.

#include <OXRS_SENSORS.h>           // Declare the library

OXRS_SENSORS sensors();             // Create library isntance

Wire.begin(SDA,SCL);                // Start I2C connection, but with different I2C pins

sensors.begin();                    // Start the Library - placed within SETUP()

There are also routines that need to be called within MQTT routines.

sensors.setConfigSchema(properties);  // Placed within main sketch ConfigSchema routine

sensors.setCommandSchema(properties); // Placed within main sketch CommandSchema routine

sensors.conf(json);                   // Placed within main sketch CONF callback routine

sensors.cmnd(json);                   // Placed within main sketch CMND callback routine

See the libraries built in examples to better see how and where to place routines and callbacks.

Program Loop

The main loop requires you to request any telemetry data, if if returned, to publish it.

  StaticJsonDocument<150> telemetry;

  if (telemetry.size() > 0)


The library can automatically handle incoming MQTT config payloads to control sensors.


The library can automatically handle incoming MQTT commands payloads to control sensors (none current supported).


The library will generate telemetry data in JSON format, ready for publishing.


These topics will be different if you set a topic prefix or suffix. E.g. a topic prefix of home and suffix of oxrs would result in a LWT topic of home/stat/<clientid>/oxrs/lwt

Publish APITopicRetainedDescription
publishTelemetrytele/<clientid>falsePublish a JSON telemetry message, e.g. when publishing regular sensor data


Download the latest version of the library on Githubopen in new window.

Supported Hardware

This library is compatible with ESP32 and ESP8266 microprocessors.


  • Austins Creations
  • Ben Jones


Found hereopen in new window.