Super Soco Custom

Custom component for integrating your Super Soco or Vmoto Soco motorcycle into Home Assistant. It provides meaningful data like power status, battery percentage, location and a lot more.

Disclaimers

This integration is based on the Super Soco & Vmoto Soco APIs, so it needs a combination of official ECU and active SIM contract that's currently working and sending data to Super Soco or Vmoto Soco servers. If this is not your case then sadly there's little to no chance that this integration will work for you. To put it simple: if your mobile app is not working, this won't work either.

Please note that Super Soco & Vmoto Soco do not allow more than one client at a time, so any open session in the official app will be closed when using this integration (same as if you'd log in from a new device).

This integration is not officially a part of Super Soco or Vmoto Soco. Additionally, this is NOT endorsed by Super Soco or Vmoto Soco in any way. Super Soco and Vmoto Soco are trademarks of Vmoto Limited.

Installation

You can install this either using HACS (recommended way) or manually copying files:

Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
If you do not have a custom_components directory (folder) there, you need to create it.
In the custom_components directory (folder) create a new folder called super_soco_custom.
Download all the files from the custom_components/super_soco_custom/ directory (folder) in this repository.
Place the files you downloaded in the new directory (folder) you created.
Restart Home Assistant

Configuration

Configuration is done in the UI; go to "Configuration" -> "Integrations" click "+ Add Integration" and search for "Super Soco Custom", then enter your login credentials as you would do in the official app:

You can configure some extra options by clicking on "Configure" once the integration is up and running:

Supported entities

Power status and switch**
Battery percentage
Estimated range
ECU battery percentage
Current speed
Current location* (device tracker)
Current location via reverse geocoding* (from Open Street Map, disabled by default)
Current altitude (from Open Topo Data)
Current course in degrees
Current course in 8-point wind rose
Current distance from home* with direction of travel (stationary/towards/away from/arrived)
Current trip distance
Current GSM signal strength*
Current GPS accuracy*
Last GPS fix time
Last warning time* with title and content
Last trip time*, distance* and average speed* (requires native tracking history to be enabled; updates every 10 minutes at most)
Agreement (SIM card validity) start and end time**
Image URLs for both the vehicle and its logo**
Switches to enable/disable native tracking history and push notifications

* These entities include extra attributes with more details. ** These entities may not be available depending on native app support (Super Soco vs Vmoto Soco).

Known limitations

Only one vehicle can be seen by this integration (I'm not lucky enough to own two Super Socos, so I don't know how would that look in the API responses)
Vehicle diagnose can't be initiated from this integration, nor the resulting report be shown in HA
Vehicle model seen by this integration may not match the actual model (the same issue happens in the official app if your ECU has been replaced with another one intended for a different model)
ECU may always report a voltage level equal to zero (and hence zero battery percentage); the cause remains unknown

Roadmap

Increase test coverage
Add altitude and reverse geocoding cache
Allow speed threshold customization (this is used to filter out unwanted GPS noise when the vehicle is virtually still)
Allow update interval customization while the vehicle is powered on (instead of forcing a 5 seconds interval)
Add vehicle diagnosis for Vmoto Soco (Super Soco API doesn't support it)
Add detailed battery information for Vmoto Soco (Super Soco API doesn't support it)

Contributions are welcome!

If you want to contribute to this project please read the Contribution guidelines

Special thanks

Members of the Super Soco - Spain Telegram group who helped me testing this. Such nice and patient folks!
Home Assistant, HACS, Integration Blueprint, Open Street Map, Open Topo Data and many more for providing the software and APIs this is built upon: "If I have seen further, it is by standing on the shoulders of Giants." - Isaac Newton

drakhart / ha-super-soco-custom