Skip to main content

MG iSMART smart home integration, free and open source

MG iSMART integration for Gladys Assistant

MG cars (MG4, ZS EV…) via the SAIC iSMART cloud, Europe: battery, range, charge, locks, doors.

View on GitHubAll integrations

Shows your MG cars (MG4, ZS EV, MG5, Marvel R, MG4 XPower…) in Gladys, through the SAIC iSMART cloud (Europe), with the account of the MG iSMART app.

Unofficial API, never tested with a real account nor a real car. The integration talks to the gateway of the MG iSMART app, as the saic-ismart-client-ng library does. SAIC may change it without notice. Not affiliated with MG or SAIC Motor.

Before you start: a second account​

SAIC allows one session per account. When the integration signs in, the MG app on your phone is signed out, and the other way round. The simplest: create a second account (another e-mail) in the MG iSMART app, share the car with it from your main account, and give that second account to Gladys.

If you use the same account, the integration signs in again once per 24 hours at most when its session is taken. Taken again, it pauses: a new try 6 h later at the earliest, then every 24 h, and never less than 24 h after its last sign-in (the "Test the connection" button counts too). So it never signs the app out in a loop. Renewing the token when it expires is a sign-in too: it signs the app out when it uses the same account.

What you get​

One device per car of the account, with:

FeatureContent
BatteryState of charge in %
RangeIn km
Charge statusUnplugged, Plugged in not charging, Charging, Complete, Scheduled, Fault…
Charging / Plugged inYes or no
Charging powerIn kW while the car charges (0 otherwise)
OdometerIn km
LocksLocked or unlocked (read only)
Doors (4) and bootOpen or closed
Latitude, longitudePosition of the car, without history
Cabin temperatureIn °C
Climate (running)Yes or no, and its mode: off, fan only, on, front defrost
Last report of the carDate and time of the last report sent by the car
Last commandThe outcome of the last command or refresh
ButtonsRefresh now, Lock, Unlock, Open the boot, climate and charge (start, stop)

Energy: the gateway gives no reliable cumulative meter. The integration publishes no index and no consumption: the charging power is a plain sensor.

Position: published as two numbers, without history in Gladys, never written in the logs nor in /data.

The 12 V battery: spaced reads​

Each read wakes the car up, which then draws on its 12 V battery. Waking a parked car too often can drain that battery until the car no longer starts. So:

  • one read per car every 3 hours by default (60 minutes to 24 hours), every 30 minutes while charging only when the car really charges (plugged in, power above 0), and for 12 hours at most: then back to the normal interval;
  • a car that does not answer (30 seconds of waiting) is read again after the interval, then twice later after each silence (up to once a day): never in a loop. Meanwhile, the buttons of that car accept one click per hour (refresh or a command), which counts in the wake-up budget;
  • an error is never read again sooner than the interval;
  • each button press wakes the car up: "Refresh now" reads it, and each command reads it before acting. Presses are limited per car: 2 minutes apart at least, 6 per hour at most; beyond, the press is refused at once with a message;
  • the vehicle list (which does not wake the car) is read at start, then every 24 hours;
  • the time of the next read is kept in /data: a restart does not wake the car before its time.

Installation​

  1. Install the integration from the Gladys store.
  2. In its configuration, enter the e-mail and the password of the MG iSMART account (preferably the second one). The password is kept by Gladys in its database, never shown again, sent only to the MG iSMART gateway of SAIC, as its SHA-1 digest like the app does.
  3. Adjust the interval, the timezone (Europe/Paris by default) and the language of the names if needed.
  4. Save, then add the cars from the Discovery tab.

The Test the connection button signs in if needed and reads the vehicle list, without waking the cars (at most every 30 seconds). It also tries again at once after a stop.

Commands (all off by default)​

Each command is a button, never a switch: a "turn everything off", Google Home, Alexa, HomeKit or a "switch" scene action never reach them. A scene can press a button, only through an explicit action on that button, and only if its option is on.

ButtonOption to turn on
LockAllow locking
UnlockAllow unlocking
Open the bootAllow opening the boot
Start / stop the climateAllow the climate commands
Start / stop chargingAllow the charging commands

Unlocking and opening the boot work remotely, for anyone who can press the button in Gladys: leave these options off unless you need them.

How a command goes:

  1. Gladys gets the answer "accepted" at once (the gateway often takes more than 10 seconds, and Gladys waits 5 seconds only); "Last command" shows "reading the car first…".
  2. The integration reads the car again (which wakes it) and decides on that fresh state only, never on memory: a useless command (already locked, climate already on…) is not sent; an unknown state, a report more than 10 minutes old ("stale state"), a car that does not answer, a car not plugged in (for charging) refuse the command without sending it. An undated state is never read as "already done": the command is sent.
  3. The option is checked again right before sending; the command is sent once, never sent again after a failure.
  4. "Last command" gives the outcome: sent and confirmed by MG (for lock, unlock and climate, only when the state sent back matches), sent with the state not confirmed, sent with a failure reported by the car, sent but not confirmed (the gateway took it then stopped answering: check before trying again), refused by MG (before taking it), or not sent with the reason. The car is read again about 90 seconds later.

After a restart during a command, "Last command" says it was interrupted: check the state of the car.

One command at a time per car. The integration never sends a code (SMS, e-mail): it signs in with the e-mail and the password only.

Errors and limits​

  • E-mail or password refused: a stop, one new try after 6 h, then every 24 h. Saving new credentials or the test button try again at once.
  • Session taken by the app: see "a second account" above.
  • 429 (too many requests): a pause of 1 minute to 6 hours (15 minutes without a hint), for everything (reads, buttons, commands), kept across a restart.
  • Network, 5xx: a new try after the interval, never sooner.
  • /data keeps the MG session token, in clear, in a file readable by the container user only (0600), so also by the administrator of the machine and in the backups of the volume; never the e-mail, the password, the VIN nor the position. This token gives access to the car: it goes away when the integration is removed.
  • Only European cars (the gateway-mg-eu gateway) and the e-mail sign-in are supported (not the phone number yet).
  • Not supported yet: target temperature, heated seats and steering wheel, windows, sunroof, find my car, charge target, scheduled charging, charging port lock, alarms.
  • The logs never hold the password, the token, the VIN, the position, nor the text of the gateway's answers.
  • The id of each car in Gladys is pseudonymised: a truncated SHA-256 of the VIN. It is not anonymous: anyone who knows the VIN can compute it.

Credits​

Ported from saic-ismart-client-ng (SAIC-iSmart-API, MIT, version 0.10.0). Apache-2.0 license.

Configuration settings​

These are the settings MG iSMART asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Your MG iSMART accountsectionNoShows your MG cars (MG4, ZS EV, MG5, Marvel R…) in Gladys through the SAIC iSMART cloud (Europe): battery, range, charge, odometer, locks, doors and boot, position, cabin temperature, climate. Enter the e-mail and password of the MG iSMART app, preferably of a second account the car is shared with: SAIC allows one session per account, signing in here signs the app out. Each read wakes the car up: one read every 3 hours by default, every 30 minutes while charging. The commands (lock, unlock, boot, climate, charge) are buttons, each one off by default. Unofficial API, never tested with a real account nor a real car. Not affiliated with MG or SAIC.
MG iSMART e-mailstringYes
MG iSMART passwordsecretYesKept by Gladys in its database, never shown again, sent only to the MG iSMART gateway of SAIC (as its SHA-1 digest, like the app does).
Read interval (minutes)numberNoMinutes between two reads of each car (60 to 1440). Each read wakes the car up and draws on its 12 V battery: keep it long. While charging, a read every 30 minutes at most.
Allow lockingbooleanNoOff by default. On: the "Lock" button locks the car (after reading it: nothing is sent when it is already locked).
Allow unlockingbooleanNoOff by default, and better left off. On: the "Unlock" button unlocks the doors of the car, from anywhere, by anyone who can press it in Gladys (a scene included).
Allow opening the bootbooleanNoOff by default, and better left off. On: the "Open the boot" button unlocks the boot.
Allow the climate commandsbooleanNoOff by default. On: the two climate buttons start and stop the climate of the car (it draws on the traction battery).
Allow the charging commandsbooleanNoOff by default. On: the two charging buttons start and stop the charge of a plugged-in car.
Gladys timezonestringNoUsed for the time of the last report and of the command results. IANA name, e.g. Europe/Paris.
Language of the feature namesselectNoUsed for the feature names of the cars added from now on, for the status texts and for the command results.

How to install MG iSMART in Gladys​

  1. In Gladys, open Integrations: MG iSMART appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/lm1lc3n7/gladys-mg-ismart:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/LM1LC3N7/gladys-mg-ismart.

MG iSMART requires Gladys >=4.86.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

MG iSMART is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by LM1LC3N7, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on