Package: victron-ble
victron_bleA Python library to parse Instant Readout advertisement data from Victron devices.Disclaimer: This software is not an officially supported interface by Victron and is provided entirely "as-is"Supported Devices:SmartShunt 500A/500mv and BMV-712/702 provide the following data:VoltageAlarm statusCurrentRemaining timeState of charge (%)Consumed amp hoursAuxilary input (temperature, midpoint voltage, or starter battery voltage)Smart Battery SenseVoltageTemperature (°C)Solar Charger (Tested with BlueSolar 75/15):Charger State (Off, Bulk, Absorption, Float)Battery Voltage (V)Battery Charging Current (A)Solar Power (W)Yield Today (Wh)External Device Load (A)If you'd like to support development for additional devices, considersponsoring this projectInstall it from PyPIpipinstallvictron_bleUsageTo be able to decrypt the contents of the advertisement, you'll need to first fetch the per-device encryption key from the official Victron application. The method to do this will vary per platform, instructions below:Fetching KeysOSXMacOS's bleak backenduses a bluetooth UUID address instead of the more traditional MAC address to identify bluetooth devices. This UUID address is often unique to the device scannedandthe device being scanned such that it cannot be used to connect to the same device from another computer.If you are going to usevictron-bleon the same Mac computer as you have the Victron app on, follow the instructions below to retrieve the address UUID and advertisement key:Install the Victron app from the Mac App StorePair with your device at least once to transfer keysRun the following from Terminal to dump the known keys (installsqlite3via Homebrew)❯sqlite3~/Library/Containers/com.victronenergy.victronconnect.mac/Data/Library/Application\Support/Victron\Energy/Victron\Connect/d25b6546b47ebb21a04ff86a2c4fbb76.sqlite'select address,advertisementKey from advertisementKeys inner join macAddresses on advertisementKeys.macAddress == macAddresses.macAddress'{763aeff5-1334-e64a-ab30-a0f478s20fe1}|0df4d0395b7d1a876c0c33ecb9e70dcd
❯If you are going to usevictron-bleon a different non-MacOS computer than the one with the Victron app (e.g. on a Raspberry Pi), follow these instructions to obtain the bluetooth MAC address and advertisement key instead:Install the Victron app from the Mac App StorePair with your device at least once to transfer keysRun the following from Terminal to dump the known keys (installsqlite3via Homebrew)❯sqlite3~/Library/Containers/com.victronenergy.victronconnect.mac/Data/Library/Application\Support/Victron\Energy/Victron\Connect/d25b6546b47ebb21a04ff86a2c4fbb76.sqlite'select macAddress,advertisementKey from advertisementKeys'a0f478020fe1|0df4d0395b7d1a876c0c33ecb9e70dcd
❯LinuxDownload the Victron AppImage app from the Victron website.Pair with your device at least once to transfer keysRun the following from a terminal to dump the known keys (installsqlite3via your package manager)❯sqlite3~/.local/share/Victron\Energy/Victron\Connect/d25b6546b47ebb21a04ff86a2c4fbb76.sqlite'select address,advertisementKey from advertisementKeys inner join macAddresses on advertisementKeys.macAddress == macAddresses.macAddress'A0:F4:78:02:0F:E1|0df4d0395b7d1a876c0c33ecb9e70dcd
❯WindowsDownload the VictronConnect installer from the Victron website and install.Pair with your device at least once to transfer keysOpen Explorer, navigate to%AppData%\Local\Victron Energy\Victron Connect\OpenSQLite Viewerin a web browser of your choiceDrag and drop thed25b6546b47ebb21a04ff86a2c4fbb76.sqlitefile from Explorer into the SQLite Viewer windowReading dataThe project ships with a standalone CLI that can be used to print device data to the console.# Will show all discovered Victron devices with Instant Readout enabled, their names, and IDs$>victron-blediscover763aeff5-1334-e64a-ab30-a0f478s20fe1:SmartShuntHT4531A246S
...# Dump data for a particular device (replace the ID and key with your own)$>victron-bleread"763aeff5-1334-e64a-ab30-a0f478s20fe1@0df4d0395b7d1a876c0c33ecb9e70dcd"INFO:victron_ble.scanner:Readingdatafor['763aeff5-1334-e64a-ab30-a0f478s20fe1']{"name":"SmartShunt HT4531A246S","address":"763AEFF5-1334-E64A-AB30-A0F478S20FE1","rssi":-79,"payload":{"aux_mode":"temperature","consumed_ah":0.0,"current":0.0,"high_starter_battery_voltage_alarm":false,"high_temperature_alarm":false,"high_voltage_alarm":false,"low_soc_alarm":false,"low_starter_battery_voltage_alarm":false,"low_temperature_alarm":false,"low_voltage_alarm":false,"midpoint_deviation_alarm":false,"remaining_mins":65535,"soc":100.0,"temperature":382.2,"voltage":12.87}}...# Dump data for debugging and supporting new devices (replace the ID)$>victron-bledump"763aeff5-1334-e64a-ab30-a0f478s20fe1"Dumpingadvertisementsfrom763aeff5-1334-e64a-ab30-a0f478s20fe11671843194.0534039:100289a302413bafd03bb245e131ae926267f6fd0b59e01671843194.682535:100289a302423baf58a1546e5262dcdf0ef642f353ed651671843197.676384:100289a302453baf804707549cffb2ab970c981ae897b6
...To consume this project as a library, you can import the particular parser for your device:fromvictron_ble.devicesimportdetect_device_typedata=<bleadvertisementdata>parser=detect_device_type(data)parsed_data=parser(<key>).parse(<bleadvertisementdata>)DevelopmentIf you'd like to help support a new device, collect the following and create a new Github issue:Runvictron-ble discoverto find the ID of the device you'd like to supportRunvictron-ble dump <ID>for a few minutes while collecting corresponding screenshots from the official apps instant readout to identify the current valuesFor pull requests:Read theCONTRIBUTING.mdfile.ContributorsSpecial thanks tohttps://github.com/rochacbruno/python-project-templatefor the project template