jaABlu

🇬🇧 English | 🇩🇪 Deutsch

Version Tests codecov License: MIT Node.js Home Assistant Shelly

The jaABlu script reads Jaalee JHT BLE temperature and humidity sensors using Shelly BLU Gateway devices as Bluetooth proxies and forwards the data to Home Assistant via MQTT Auto-Discovery.

• ✅ Full MQTT Auto-Discovery support – sensors are created automatically in Home Assistant
• ✅ 8 optional sensor entities per device: Temperature, Humidity, Battery, RSSI, Last Seen, Link Quality, Battery Low Warning, Data Age
• ✅ Configurable temperature unit – Celsius or Fahrenheit
• ✅ Online/Offline status – automatic detection via configurable timeout (default 5 minutes)
• ✅ Multi-sensor support – any number of Jaalee JHT sensors per Shelly BLU Gateway
• ✅ Configurable logging – DEBUG / INFO / WARN / ERROR
• ✅ Active BLE scanning – optimized for the Jaalee iBeacon format
• ✅ Optimized performance – MQTT caching, helper functions, reduced code duplication

• Shelly BLU Gateway (e.g. BLU Gateway, BLU Mini, BLU Pro) with Bluetooth enabled
• Home Assistant with a running MQTT broker (e.g. Mosquitto)
• MQTT Auto-Discovery enabled, Discovery prefix set to homeassistant (default)

1. Upload the script to your Shelly BLU Gateway

   In the web UI:

   • Settings → Scripts → Add script
   • Paste the contents of jaABlu.js
   • Enable the script

2. Enable Bluetooth on the Shelly

   • Settings → Bluetooth → Enable

3. Start the script

   • Settings → Scripts → jaABlu.js → Start
   • Optionally enable autostart for the script

4. Verify in Home Assistant

   • After a few seconds, new devices should appear under
     Settings → Devices & Services → MQTT.
   • Each Jaalee sensor will expose several entities (Temperature, Humidity, Battery, etc.).

The script can be configured through the CONFIG object:

const CONFIG = {
 // Temperature unit configuration
 temperature: {
 unit: 'celsius', // 'celsius' or 'fahrenheit'
 },
 mqtt: {
 enabled: true,
 discovery_prefix: 'homeassistant',
 device_prefix: 'jaABlu',
 // Optional diagnostic sensors (disabled by default)
 publish_rssi: true, // Signal strength (RSSI in dBm)
 publish_last_seen: true, // Last seen timestamp
 publish_link_quality: false, // Link quality in % (0-100)
 publish_battery_low: false, // Binary sensor for low battery warning
 publish_data_age: false, // Age of last data in seconds
 // Status & Timeout
 sensor_timeout: 300, // Seconds without update -> offline (5 min)
 timeout_check_interval: 120, // Check interval in seconds (2 min)
 battery_low_threshold: 20, // Battery percentage threshold for warning
 },
 knownDevices: {
 // Optional: Format: "mac-address": "friendly_name"
 // 'XX:XX:XX:XX:XX:XX': 'Living Room',
 },
};

Legend:

• ✅ = Always enabled
• 🔘 = Enabled by default (configurable)
• ⚪ = Disabled by default (can be enabled manually)

Choose between Celsius and Fahrenheit:

temperature: {
 unit: 'fahrenheit', // or 'celsius'
}

RSSI is automatically converted to a user-friendly percentage display (0-100%):

• 100% = Excellent signal (-30 dBm)
• 0% = No usable signal (-90 dBm)

Binary sensor for automations on low battery:

automation:
 - alias: 'Low Battery Notification'
 trigger:
 - platform: state
 entity_id: binary_sensor.jaalee_xxx_battery_low
 to: 'on'
 action:
 - service: notify.mobile_app
 data:
 message: 'Jaalee sensor battery is low!'

Monitor the freshness of sensor data - useful for diagnostics and timeout monitoring.

❌ No sensors/devices appear in Home Assistant

• Restart Home Assistant once after the script has been started.
• Verify that the MQTT broker is configured correctly in Home Assistant.
• Check the script logs for messages like "MQTT connected" and "MQTT Discovery published for: ...".

❌ Discovery topics missing on the MQTT broker

• Increase log level to DEBUG in the script:

  logLevel: LOG_LEVELS.DEBUG;

• Use an MQTT tool (e.g. MQTT Explorer) to check for topics like

  homeassistant/sensor/jaABlu_*/config
  

❌ Sensor shows "Unavailable"

• Check if the sensor is within Bluetooth range (Link Quality sensor can help)
• Adjust timeout settings if sensors transmit less frequently
• Data Age sensor shows how old the last data is

[INFO] jaABlu v1.3.0: MQTT connected 08:58:43
[INFO] jaABlu v1.3.0: BLE scanner already running 08:58:43
[INFO] jaABlu v1.3.0: Timeout monitoring started (interval: 120s) 08:58:43
[INFO] jaABlu v1.3.0: jaABlu parser initialized (v1.3.0) 08:58:43
[INFO] jaABlu v1.3.0: Log level: INFO 08:58:43
[INFO] jaABlu v1.3.0: Temperature unit: °C 08:58:43
[INFO] jaABlu v1.3.0: Optional sensors enabled: RSSI, Last Seen, Link Quality, Battery Low, Data Age 08:58:43
[INFO] jaABlu v1.3.0: Jaalee JHT found - MAC: XX:XX:XX:XX:XX:XX | Temp: 0.58°C | Humidity: 92.01% 08:58:44
[INFO] jaABlu v1.3.0: MQTT Discovery published for: XX:XX:XX:XX:XX:XX 08:58:52

jaABlu includes a comprehensive test suite with 37 unit tests covering all core functionality.

# Install dependencies
npm install
# Run all tests
npm test
# Run tests in watch mode (auto-rerun on changes)
npm run test:watch
# Generate coverage report
npm run coverage

• ✅ 37 test cases covering helper functions, BLE parsing, and edge cases
• ✅ 100% statement coverage
• ✅ 96.66% branch coverage
• ✅ Continuous Integration via GitHub Actions

jaABlu/
├── .github/workflows/
│ └── test.yml # CI/CD pipeline
├── test/
│ └── jaABlu.test.js # Unit tests
├── jaABlu-core.js # Testable core module
├── jaABlu.js # Production Shelly script
├── package.json # NPM configuration
└── README.md # Documentation

MIT License – see LICENSE © 2026 Arend Böhmer

https://github.com/arboeh/jaABlu