Merge pull request #16 from rubnium/dev

v1.0.0 First public release!

.github/workflows/generate_doxygen.yaml

@@ -0,0 +1,41 @@
+name: Doxygen GitHub Pages Deploy
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+            submodules: "true"
+
+      - name: Install Doxygen and Graphviz
+        run: |
+          sudo apt-get update
+          sudo apt-get install graphviz -y
+          wget https://www.doxygen.nl/files/doxygen-1.11.0.linux.bin.tar.gz
+          tar -xf doxygen-1.11.0.linux.bin.tar.gz
+          cd doxygen-1.11.0
+          sudo make
+          sudo make install
+
+      - name: Mover a la carpeta y ejecutar Doxygen
+        run: |
+          cd doxygen_files
+          doxygen Doxyfile
+          touch html/.nojekyll
+        shell: bash
+
+      - name: Deploy to GitHub Pages
+        uses: JamesIves/github-pages-deploy-action@v4.6.3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          branch: "gh-pages"
+          folder: "doxygen_files/html"
+          target_folder: false

.github/workflows/platformio_publish.yaml

@@ -0,0 +1,31 @@
+name: Publish PlatformIO Library
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+
+      - name: Install PlatformIO CLI
+        run: pip install platformio
+
+      - name: Verify PlatformIO project
+        run: platformio check
+        working-directory: library
+
+      - name: Publish Library
+        env:
+          PLATFORMIO_AUTH_TOKEN: ${{ secrets.PLATFORMIO_AUTH_TOKEN }}
+        run: platformio package publish --non-interactive
+        working-directory: library

README.md

@@ -3,19 +3,22 @@
 Este proyecto es el resultado del desarrollo del Trabajo de Fin de Grado para el Grado de Ingeniería Informática de la <a href="https://www.uclm.es/es/toledo/fcsociales/grado-informatica"><img src="https://esi.uclm.es/assets/uploads/2022/03/logo_uclm.png" alt="Universidad de Castilla-La Mancha" height="25em"/></a> en Talavera de la Reina. Realizado en julio de 2024 por Rubén Gomez Villegas, con la supervisión de los tutores Rubén Cantarero Navarro y Ana Rubio Ruiz, el proyecto se centra en el desarrollo de un protocolo de mensajería ligera para placas ESP32 basado en MQTT y utilizando ESP-NOW, culminando en una librería publicada en el registro de PlatformIO.
 
 Recursos de interés:
-- Memoria oficial: <insertar>
+- [Memoria oficial](/tfg_report/TFG_GomezRuben_ProtocoloESPNOWMQTT.pdf)
 - Tablero Trello utilizado para gestionar el proyecto: <https://trello.com/b/tWmPaG2l/lobomq-tfg>
-- Librería: <insertar>
+- Librería: <https://registry.platformio.org/libraries/rubnium/LoboMQ>
+- Manual web: <https://rubnium.github.io/LoboMQ>
 
 A continuación se detalla brevemente la herramienta.
 
 -----
 # LoboMQ
 
 <p align="center">
-	<img src="other_resources/LoboMQ_icon.png" width="90"/>
+	<img src="https://rubnium.github.io/LoboMQ/LoboMQ_icon.png" width="90"/>
 </p>
 
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/rubnium/library/LoboMQ.svg)](https://registry.platformio.org/libraries/rubnium/LoboMQ)
+
 LoboMQ is a lightweight protocol based on [MQTT](https://mqtt.org/) that runs over ESP-NOW on ESP32 boards, without the need for an Internet connection! 
 It allows the creation of topic-based message queues where messages are posted to a broker and subscribers receive them.
 
@@ -38,5 +41,20 @@ You should see the examples to get a better idea of how to use it.
 - Log filtering according to log level and log storage on SD card.
 - Ability to persist topics and subscribers of the broker on SD card. 
 
+## Message types and formats
+
+There are 3 types of messages exchanged depending on the action performed: SubscribeAnnouncement, UnsubscribeAnnouncement and PublishContent.
+
+<p align="center">
+	<img src="https://rubnium.github.io/LoboMQ/LoboMQ_packets.png" width="600"/>
+</p>
+
+- `type`: the type of message.
+- `topic`: the topic, limited to 24 characters.
+- `contentSize`: the size of the content.
+- `content`: the content, limited to 120 bytes.
+
+These messages are created and transmitted automatically with the `publish`, `subscribe` and `unsubscribe` functions.
+
 ## Why "Lobo"?
 A lobo or wolf is an animal known for its ability to communicate effectively with its pack, such as this protocol, that can convey messages quickly to multiple "canine" companions located at far distances.

doxygen_files/Doxyfile

@@ -74,7 +74,7 @@ PROJECT_ICON           = ../other_resources/LoboMQ_icon.png
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = paginaGenerada
+OUTPUT_DIRECTORY       = 
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create up to 4096
 # sub-directories (in 2 levels) under the output directory of each output format
@@ -1421,7 +1421,8 @@ HTML_EXTRA_FILES       = doxygen-awesome/js/doxygen-awesome-darkmode-toggle.js \
                          doxygen-awesome/js/doxygen-awesome-fragment-copy-button.js \
                          doxygen-awesome/js/doxygen-awesome-interactive-toc.js \
                          doxygen-awesome/js/doxygen-awesome-paragraph-link.js \
-                         doxygen-awesome/js/doxygen-awesome-tabs.js
+                         doxygen-awesome/js/doxygen-awesome-tabs.js \
+                         ../other_resources/LoboMQ_packets.png
 
 # The HTML_COLORSTYLE tag can be used to specify if the generated HTML output
 # should be rendered with a dark or light theme.

library/README.md

@@ -1,9 +1,11 @@
 # LoboMQ
 
 <p align="center">
-	<img src="other_resources/LoboMQ_icon.png" width="90"/>
+	<img src="https://rubnium.github.io/LoboMQ/LoboMQ_icon.png" width="90"/>
 </p>
 
+[![PlatformIO Registry](https://badges.registry.platformio.org/packages/rubnium/library/LoboMQ.svg)](https://registry.platformio.org/libraries/rubnium/LoboMQ)
+
 LoboMQ is a lightweight protocol based on [MQTT](https://mqtt.org/) that runs over ESP-NOW on ESP32 boards, without the need for an Internet connection! 
 It allows the creation of topic-based message queues where messages are posted to a broker and subscribers receive them.
 
@@ -26,5 +28,20 @@ You should see the examples to get a better idea of how to use it.
 - Log filtering according to log level and log storage on SD card.
 - Ability to persist topics and subscribers of the broker on SD card. 
 
+## Message types and formats
+
+There are 3 types of messages exchanged depending on the action performed: SubscribeAnnouncement, UnsubscribeAnnouncement and PublishContent.
+
+<p align="center">
+	<img src="https://rubnium.github.io/LoboMQ/LoboMQ_packets.png" width="600"/>
+</p>
+
+- `type`: the type of message.
+- `topic`: the topic, limited to 24 characters.
+- `contentSize`: the size of the content.
+- `content`: the content, limited to 120 bytes.
+
+These messages are created and transmitted automatically with the `publish`, `subscribe` and `unsubscribe` functions.
+
 ## Why "Lobo"?
 A lobo or wolf is an animal known for its ability to communicate effectively with its pack, such as this protocol, that can convey messages quickly to multiple "canine" companions located at far distances.

library/examples/BrokerExample/BrokerExample.ino

@@ -0,0 +1,43 @@
+/**
+ * LoboMQ Broker Example
+ * This broker example has both topic and subscriber persistence and
+ * whitelist access control enabled. The log messages are stored on the SD card.
+ * 
+ * https://github.com/rubnium/LoboMQ
+ */
+
+#include <LoboMQ/Broker.h>
+
+void setup() {
+	Serial.begin(9600);
+
+	//Create whitelist of the devices allowed to connect to the broker
+	MACAddrList *whitelist = new MACAddrList();
+	whitelist->addToList({0xAA, 0xBB, 0xCC, 0xDD, 0xEE, 0xFF}); //add 1 by 1
+	whitelist->addArrayToList((std::vector<String>){ //or multiple at once
+		"08:B6:1F:BA:04:F8", 
+		"C0:49:EF:CB:99:10"
+	});
+
+	//Choose logger:
+	//a. Serial monitor logger
+	//Elog *logger = initializeSerialLogger(BROKER, DEBUG);
+	//b. SD logger. In this case, pins are:
+	// - CD/Chip Detect: 22 (not used)
+	// - DO/MISO: 19
+	// - SCK/CLK: 18
+	// - DI/MOSI: 23
+	// - CS: 5
+	// - VCC: 3.3V
+	// - GND: GND
+	Elog *logger = initializeSDLogger(BROKER, 5, 18, 19, 23, DEBUG);
+	//c. No logger
+	//Elog *logger = disableLogger();
+
+	//Initialize broker
+	initBroker(whitelist, logger, true, 5);
+	//Default values are available:
+	//initBroker(BRO_DEFAULT_WHITELIST, BRO_DEFAULT_LOGGER, BRO_DEFAULT_PERSISTENCE, BRO_DEFAULT_CS_SD_PIN);
+}
+
+void loop() { }

library/examples/PublisherExample/.gitignore

@@ -0,0 +1,5 @@
+.pio
+.vscode/.browse.c_cpp.db*
+.vscode/c_cpp_properties.json
+.vscode/launch.json
+.vscode/ipch

library/examples/PublisherExample/PublisherExample.ino

@@ -0,0 +1,30 @@
+/**
+ * LoboMQ Publisher Example
+ * This publisher example publishes a random number every 2 seconds.
+ * 
+ * https://github.com/rubnium/LoboMQ
+ */
+
+#include <LoboMQ/PubSub.h>
+
+uint8_t brokerAddr[] = {0x24, 0xDC, 0xC3, 0x9C, 0x7E, 0x40}; //Broker MAC destination
+
+Elog *_logger;
+
+void setup() {
+  Serial.begin(9600);
+  randomSeed(analogRead(0)); //to generate random numbers
+
+	//Choose logger:
+	_logger = initializeSerialLogger(PUBLISHER, DEBUG);
+	//_logger = initializeSDLogger(...);
+	//_logger = disableLogger();
+
+  _logger->log(INFO, "Started publisher board on %s!", WiFi.macAddress().c_str());
+}
+
+void loop() {
+  int numberExample = random(101); //generates random number
+  publish(brokerAddr, "topic1", &numberExample, sizeof(numberExample), _logger);
+  sleep(2);
+}

library/examples/PublisherExample/platformio.ini

@@ -0,0 +1,13 @@
+[platformio]
+src_dir = .
+
+[env:run_test]
+platform = espressif32
+board = esp32doit-devkit-v1
+framework = arduino
+
+lib_ldf_mode = deep
+lib_deps = 
+	adafruit/Adafruit Unified Sensor@^1.1.14
+  adafruit/DHT sensor library@^1.4.6
+  symlink://../..

library/examples/SensorDemo_Broker/.gitignore

@@ -0,0 +1,5 @@
+.pio
+.vscode/.browse.c_cpp.db*
+.vscode/c_cpp_properties.json
+.vscode/launch.json
+.vscode/ipch

library/examples/SensorDemo_Broker/SensorDemo_Broker.ino

@@ -0,0 +1,28 @@
+/**
+ * LoboMQ Sensor Demo - Broker
+ * This example broker has topic and subscriber persistence enabled and
+ * whitelist access control disabled. The log messages are printed on the serial
+ * monitor.
+ * 
+ * SD module pins:
+ * - CD/Chip Detect: 22 (not used)
+ * - DO/MISO: 19
+ * - SCK/CLK: 18
+ * - DI/MOSI: 23
+ * - CS: 5
+ * - VCC: 3.3V
+ * - GND: GND
+ * 
+ * https://github.com/rubnium/LoboMQ
+ */
+
+#include <LoboMQ/Broker.h>
+
+void setup() {
+	Serial.begin(9600);
+	Elog *logger = initializeSerialLogger(BROKER, DEBUG);
+
+	initBroker(BRO_DEFAULT_WHITELIST, logger, true, 5);
+}
+
+void loop() { }

library/examples/SensorDemo_Broker/platformio.ini

@@ -0,0 +1,11 @@
+[platformio]
+src_dir = .
+
+[env:sensordemo_bro]
+platform = espressif32
+board = esp32doit-devkit-v1
+framework = arduino
+
+lib_ldf_mode = deep
+lib_deps = 
+  symlink://../..

library/examples/SensorDemo_Publisher/.gitignore

@@ -0,0 +1,5 @@
+.pio
+.vscode/.browse.c_cpp.db*
+.vscode/c_cpp_properties.json
+.vscode/launch.json
+.vscode/ipch