feat(MMM-SenseHat): add multi-instance support and screenshots

Author: EmanuelVasileGresnu

modules/MMM-SenseHat/MMM-SenseHat.js

@@ -0,0 +1,149 @@
+/* global Module */
+
+Module.register("MMM-SenseHat", {
+  defaults: {
+    updateInterval: 5000,
+    showTemperature: true,
+    showHumidity: true,
+    showPressure: true,
+    showOrientation: false,
+    temperatureUnit: "C", // "C" or "F"
+    roundValues: 1,
+    ledMatrixEnabled: true,
+    ledMode: "status", // "off" | "status" | "text"
+    ledText: "Hello from Sense HAT",
+    ledColor: [0, 255, 0],
+    criticalThresholds: {
+      temperatureHigh: 30,
+      temperatureLow: 10,
+      humidityHigh: 80,
+      humidityLow: 20
+    },
+    debug: false,
+    // Optional: override Python executable path on some systems (e.g., "/usr/bin/python3")
+    pythonPath: null
+  },
+
+  start() {
+    this.sensorData = null;
+    this.ready = false;
+    // Send configuration to node_helper and include our instance identifier for multi-instance safety
+    const payload = Object.assign({}, this.config, { identifier: this.identifier });
+    this.sendSocketNotification("SENSEHAT_CONFIG", payload);
+  },
+
+  getDom() {
+    const wrapper = document.createElement("div");
+    wrapper.className = "mmm-sensehat";
+
+    // Loading state
+    if (this.sensorData === null) {
+      wrapper.innerHTML = "Loading Sense HAT data...";
+      return wrapper;
+    }
+
+    const data = this.sensorData;
+
+    // Error state from backend
+    if (data && typeof data.error === "string" && data.error.trim() !== "") {
+      wrapper.innerHTML = `Sense HAT error: ${data.error}`;
+      return wrapper;
+    }
+
+    const hasAnyValue =
+      typeof data.temperature === "number" ||
+      typeof data.humidity === "number" ||
+      typeof data.pressure === "number" ||
+      (data.orientation &&
+        (typeof data.orientation.pitch === "number" ||
+          typeof data.orientation.roll === "number" ||
+          typeof data.orientation.yaw === "number"));
+
+    if (!hasAnyValue) {
+      wrapper.innerHTML = "Sense HAT: no sensor data (check hardware or drivers)";
+      return wrapper;
+    }
+
+    // Temperature
+    if (this.config.showTemperature && typeof data.temperature === "number") {
+      const t = this.config.temperatureUnit === "F" ? (data.temperature * 9) / 5 + 32 : data.temperature;
+      const tEl = document.createElement("div");
+      tEl.className = "small bright";
+      tEl.innerHTML = `${this.round(t)} °${this.config.temperatureUnit}`;
+      wrapper.appendChild(tEl);
+    }
+
+    // Humidity
+    if (this.config.showHumidity && typeof data.humidity === "number") {
+      const hEl = document.createElement("div");
+      hEl.className = "xsmall light";
+      hEl.innerHTML = `${this.round(data.humidity)} %`;
+      wrapper.appendChild(hEl);
+    }
+
+    // Pressure
+    if (this.config.showPressure && typeof data.pressure === "number") {
+      const pEl = document.createElement("div");
+      pEl.className = "xsmall light";
+      pEl.innerHTML = `${this.round(data.pressure)} hPa`;
+      wrapper.appendChild(pEl);
+    }
+
+    // Orientation
+    if (this.config.showOrientation && data.orientation) {
+      const o = data.orientation;
+      const oEl = document.createElement("div");
+      oEl.className = "xsmall dimmed";
+      const pitch = typeof o.pitch === "number" ? this.round(o.pitch) : "-";
+      const roll = typeof o.roll === "number" ? this.round(o.roll) : "-";
+      const yaw = typeof o.yaw === "number" ? this.round(o.yaw) : "-";
+      oEl.innerHTML = `P:${pitch}° R:${roll}° Y:${yaw}°`;
+      wrapper.appendChild(oEl);
+    }
+
+    return wrapper;
+  },
+
+  round(value) {
+    const places = Math.max(0, parseInt(this.config.roundValues || 0, 10));
+    const p = Math.pow(10, places);
+    return Math.round(value * p) / p;
+  },
+
+  socketNotificationReceived(notification, payload) {
+    if (notification === "SENSEHAT_DATA" && payload && payload.identifier === this.identifier) {
+      this.sensorData = payload;
+      this.updateDom();
+
+      // Optional LED status logic
+      if (this.config.ledMatrixEnabled && this.config.ledMode !== "text") {
+        // Only act when we have real numeric data and no error
+        const hasNumeric = typeof payload.temperature === "number" || typeof payload.humidity === "number";
+        if (!hasNumeric || (payload && typeof payload.error === "string" && payload.error.trim() !== "")) {
+          return;
+        }
+        const { temperatureHigh, temperatureLow, humidityHigh, humidityLow } = this.config.criticalThresholds || {};
+        let color = this.config.ledColor || [0, 255, 0];
+
+        if (
+          (typeof payload.temperature === "number" &&
+            (((temperatureHigh !== null && temperatureHigh !== undefined) && payload.temperature > temperatureHigh) ||
+              ((temperatureLow !== null && temperatureLow !== undefined) && payload.temperature < temperatureLow))) ||
+          (typeof payload.humidity === "number" &&
+            (((humidityHigh !== null && humidityHigh !== undefined) && payload.humidity > humidityHigh) ||
+              ((humidityLow !== null && humidityLow !== undefined) && payload.humidity < humidityLow)))
+        ) {
+          color = [255, 0, 0]; // red
+        } else {
+          color = [0, 200, 0]; // green
+        }
+
+        this.sendSocketNotification("SENSEHAT_LED_COMMAND", {
+          identifier: this.identifier,
+          mode: this.config.ledMode || "status",
+          color
+        });
+      }
+    }
+  }
+});

modules/MMM-SenseHat/README.md

@@ -1,43 +1,51 @@
-MMM-SenseHat
-============
+# MMM-SenseHat
 
-A 3rd‑party MagicMirror² module that integrates the Raspberry Pi Sense HAT. It reads sensor data (temperature, humidity, pressure, optional orientation) and can control the Sense HAT 8×8 RGB LED matrix for simple status indication or scrolling text.
+## Overview
+MMM-SenseHat is a third-party module for MagicMirror² that integrates the official Raspberry Pi Sense HAT.
+It displays sensor readings (temperature, humidity, pressure, and optional orientation) and can control the
+Sense HAT’s 8×8 RGB LED matrix for a status color or scrolling text.
 
-## Screenshot
-![MMM-SenseHat screenshot](images/how_its_working.png)
+- Sense HAT product page: https://www.raspberrypi.com/products/sense-hat/
+- Sense HAT documentation: https://www.raspberrypi.com/documentation/accessories/sense-hat.html
 
-Features
-- Display temperature, humidity, pressure, and optionally orientation (pitch/roll/yaw)
-- Periodic polling interval (configurable)
-- Optional LED matrix control: off, status color, or scrolling text
-- Basic threshold‑based LED status (green when normal, red when out‑of‑range)
+This is **not** a core/default MagicMirror module. Install it under: `modules/MMM-SenseHat`.
 
-Requirements
+## Features
+- Show temperature, humidity, and pressure
+- Optional orientation readout (pitch / roll / yaw)
+- Configurable polling interval
+- LED matrix control: off, status color, or scrolling text
+- Basic threshold-based LED status (green when normal, red when out of range)
+- Runs as a standard MagicMirror third-party module (folder: `modules/MMM-SenseHat`)
+
+## Requirements
 - Raspberry Pi with a Sense HAT attached
-- Python 3 with the official sense HAT library
+- MagicMirror² installed and running
+- Python 3 with the official Sense HAT library
 
-Install dependencies on the Raspberry Pi
+Install dependencies on the Raspberry Pi:
 ```bash
 sudo apt update
 sudo apt install -y sense-hat python3-sense-hat
 ```
 
-Installation (as a 3rd‑party module)
-1) Clone this module into your MagicMirror installation under `modules/MMM-SenseHat`:
+## Installation
+Clone this repository into your MagicMirror installation under `modules/MMM-SenseHat`.
 ```bash
 cd ~/MagicMirror/modules
 git clone https://github.com/YOUR_GITHUB_ACCOUNT/MMM-SenseHat.git MMM-SenseHat
 ```
 
-2) (Optional) Ensure the Python helper is executable:
+Optional: ensure the Python helper is executable:
 ```bash
 chmod +x ~/MagicMirror/modules/MMM-SenseHat/python/reader.py
 ```
 
-Configuration
-Add the module to your `config/config.js`:
+## Configuration
+Add the module to your `config/config.js` following standard MagicMirror style.
+Paste the following object into the `modules: []` array:
 ```js
-{
+const moduleEntry = {
   module: "MMM-SenseHat",
   position: "top_right",
   config: {
@@ -46,7 +54,7 @@ Add the module to your `config/config.js`:
     showHumidity: true,
     showPressure: true,
     showOrientation: false,
-    temperatureUnit: "C",
+    temperatureUnit: "C", // "C" or "F"
     roundValues: 1,
     ledMatrixEnabled: true,
     ledMode: "status", // "off" | "status" | "text"
@@ -59,33 +67,48 @@ Add the module to your `config/config.js`:
       humidityLow: 20
     },
     debug: false,
-    // Optional: override Python executable path if needed (e.g., "/usr/bin/python3")
-    // pythonPath: "/usr/bin/python3"
+    // Optional: override Python executable path (e.g., "/usr/bin/python3").
+    // For familiarity with MMM-PythonPrint, you can also use `pythonName` (alias of pythonPath).
+    // pythonPath: "/usr/bin/python3",
+    // pythonName: "/usr/bin/python3"
   }
-}
+};
+// Then insert `moduleEntry` into the modules array in your config.js
 ```
 
-How it works
-- Frontend (MMM-SenseHat.js): Displays data and optionally sends LED status commands based on thresholds.
-- Node Helper (node_helper.js): Spawns the Python helper to read sensors at a set interval and forwards LED commands to it. Respects `config.pythonPath` if provided.
-- Python Helper (python/reader.py): Uses `from sense_hat import SenseHat` to read sensors and control the LED matrix. Prints JSON to stdout in read mode.
-
-Troubleshooting
+## How it works (architecture)
+- Frontend (MMM-SenseHat.js)
+  - Renders the sensor values in the MagicMirror UI
+  - Shows clear states: loading, error, or data
+  - May send LED commands (status/text) back to the backend based on thresholds
+- Node helper (node_helper.js)
+  - Manages one polling loop per module instance (multi-instance safe)
+  - Spawns the Python helper on an interval to read sensors
+  - Forwards sensor JSON to the correct frontend instance via an `identifier`
+  - Accepts LED commands per instance and uses that instance’s config
+  - Respects `config.pythonPath` (or `pythonName`) to select the Python executable
+- Python helper (python/reader.py)
+  - Uses `from sense_hat import SenseHat`
+  - Reads sensors and prints JSON to stdout in `--read` mode
+  - Controls the LED matrix (status color, text, clear)
+
+## Troubleshooting
 1) Check that the Sense HAT is detected by the kernel
 ```bash
 ls -l /dev/i2c*
 dmesg | grep -i "sense"
 ```
-Expect:
+Expected:
 - `/dev/i2c-1` present
-- A line similar to: `fb1: RPi-Sense FB frame buffer device`
-- A joystick device entry for the Sense HAT
+- A line like `fb1: RPi-Sense FB frame buffer device`
+- A Sense HAT joystick device entry
 
 2) Probe I²C bus 1
 ```bash
 sudo i2cdetect -y 1
 ```
-On a working Sense HAT, you should see several non-"--" addresses (for example `1c`, `39`, `5c`, `5f`, `6a`). If everything shows `--`, the HAT might not be seated correctly or could be faulty.
+On a working Sense HAT, you should see several non-"--" addresses (e.g., `1c`, `39`, `5c`, `5f`, `6a`).
+If everything shows `--`, the HAT may not be seated correctly or could be faulty.
 
 3) Test using the official Python library
 ```bash
@@ -100,7 +123,7 @@ print("Pressure   :", sh.get_pressure())
 PY
 ```
 - If you get numeric values, the sensors are working.
-- If you see errors like `OSError: Humidity Init Failed`, there may be a contact problem on the header or a sensor issue.
+- If you see `OSError: Humidity Init Failed`, check the 40-pin header seating and try again.
 
 4) Check the LED matrix
 ```bash
@@ -115,15 +138,41 @@ sleep(1)
 sh.clear()
 PY
 ```
-If you don’t see LEDs:
-- Power off the Raspberry Pi.
-- Firmly press the Sense HAT onto the 40‑pin header (common on new boards).
-- Boot again and re‑run the test.
+If no LEDs appear:
+- Power off the Raspberry Pi
+- Firmly press the Sense HAT onto the 40-pin header (common on new boards)
+- Boot again and re-run the test
 
 5) What the MagicMirror module will show
-- "Loading Sense HAT data…" → Python helper hasn’t delivered any data yet.
-- "Sense HAT: no sensor data (check hardware or drivers)" → helper runs, but all sensor fields are null.
-- "Sense HAT error: …" → helper reported an explicit error (library missing, init failure, etc.).
+- "Loading Sense HAT data…" → Python helper hasn’t delivered any data yet
+- "Sense HAT: no sensor data (check hardware or drivers)" → helper runs, but all sensor fields are null
+- "Sense HAT error: …" → helper reported an explicit error (e.g., library missing, init failure). Errors are per instance.
+
+## Multiple instances
+You can place MMM-SenseHat in `modules:[]` multiple times, each with different options (e.g., different LED policies or intervals). The module tags all traffic with an `identifier` and the helper maintains one polling loop per instance, so configurations are isolated.
+
+Example with two instances (as part of your modules array):
+```js
+[
+  {
+    module: "MMM-SenseHat",
+    position: "top_right",
+    config: { updateInterval: 4000, ledMatrixEnabled: true, ledMode: "status" }
+  },
+  {
+    module: "MMM-SenseHat",
+    position: "bottom_right",
+    config: { updateInterval: 10000, ledMatrixEnabled: true, ledMode: "text", ledText: "Hello", ledColor: [0, 200, 255] }
+  }
+]
+```
+
+## Screenshots
+- images/mmm-sensehat-dashboard.png — UI screenshot of the module
+- images/mmm-sensehat-hardware_1.jpg — Raspberry Pi + Sense HAT setup
+- images/mmm-sensehat-hardware_2.jpg — Additional hardware photo
+
+Styling: the module wraps its DOM in a `div.mmm-sensehat`, so you can target `.MMM-SenseHat .mmm-sensehat` from your `custom.css` if desired.
 
-License
-MIT (follow the MagicMirror² project license)
+## License
+MIT — typical for MagicMirror third-party modules.