MMM-GoveeSmartHomeStatus

A MagicMirror module for displaying Govee smart home device status and information.

Repository: github.com/rroach3753/MMM-GoveeSmartHomeStatus

• Display list of Govee smart devices with live online and power state
• Display temperature and humidity when the device reports them
• Color-coded online/offline status indicators
• Source badges for connectivity path: CLOUD, LAN, LAN+, and HB (Homebridge)
• Real-time device list updates
• Refreshes update in place after the first render without flashing the module
• Configurable refresh interval
• Automatic recovery after temporary network or access-point outages
• Full-width bottom bar layout option for compact device display
• Compact multi-column card grid layout with 3-4 cards per row (ideal for side panels)
• Compact cards sorted by room name, then device name
• Lights summary showing on/off counts for detected lights
• Room summary showing on/total devices by room
• Customizable light detection keywords
• Appliance hiding with configurable keyword filters (enabled by default)
• Optional LAN Control discovery for local-network device visibility
• Homebridge power consumption integration — display live wattage on outlet cards sourced from the Homebridge REST API
• Optional monitor power control from Govee presence sensors exposed by Homebridge

• MagicMirror² installed and running
• A Govee account with supported devices
• A Govee Open API key (required for cloud or hybrid modes)
• Outbound HTTPS access to openapi.api.govee.com

For LAN Control mode:

• Enable LAN Control for each device in the Govee app
• Keep MagicMirror and Govee devices on the same local network/VLAN, or use cross-subnet targeting options below
• Allow local UDP multicast/broadcast discovery traffic

Note: This module now calls both Govee APIs: the device list endpoint and the per-device state endpoint. With large device counts, lower refresh intervals will consume your daily API quota faster.

1. Navigate to your MagicMirror modules directory:

   cd ~/MagicMirror/modules

2. Clone the repository from GitHub:

   git clone https://github.com/rroach3753/MMM-GoveeSmartHomeStatus.git

3. Navigate into the module directory:

   cd MMM-GoveeSmartHomeStatus

4. Install dependencies:

   npm install

1. Install using MMPM:

   mmpm install MMM-GoveeSmartHomeStatus

2. If your setup requires dependencies to be installed manually, run:

   cd ~/MagicMirror/modules/MMM-GoveeSmartHomeStatus
   npm install

1. Navigate to the module directory:

   cd ~/MagicMirror/modules/MMM-GoveeSmartHomeStatus

2. Pull the latest changes:

   git pull

3. Refresh dependencies (recommended after updates):

   npm install

mmpm update MMM-GoveeSmartHomeStatus

This module requires a Govee Open API key. Without it, device data cannot be loaded.

If you set GOVEE_LAN_CONTROL_ENABLED=true and GOVEE_LAN_ONLY=true in the MagicMirror server environment, you can run LAN discovery mode without an API key.

LAN-only mode is currently discovery-focused. Some devices may not report cloud-level telemetry fields (for example, power/temperature/humidity) unless cloud mode is also enabled.

Fallback behavior:

• In hybrid mode (GOVEE_LAN_CONTROL_ENABLED=true, GOVEE_LAN_ONLY=false), if LAN devStatus is unavailable for a device, the module keeps cloud state for that device.
• In LAN-only mode (GOVEE_LAN_ONLY=true), there is no cloud fallback.

1. Create or sign in to your Govee account at https://www.govee.com/.
2. Go to the Govee developer portal at https://developer.govee.com/ and apply for Open API access.
3. After approval, create/generate your API key from your Govee developer settings.
4. Set the key in the environment used to start MagicMirror:

export GOVEE_API_KEY="YOUR_GOVEE_API_KEY"
npm start

If you prefer, you can request/generate your API key directly in the Govee app:

1. Open the Govee Home app and sign in.
2. Go to Profile.
3. Open About Us.
4. Tap Apply for API Key (or Request API Key, depending on app version).
5. Submit the request and copy the generated key once approved/available.
6. Set the key as GOVEE_API_KEY in the MagicMirror process environment.

If you do not see the API key option in-app, update the app to the latest version and check the developer portal method above.

1. Set the Govee API key in the environment used to start MagicMirror:

   export GOVEE_API_KEY="YOUR_GOVEE_API_KEY"

2. Add this module block inside the modules array in config/config.js:

{
  module: "MMM-GoveeSmartHomeStatus",
  position: "top_right",
  config: {
    title: "Govee Devices",
    refreshInterval: 480000,
    showOnlineOnly: false,
    showPower: true,
    showTemperature: true,
    showHumidity: true
  }
},

3. Restart the complete MagicMirror process so the node helper receives GOVEE_API_KEY. For PM2 installations:

   pm2 restart MagicMirror --update-env

Secrets and privileged automation settings must not be placed in config/config.js. See Security for the server-only Homebridge, display-control, and outlet auto-off variables.

This feature uses Govee occupancy or motion sensor characteristics exposed by the Homebridge UI API to control the MagicMirror host's display. It is disabled by default and configured only through the MagicMirror server environment; it does not accept sensor names or power-control commands from config.js or browser socket messages.

• Any selected sensor reporting presence wakes the display on the next poll.
• The display turns off after all selected sensors report clear continuously for five minutes by default.
• Missing, ambiguous, or unreadable sensors pause the off timer. Homebridge request errors and long polling gaps reset it.
• The feature reads actual display state and verifies power commands. It uses Wayland wlr-randr or X11 DPMS through xset; unsupported environments report an error rather than silently switching backends.
• Stopping MagicMirror leaves the display in its current state. Keep SSH or another manual recovery path available before enabling display automation.

The selected sensor names must match exactly one Homebridge occupancy (00000071) or motion (00000022) characteristic. Names are case-insensitive and can match the accessory name or service name. If an accessory exposes multiple sensor services, use a unique service name. The Homebridge credentials and TLS settings are the same server-only settings used by the wattage feature.

Example for a Wayland-based mirror:

export PRESENCE_DISPLAY_ENABLED=true
export PRESENCE_DISPLAY_SENSOR_NAMES='["Hallway - Sensor"]'
export PRESENCE_DISPLAY_OFF_DELAY_MS=300000
export PRESENCE_DISPLAY_POLL_INTERVAL_MS=15000
export PRESENCE_DISPLAY_BACKEND=auto
export PRESENCE_DISPLAY_OUTPUT=HDMI-A-1

Install wlr-randr for Wayland or x11-xserver-utils for X11 if the required display command is missing. For Wayland, find the connector name with wlr-randr. MagicMirror must run as the logged-in desktop user with its WAYLAND_DISPLAY/XDG_RUNTIME_DIR or DISPLAY environment available.

LAN discovery can send privileged network probes, so its policy is accepted only from the MagicMirror server environment. Renderer configuration values with these names are ignored.

When upgrading from 2.x to 3.0.0, move renderer LAN settings to the launch environment using these replacements:

• enableLanControl -> GOVEE_LAN_CONTROL_ENABLED
• lanOnly -> GOVEE_LAN_ONLY
• lanDiscoveryTimeout -> GOVEE_LAN_DISCOVERY_TIMEOUT_MS
• lanDiscoveryTargets -> GOVEE_LAN_DISCOVERY_TARGETS
• lanStaticDevices -> GOVEE_LAN_STATIC_DEVICES

Discovery targets become a comma-separated IPv4/CIDR list; static devices remain an array encoded as JSON. Restart MagicMirror after updating its service/PM2 environment. LAN discovery stays disabled until explicitly enabled.

Socket status requests are validated, share one in-flight fetch, and reuse its success or error for at least 30 seconds before another fetch can begin. At most 32 routing IDs may await a fetch. LAN discovery rejects malformed packet shapes and retains at most 128 discovered devices per scan.

Secrets and privileged automation policy are server-only. Set them in the MagicMirror process environment; values placed in browser-side config.js or socket payloads are ignored. Renderer requests can request device status and Homebridge wattage enrichment, but cannot enable or retarget Homebridge writes. HOMEBRIDGE_URL must be an HTTPS origin without a path, query, fragment, or embedded credentials. Plaintext HTTP origins are rejected so Homebridge credentials and bearer tokens cannot cross the network unencrypted.

Presence-based display control is privileged physical-device automation. It remains disabled unless PRESENCE_DISPLAY_ENABLED=true; its sensor allowlist, timing, backend, and output are read only from the MagicMirror process environment. A malformed or incomplete enabled policy fails closed and logs an explicit error.

Homebridge HTTPS certificate verification is enabled by default. For a private certificate authority, set NODE_EXTRA_CA_CERTS to its PEM certificate. A trusted self-signed local installation can explicitly set HOMEBRIDGE_VERIFY_SSL=false, but using a trusted private CA is strongly preferred because disabling verification permits interception of Homebridge credentials and access tokens.

Privileged automation is disabled by default. To enable an automation, set its enable variable to true and provide every related policy variable in the server environment before restarting MagicMirror. Invalid or incomplete enabled policy fails closed and does not create a monitor.

See .env.example for a complete sample. How these variables are supplied depends on how MagicMirror is launched (for example, a systemd EnvironmentFile, PM2 environment settings, or shell exports).

The former config.js keys homebridgeAutoOff* no longer have any effect. Auto-off was previously enabled by default for eBike - Pro; after this security change it remains off until all six HOMEBRIDGE_AUTO_OFF_* variables are explicitly configured on the server. Existing Homebridge credentials, wattage display, and TLS settings are unchanged.

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "top_right",
   config: {
      title: "Govee Devices"
   }
},

Grouped compact cards use two dense rows in the full-width bottom bar. Room sections wrap only when necessary instead of extending into an off-screen horizontal strip.

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "bottom_bar",
   config: {
      fullWidthBottomBar: true,
      showTemperature: false,
      showHumidity: false
   }
},

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "top_right",
   config: {
      showLightsSummary: false,
      showRoomSummary: false,
      hideAppliances: false
   }
},

export GOVEE_LAN_CONTROL_ENABLED=true
export GOVEE_LAN_ONLY=false
export GOVEE_LAN_DISCOVERY_TIMEOUT_MS=4000

export GOVEE_LAN_CONTROL_ENABLED=true
export GOVEE_LAN_ONLY=true
export GOVEE_LAN_DISCOVERY_TIMEOUT_MS=5000

Tip: Use hybrid mode (GOVEE_LAN_CONTROL_ENABLED=true with GOVEE_LAN_ONLY=false) if you want LAN reachability plus richer cloud state data.

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "top_right",
   config: {
      refreshInterval: 120000,                 // Module refresh every 2 minutes
      cloudDeviceListRefreshInterval: 1800000, // Device list every 30 minutes
      cloudDeviceStateRefreshInterval: 120000  // Device state every 2 minutes
   }
},

With segmented refresh enabled, set refreshInterval to your fastest desired update cadence (usually the cloud state interval).

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "bottom_bar",
   config: {
      compactCards: true,
      maxCompactCards: 30,
      showRoomSummary: true,
      showLightsSummary: true,
      refreshInterval: 30000,                   // UI/LAN cadence every 30s
      cloudDeviceListRefreshInterval: 28800000, // Cloud list every 8h
      cloudDeviceStateRefreshInterval: 600000   // Cloud state every 10m
   }
},

This profile keeps local card responsiveness high while reducing cloud API calls. Set GOVEE_LAN_CONTROL_ENABLED=true, GOVEE_LAN_DISCOVERY_TIMEOUT_MS=5000, and GOVEE_LAN_DISCOVERY_TARGETS=10.0.10.0/24 in the server environment.

export GOVEE_LAN_CONTROL_ENABLED=true
export GOVEE_LAN_ONLY=false
export GOVEE_LAN_DISCOVERY_TIMEOUT_MS=5000
export GOVEE_LAN_DISCOVERY_TARGETS="10.0.10.0/28,10.0.10.97,10.0.10.101"
export GOVEE_LAN_STATIC_DEVICES='[{"ip":"10.0.10.63","deviceId":"05:36:5C:E7:53:E8:F7:24","deviceName":"Kitchen Strip","model":"H1401"},{"ip":"10.0.10.97","deviceId":"04:6E:5C:E7:53:CE:51:0E","deviceName":"Desk Lamp","model":"H1401"}]'

GOVEE_LAN_DISCOVERY_TARGETS accepts individual IPv4 addresses and CIDR ranges, and sends unicast scan packets to the expanded IP list in addition to multicast/broadcast.

For safety, CIDR expansion is capped at 512 unicast targets per refresh cycle.

GOVEE_LAN_STATIC_DEVICES adds known devices even when cross-subnet UDP replies are blocked.

Compact cards are grouped into room sections by default. Device names that begin with the inferred room and roomNameDelimiter display only their local label, such as Couch Left instead of Living Room - Couch Left. Devices remain alphabetical within each room, and Unassigned is placed last.

When maxCompactCards is lower than the device count, selection rotates across rooms so later rooms are not excluded entirely. Room headings continue to show counts for all matching devices.

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "bottom_bar",
   config: {
      compactCards: true,
      fullWidthBottomBar: true,
      maxCompactCards: 40,
      groupCompactCardsByRoom: true,
      roomOrder: ["Living Room", "Office", "Primary Bath", "Bedroom"],
      showRoomSummary: true,
      showLightsSummary: true
   }
},

Set groupCompactCardsByRoom: false to restore the original flat compact-card grid. Set hideRoomSummaryWhenGrouped: false to display both room headings and the separate room summary.

Grouped cards default to compactRoomCardAlignment: "rows": cards fill across rows, with each row centered under its room heading, including incomplete rows. Choose "block" to preserve the previous grid arrangement (column-first in the bottom bar), "vertical" to preserve that arrangement and vertically center shorter groups, or "both" to center rows and vertically center shorter groups. This setting does not affect ungrouped cards. Bottom-bar groups still use at most two rows and retain the existing card widths.

Display the latest reported wattage on outlet device cards by connecting to the Homebridge REST API. Homebridge-Govee receives power data from the outlet via its AWS IoT channel and exposes it as a cached CurrentConsumption Eve characteristic. This module reads that value and the matching service's Homebridge On state on each refresh. The API does not provide a measurement timestamp, and reading it does not force a fresh device measurement; some models rely on pushed telemetry rather than periodic device polling. When Homebridge provides an explicit On value, it determines the displayed state; positive wattage is only used to infer ON when that state is unavailable. The wattage itself may still be stale. Outlets using Homebridge state display an HB source badge; if Homebridge is unavailable, unmatched, or lacks usable state, the existing Govee cloud or LAN-backed state remains in use.

The optional server auto-off policy can monitor one explicitly allowed Homebridge outlet and turn it off after an explicitly configured period of sustained low power. This local polling does not use the Govee OpenAPI and is independent of refreshInterval. It is disabled unless the complete server environment policy above is present. The monitor must first observe an on outlet drawing at least HOMEBRIDGE_AUTO_OFF_ARM_WATTS before low readings can start the shutoff timer. Startup zero/low-power readings do not arm it. Confirmed charging evidence is stored under the user's XDG state directory so it survives MagicMirror restarts during the same charging cycle; observing the outlet off disarms it. Legacy armed records without confirmed charging evidence are ignored and require a new arming-level reading after this update.

Auto-off requires an explicit Homebridge On state and valid, non-negative wattage; unlike the display, it does not infer outlet state from positive wattage. Missing or invalid telemetry, request errors, readings at or above the threshold, and gaps longer than twice the poll interval reset the low-power timer. Control uses unrounded wattage. Timer-start and successful shutoff logs include wattage and the configured threshold/duration.

Low power is only a completion heuristic, not a battery-percentage measurement. A charger can pause or taper before the battery is full. Measure its actual full-charge draw before choosing a threshold and duration; once armed, valid low readings below that threshold for the entire duration will still switch the outlet off. Repeated successful Homebridge API reads do not prove that the underlying wattage is fresh. Run only one MagicMirror instance to avoid independent automation timers.

Homebridge must run in insecure mode (-I) so config-ui-x can provide /api/accessories. In the Homebridge UI, open Settings, enable Homebridge Insecure Mode, and restart Homebridge. This setting allows local accessory API access; it does not disable Homebridge UI authentication.

The module matches Homebridge accessories to Govee devices by device ID, with a case-insensitive device-name fallback. No additional Homebridge plugins are required — only the built-in config-ui-x REST API.

Trust the exact local origin and configure Homebridge credentials only on the MagicMirror server:

export HOMEBRIDGE_URL="https://192.168.1.50:8581"
export HOMEBRIDGE_USERNAME="admin"
export HOMEBRIDGE_PASSWORD="yourpassword"
export HOMEBRIDGE_AUTO_OFF_ENABLED="true"
export HOMEBRIDGE_AUTO_OFF_DEVICE_NAME="eBike - Pro"
export HOMEBRIDGE_AUTO_OFF_THRESHOLD_WATTS="5"
export HOMEBRIDGE_AUTO_OFF_ARM_WATTS="20"
export HOMEBRIDGE_AUTO_OFF_BELOW_DURATION_MS="300000"
export HOMEBRIDGE_AUTO_OFF_POLL_INTERVAL_MS="30000"

If Homebridge is unreachable or returns an error the Govee devices still display normally; the wattage value is simply omitted.

In this layout:

• Summaries are centered horizontally above device cards
• Lights and room summaries render in a horizontal row
• Device cards are compact and fit into a maximum of 2 rows

This layout displays:

• Lights Summary — Total count of lights on/off (e.g., "7 on / 16 off")
• Room Summary — 2-column grid showing per-room device counts with color-coding:
  • Green border/text for rooms with at least one device ON
  • Gray border/text for rooms with all devices OFF
• Device Grid — Compact 3-column card layout showing all devices with name and power state (ON/OFF)
  • Green border indicates powered ON devices
  • Gray border indicates powered OFF devices
  • Source badge shows LAN+ (cloud+LAN merged), LAN (LAN-only), or CLOUD (cloud-only)
  • Perfect for side panels (bottom_right, top_right, etc.)

This illustrative comparison uses the module's grouped bottom-bar cards. Set compactRoomCardAlignment to one of these values:

1. "rows" (default) — Fill cards left to right across each row and center every row beneath its room heading. Incomplete rows are centered too, while shorter groups remain top-aligned.
2. "block" — Preserve the previous column-first bottom-bar arrangement, filling down each column before starting the next. Center the card block horizontally; incomplete rows are not centered separately, and shorter groups remain top-aligned.
3. "vertical" — Preserve the same arrangement as "block", but vertically center shorter card groups within the available space below their room headings. The single-card room makes this difference easiest to see.
4. "both" — Combine the row-first ordering and individually centered rows of "rows" with vertical centering for shorter groups.

For example, to select the fourth option:

compactRoomCardAlignment: "both",

These options require compactCards: true and groupCompactCardsByRoom: true. Ungrouped cards are unchanged.

The module classifies a device as a light when its name, type, or model contains a keyword from lightDetectionKeywords. This is used for the lights summary and for detecting light devices in room summaries.

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "top_right",
   config: {
      lightDetectionKeywords: ["light", "lamp", "bulb", "strip", "led", "sconce", "can", "uplight"]
   }
},

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "top_right",
   config: {
      lightDetectionKeywords: ["bulb", "strip"]
   }
},

The module automatically retries failed or timed-out requests with exponential backoff, capped at one attempt every 30 seconds. After the network or wireless access point becomes available, device updates should resume without restarting MagicMirror.

If updates do not resume after allowing time for the next retry, check the MagicMirror logs and verify DNS and API connectivity using the steps below. Restart MagicMirror after installing a module update so the updated browser and node helper code are loaded.

This error indicates your system cannot reach the Govee API server. Try these steps:

1. Check Network Connectivity

   ping -c 4 openapi.api.govee.com
   nslookup openapi.api.govee.com

2. Check Firewall/Network Access

   • Ensure your network allows HTTPS (port 443) outbound connections
   • Check if your ISP or network is blocking access to openapi.api.govee.com
   • Try disabling VPN or proxy if you're using one

3. Verify DNS Configuration

   cat /etc/resolv.conf

   Ensure you have valid DNS servers configured (e.g., 8.8.8.8, 1.1.1.1)

4. Test API Connectivity

   curl -H "Govee-API-Key: YOUR_API_KEY" https://openapi.api.govee.com/router/api/v1/user/devices

• Verify your API key is correct in config.js
• Check that there are no extra spaces or quotes around the key
• Regenerate your API key from the Govee app if unsure

• Verify you have Govee devices added to your account
• Ensure the devices are online and connected to WiFi
• Check that your API key has permissions to access device data
• If hideAppliances is enabled, appliance-like names such as ice maker or fridge may be filtered out intentionally

• The module calls the device list endpoint once per refresh plus one state request per returned device
• Example: 25 devices with an 8 minute refresh interval is about 4,680 requests per day
• Govee documents a 10,000 request per account per day limit, so avoid very short refresh intervals on larger device lists

If you use the default behavior, each cloud refresh makes:

1 + device_count

cloud requests, where device_count is the number of devices returned by the cloud device list.

If you enable segmented refresh, the rough daily request count is:

(list_refreshes_per_day * 1) + (state_refreshes_per_day * device_count)

For example, with 25 devices, a 30 minute device-list interval, and a 2 minute device-state interval:

• Device list calls per day: 24
• Device state calls per day: 25 * 720 = 18,000
• Total cloud requests per day: 18,024

That is a high-volume configuration and will exceed the 10,000 request limit.

Backward compatibility note: if both cloudDeviceListRefreshInterval and cloudDeviceStateRefreshInterval are 0, the module keeps the legacy behavior and refreshes both list and state on every module refresh.

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "top_right",
   config: {
      refreshInterval: 600000,                // UI refresh every 10 minutes
      cloudDeviceListRefreshInterval: 3600000, // Cloud device list every 60 minutes
      cloudDeviceStateRefreshInterval: 600000  // Cloud device state every 10 minutes
   }
},

This keeps the display responsive without hammering the cloud API. With 25 devices, it stays around 3,624 cloud requests/day.

{
   module: "MMM-GoveeSmartHomeStatus",
   position: "top_right",
   config: {
      refreshInterval: 300000,                // UI refresh every 5 minutes
      cloudDeviceListRefreshInterval: 1800000, // Cloud device list every 30 minutes
      cloudDeviceStateRefreshInterval: 300000  // Cloud device state every 5 minutes
   }
},

This is a balanced option for moderate device counts. With 25 devices, it stays around 7,224 cloud requests/day.

The module uses Node.js built-ins for HTTP and UDP, plus bonjour-service for optional Homebridge mDNS discovery.

npm ci --ignore-scripts
node --run lint
node --run test

Run development checks on Node.js 20.19 or newer. ESLint applies recommended common-error rules with separate browser and Node.js globals; CI runs lint and tests on Node.js 20, 22, and 24.

Homebridge networking and accessory mapping live in lib/homebridge.js; the helper retains the existing method entry points. Configuration and socket notification names remain unchanged. Stopping the helper cancels automation timers and LAN/mDNS discovery; late callbacks from the previous lifecycle cannot restart monitors or publish data. Automation still runs independently of whether the display is visible.

All CSS is now scoped beneath .mmm-govee-smartHome. Existing class names are retained, but custom overrides may need that wrapper prefix to match specificity. The legacy noApiKeyMessage option remains accepted but is unused; API errors are supplied by the server.

MIT

For issues, feature requests, or contributions, please visit the GitHub repository.

• Issues
• Discussions
• Pull Requests