intial

CONTRIBUTING

@@ -0,0 +1,7 @@
+Thank you for your interest in improving this library.
+
+If you have any questions or have found a bug, please feel free to create an
+Issue on this project's GitHub page.
+
+Any suggestions for improvements are welcome as well. Please bring them up as
+an Issue or a Pull Request.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Microfire LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,38 @@
+HABridge
+======
+
+> Create a Home Assistant sensor from any hardware and send measurements with ESPNow or LoRa.
+
+#### Summary ℹ️
+
+This is a great solution for a send-only battery-operated Home Assistant device. 
+
+This library works in conjuction with the MQTT-Bridge project described [here](https://microfire.co/articles/lora-with-espnow) and [here](https://microfire.co/articles/espnow-with-esphome). An ESP32 device is programmed to receive ESPNow or LoRa messages, processes them and then creates an MQTT-based sensor for display in Home Assistant. 
+
+An ESP32 can be used for ESPNow messages, or any device with a LoRa radio can be used to send LoRa messages. 
+
+Only one-way messaging works, sensor-device to Home Assistant. The following types are supported.
+
+| Home Assistant  |  |
+| ------------------- | :--------: |
+| Sensor       |     ✅     |
+| Binary Sensor              |     ✅     |
+| Text Sensor              |     ✅     |
+
+* * *
+
+### Use
+1. Read about the Bridge portion of this from the links above
+2. Create your bridge device
+3. Use this library to create a sensor device
+* * *
+
+### Ask a question 🤙
+
+*   [Discord](https://discord.gg/rAnZPdW)
+*   [[email protected]](mailto:[email protected])
+
+* * *
+
+### Website
+[microfire.co](https://microfire.co)

examples/ESPNow/ESPNow.ino

@@ -0,0 +1,50 @@
+#include <Arduino.h>
+#include <HABridge.h>
+#include <ESPNowBridge.h>
+#define DEVICE_NAME "test_device"
+
+// This library is intended to work in conjuction with the ESPNow-MQTT Bridge project
+// as described here: https://microfire.co/articles/espnow-with-esphome
+
+// HABridgeSensor sends a measurement associated with a unit, like temperature in Celsius
+// the parameters are:
+// device name: a string that represents the device name (outside_temperature_box, livingroom_presence)
+// sensor name: the name of the sensor (outside_temp_f)
+// SensorClass: available SensorClass values are listed here: https://developers.home-assistant.io/docs/core/entity/sensor/#available-device-classes
+// SensorState: available SensorState values are here: https://developers.home-assistant.io/docs/core/entity/sensor/#available-state-classes
+// unit of measurement: a string that represents the unit being measured, (C, F) for display in Home Assistant
+// (optional) HA icon: an explanation of icons can be found here: https://www.home-assistant.io/docs/frontend/icons/
+// (optional) hardware board name for display within Home Assistant
+// (optional) board version for display in Home Assistant
+HABridgeSensor sensor(DEVICE_NAME, "temperature_sensor", HABridge::SensorClass::TEMPERATURE, HABridge::SensorState::MEASUREMENT, "C", "mdi:temperature-celsius");
+
+// HABridgeBinary sends a binary state, 1/0
+// the parameters are: device name, sensor name, (optional) icon, (optional) hardware board name, (optional) board version
+HABridgeBinary binary(DEVICE_NAME, "binary_sensor");
+
+// HABridgeText sends a text state, battery_charging, battery_hot, battery_discharging
+// the parameters are: device name, sensor name, (optional) icon, (optional) hardware board name, (optional) board version
+HABridgeText text(DEVICE_NAME, "text_sensor", "mdi:text");
+
+ESPNowBridge now;
+
+void setup()
+{
+    // start the ESPNow library
+    now.begin();
+}
+
+void loop()
+{
+    // After getting your sensor measurement (this demo just uses rand numbers) call HABridgeSensor::line(float, precision)
+    // ::send it to the bridge device
+    now.send(sensor.line(rand() % 20, 2));
+
+    // HABridgeBinary::line(bool)
+    now.send(binary.line(rand() % 2));
+
+    // HABridgeText::line(std::string)
+    now.send(text.line(rand() % 2 ? "charging" : "discharging"));
+
+    delay(5000);
+}

examples/LoRa/LoRa.ino

@@ -0,0 +1,62 @@
+#include <Arduino.h>
+#include <HABridge.h>
+#include <LoRaBridge.h>
+#define DEVICE_NAME "test_device"
+
+// This library is intended to work in conjuction with the ESPNow-MQTT Bridge project
+// as described here: https://microfire.co/articles/lora-with-espnow
+
+// HABridgeSensor sends a measurement associated with a unit, like temperature in Celsius
+// the parameters are:
+// device name: a string that represents the device name (outside_temperature_box, livingroom_presence)
+// sensor name: the name of the sensor (outside_temp_f)
+// SensorClass: available SensorClass values are listed here: https://developers.home-assistant.io/docs/core/entity/sensor/#available-device-classes
+// SensorState: available SensorState values are here: https://developers.home-assistant.io/docs/core/entity/sensor/#available-state-classes
+// unit of measurement: a string that represents the unit being measured, (C, F) for display in Home Assistant
+// (optional) HA icon: an explanation of icons can be found here: https://www.home-assistant.io/docs/frontend/icons/
+// (optional) hardware board name for display within Home Assistant
+// (optional) board version for display in Home Assistant
+HABridgeSensor sensor(DEVICE_NAME, "temperature_sensor", HABridge::SensorClass::TEMPERATURE, HABridge::SensorState::MEASUREMENT, "C", "mdi:temperature-celsius");
+
+// HABridgeBinary sends a binary state, 1/0
+// the parameters are: device name, sensor name, (optional) icon, (optional) hardware board name, (optional) board version
+HABridgeBinary binary(DEVICE_NAME, "binary_sensor");
+
+// HABridgeText sends a text state, battery_charging, battery_hot, battery_discharging
+// the parameters are: device name, sensor name, (optional) icon, (optional) hardware board name, (optional) board version
+HABridgeText text(DEVICE_NAME, "text_sensor", "mdi:text");
+
+// this is just a very thin wrapper of https://github.com/sandeepmistry/arduino-LoRa, all methods are exposed through LoRaBridge::
+LoRaBridge lora;
+
+void setup()
+{
+    // start SPI
+    SPI.begin(/*SCK*/ 5, /*MISO*/19,  /*MOSI*/27,  /*SS*/18);
+
+    // start the LoRa library with the additional pins to use the radio
+    lora.begin(/*SS*/18, /*LoRa RESET*/14, /*LoRa DIO0*/35);
+
+    // If you want to change any of these settings, be sure to read the datasheet for your radio module
+    // not all combinations work and it is hardware dependent
+    // additionally, some settings may not be permitted in your location
+    // lora.setSyncWord(0xF3);
+    // lora.setSpreadingFactor(12);
+    // lora.setCodingRate4(5);
+    // lora.setSignalBandwidth(250E3);
+}
+
+void loop()
+{
+    // After getting your sensor measurement (this demo just uses rand numbers) call HABridgeSensor::line(float, precision)
+    // ::send it to the bridge device
+    lora.send(sensor.line(rand() % 20, 2));
+
+    // HABridgeBinary::line(bool)
+    lora.send(binary.line(rand() % 2));
+
+    // HABridgeText::line(std::string)
+    lora.send(text.line(rand() % 2 ? "charging" : "discharging"));
+
+    delay(5000);
+}

library.json

@@ -0,0 +1,20 @@
+{
+  "name": "Microfire_HABridge",
+  "keywords": "home assistant, esphome, espnow, lora",
+  "description": "Create a Home Assistant sensor from any hardware and send measurements with ESPNow or LoRa.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/u-fire/HABridge.git"
+  },
+  "authors": [
+    {
+      "name": "Microfire LLC",
+      "email": "[email protected]",
+      "url": "https://microfire.co",
+      "maintainer": true
+    }
+  ],
+  "version": "1.0.0",
+  "frameworks": "arduino",
+  "platforms": "*"
+}

library.properties

@@ -0,0 +1,9 @@
+name=Microfire_HABridge
+version=1.0.0
+author=Microfire LLC
+maintainer[email protected]
+sentence=Create a Home Assistant sensor from any hardware and send measurements with ESPNow or LoRa.
+paragraph=This library works in conjuction with the MQTT-ESPnow/LoRa bridge project (https://microfire.co/articles/lora-with-espnow). 
+category=Sensors
+url=https://microfire.co
+architectures=*

src/ESPNowBridge.cpp

@@ -0,0 +1,39 @@
+#include <ESPNowBridge.h>
+
+uint8_t broadcastAddress[] = {0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF};
+
+bool ESPNowBridge::begin(uint8_t channel)
+{
+    esp_now_peer_info_t peerInfo = {};
+
+    esp_netif_init();
+    esp_event_loop_create_default();
+    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
+    esp_wifi_init(&cfg);
+    esp_wifi_set_storage(WIFI_STORAGE_RAM);
+    esp_wifi_set_mode(WIFI_MODE_STA);
+    esp_wifi_start();
+
+    if (esp_now_init() != ESP_OK)
+    {
+        return false;
+    }
+
+    esp_wifi_set_protocol(WIFI_IF_STA, WIFI_PROTOCOL_LR);
+    memcpy(peerInfo.peer_addr, broadcastAddress, 6);
+    peerInfo.channel = channel;
+    peerInfo.encrypt = false;
+
+    if (esp_now_add_peer(&peerInfo) != ESP_OK)
+    {
+        return false;
+    }
+
+    return true;
+}
+
+bool ESPNowBridge::send(std::string line)
+{
+    esp_now_send(broadcastAddress, reinterpret_cast<const uint8_t *>(&line[0]), line.size());
+    return true;
+}

src/ESPNowBridge.h

@@ -0,0 +1,13 @@
+#pragma once
+#include <cstring>
+#include <string>
+
+#include <esp_now.h>
+#include <esp_wifi.h>
+
+class ESPNowBridge
+{
+public:
+    bool begin(uint8_t channel = 1);
+    bool send(std::string line);
+};