Skip to content
BranchesTags

Repository files navigation

Moixa - Home Assistant integration

hacs_badge License

Unofficial Home Assistant integration for the Moixa GridShare smart battery system. Polls the GridShare cloud API every 5 minutes and exposes power flow, battery state, and operation mode as Home Assistant entities.

Features

Sensors

Sensor Unit Description
Battery State of Charge % Current battery charge level
Home Consumption W Power currently being used in the home
Grid Import W Power drawn from the grid
Grid Export W Power exported to the grid
Solar Production W Power generated by solar panels
Battery Charging W Power flowing into the battery
Battery Discharging W Power flowing out of the battery
Forecast Consumption W Predicted home consumption for the next 30-min slot (next 24 h series in forecast attribute)
Forecast Solar Production W Predicted solar output for the next 30-min slot (next 24 h series in forecast attribute)
Current Intent What the battery is currently doing: Balancing, Charging / Discharging, or Idle (full 24 h intent schedule in schedule attribute)
Solar Production Energy kWh Cumulative solar energy generated (resets at 0 on fresh install; persists across HA restarts)
Grid Import Energy kWh Cumulative energy drawn from the grid
Grid Export Energy kWh Cumulative energy exported to the grid
Battery Charging Energy kWh Cumulative energy charged into the battery
Battery Discharging Energy kWh Cumulative energy discharged from the battery

Controls

Entity Type Description
Operation Mode Select Switch between Smart, Schedule, and Simple battery modes (weekly schedule plan in schedule attribute)

All entities share a single Moixa GridShare device in Home Assistant.

The two forecast sensors expose the full 24-hour ahead series (30-min slots) as a forecast state attribute - a list of {ts, W} dicts - useful for custom Lovelace cards or template sensors.

Requirements

  • Home Assistant 2024.11 or newer.
  • A Moixa / GridShare account (the email and password you use to log in to the GridShare mobile app).
  • HACS installed, or willingness to copy files manually.

Installation

Option A - HACS (recommended)

  1. In Home Assistant open HACS -> Integrations -> ... -> Custom repositories.
  2. Add this repository URL with category Integration.
  3. Find Moixa in the HACS integrations list and click Download.
  4. Restart Home Assistant.

Option B - Manual

  1. Copy the custom_components/moixa/ directory into your Home Assistant config directory so you end up with <config>/custom_components/moixa/__init__.py.
  2. Restart Home Assistant.

Configuration

  1. Go to Settings -> Devices & services -> Add integration.
  2. Search for Moixa and select it.
  3. Enter the email address and password from your GridShare account.
  4. The integration authenticates, discovers your site, and creates a device with seven sensor entities and one select entity.

There is no YAML configuration. All settings are managed through the UI.

Re-authentication

If your password changes or the session expires, Home Assistant will prompt you to re-authenticate. Open the integration notification or go to Settings -> Devices & services -> Moixa -> Re-authenticate.

Automation examples

Alert when battery is low

trigger:
  - platform: numeric_state
    entity_id: sensor.moixa_gridshare_battery_state_of_charge
    below: 10
action:
  - service: notify.mobile_app
    data:
      message: "Moixa battery below 10% - grid import likely soon."

Notify when exporting to grid

trigger:
  - platform: numeric_state
    entity_id: sensor.moixa_gridshare_grid_export
    above: 100
action:
  - service: notify.mobile_app
    data:
      message: "Exporting {{ states('sensor.moixa_gridshare_grid_export') }} W to the grid."

Switch to Smart mode at a set time

trigger:
  - platform: time
    at: "06:00:00"
action:
  - service: select.select_option
    target:
      entity_id: select.moixa_gridshare_operation_mode
    data:
      option: smart

Services (Actions)

Three services are registered under the moixa domain and are available in Developer Tools -> Actions and in automations.

moixa.set_operation_mode

Parameter Type Description
mode smart | schedule | simple Target operation mode

moixa.add_schedule_intent

Inserts a slot into the weekly schedule. The slot's duration is borrowed from the neighbouring slot.

Parameter Default Description
kind (required) balance, charge/discharge, or idle
duration_minutes (required) Length of the slot in minutes
position -1 (end) Index to insert before (-1 = append)
soc_min 0.1 Minimum SOC during this slot (fraction)
soc_max 1.0 Target SOC ceiling (fraction)
power_watts Required for charge/discharge kind

Slot indices can be read from the schedule attribute of select.moixa_gridshare_operation_mode.

moixa.remove_schedule_slot

Parameter Description
index (required) Index of the slot to remove (duration transferred to neighbour)

Example: free-energy charge window

Add a forced charge slot during an off-tariff window, switch to schedule mode for the duration, then return to smart mode:

automation:
  - alias: "Free energy: start forced charge"
    trigger:
      - platform: time
        at: "00:30:00"
    action:
      - service: moixa.add_schedule_intent
        data:
          kind: "charge/discharge"
          duration_minutes: 90
          power_watts: 2000
          soc_max: 1.0
      - service: moixa.set_operation_mode
        data:
          mode: schedule

  - alias: "Free energy: resume smart mode"
    trigger:
      - platform: time
        at: "02:00:00"
    action:
      - service: moixa.set_operation_mode
        data:
          mode: smart

Diagnostics

The integration supports Home Assistant's built-in diagnostics. Go to Settings -> Devices & services -> Moixa -> Download diagnostics to get a redacted snapshot of the latest sensor data and config entry (credentials are stripped automatically).

Development

Setup

git clone https://github.com/ifayers/ha-moixa
cd ha-moixa
python -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"

Run tests

pytest tests/ -v

pytest-homeassistant-custom-component provides the hass fixture and all HA testing infrastructure. All tests mock the Moixa API so no real credentials or network access are needed.

Library updates

The bundled moixa_py/ library is automatically synced from codebeetl/moixa-api by a nightly GitHub Actions workflow. When the upstream library changes, the sync workflow commits the updated files and the version-bump CI creates a new release automatically.

To trigger a manual sync: Actions -> Sync moixa-py library -> Run workflow.

Releases

Releases are fully automated. Every push to main that passes tests triggers the CI workflow, which:

  1. Bumps the patch version in manifest.json (e.g. 0.1.1 -> 0.1.2)
  2. Commits the updated manifest back to main
  3. Creates a GitHub release tagged with the new version

To trigger a release, just push to main. For a minor or major bump, manually edit manifest.json to the desired base version (e.g. 0.2.0) in the same commit - the automation will increment from there on the next push.

Project layout

custom_components/moixa/
    __init__.py          # entry setup / teardown
    config_flow.py       # credentials UI flow
    const.py             # domain, platforms, poll interval
    coordinator.py       # DataUpdateCoordinator + JTS parser
    diagnostics.py       # diagnostics support
    manifest.json        # HA / HACS metadata
    select.py            # operation mode select entity
    sensor.py            # power sensors, forecast sensors, intent sensor, energy sensors
    services.yaml        # service UI descriptions
    translations/
        en.json          # UI strings
    moixa_py/            # bundled GridShare API client (synced from codebeetl/moixa-api)
tests/
    conftest.py          # shared fixtures
    const.py             # mock data
    test_coordinator.py  # unit tests for JTS parsing
    test_config_flow.py  # config flow tests
    test_init.py         # setup / unload / error handling
    test_select.py       # operation mode select entity tests
    test_sensor.py       # sensor entity tests

Technical notes

  • Authentication: Moixa uses AWS Cognito SRP for login and SigV4-signed requests. All auth is handled by the bundled moixa_py library, which also refreshes tokens automatically on 401 responses. The coordinator additionally performs a full re-login on 403 responses (AWS identity credentials expire after ~1 hour).
  • Executor wrapping: The moixa_py library is fully synchronous (uses requests and boto3). Every API call runs in HA's thread-pool executor via async_add_executor_job to avoid blocking the event loop.
  • Poll interval: 5 minutes, 6 API calls per cycle (core readings, device status, operation mode, forecasts, schedule, intent time series). The GridShare API's latest-reading endpoint is not a real-time stream, so polling more frequently does not yield fresher data.
  • Energy sensors: The five *_energy sensors accumulate kWh using a trapezoidal approximation between polls. State persists across HA restarts via RestoreEntity. After a coordinator failure, the elapsed-time baseline is reset so the recovery poll does not over-count the outage gap. All five sensors are immediately available in the Energy Dashboard source picker - no manual helper setup required.
  • Operation mode: The GridShare platform manages a nightly AI-computed schedule (smart mode). Switching to simple or schedule hands control back to fixed rules or a user-defined schedule.

Disclaimer

This is an unofficial integration with no affiliation with Moixa Energy or its parent company Shell. It is based on reverse-engineered traffic from the GridShare mobile app. The API may change without notice.

About

Unofficial Home Assistant integration for Moixa battery installations

Topics

batteryhacshome-assistanthomeassistantintegrationmoixa

Resources

Readme
MIT license
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages