SwitchMaster - Open for Development
SwitchMaster was designed from day one to be flexible, expandable and easy to integrate with other systems.
As part of our move to open source, the communication protocols, firmware, hardware designs and supporting documentation are being released to the community.
This means you're free to build your own applications, integrations, dashboards and automation systems without requiring permission, subscriptions or access to proprietary APIs.
Build What You Want
SwitchMaster can be integrated into virtually any platform capable of communicating with Bluetooth or serial devices.
Potential applications include:
-
Custom mobile applications
-
Fleet management systems
-
Vehicle monitoring platforms
-
Caravan and RV automation
-
Marine monitoring systems
-
Home Assistant integrations
-
Raspberry Pi projects
-
ESP32 and Arduino projects
-
Industrial control systems
-
Custom touchscreen dashboards
-
Telemetry platforms
-
IoT and remote monitoring solutions
If you can send and receive data, you can integrate with SwitchMaster.
Complete Documentation
The platform documentation includes:
-
Communication protocols
-
Message formats
-
Command structures
-
PCB design files
-
Schematics
-
Firmware source code
-
Application source code
-
Hardware design files
-
Enclosure and case files
Nothing is hidden behind proprietary interfaces or closed APIs.
Future-Proof By Design
Vehicle electronics often remain in service for many years.
A common problem with modern control systems is dependence on a specific application, cloud platform or manufacturer. When support disappears, the hardware often becomes useless.
SwitchMaster was designed differently.
Because the platform is open, users can continue developing, maintaining and extending the system long into the future.
For Developers
Whether you're building a custom mobile application, integrating with an existing vehicle management system, creating a Home Assistant plugin or developing commercial products based on the platform, the tools and documentation are available.
Build exactly what you need.
Open Source. Commercial Hardware.
The SwitchMaster platform is open source and available to the community.
For customers who prefer professionally assembled hardware, MLT Industries will continue supplying boards, cases and accessories through our online store.
Bluetooth Protocols
The below is for the keen amongst us and not for the faint of heart. We have tried to include as much detail as possible here to make it a bit easier to get started and whilst we can't support everyone's developments, we'll be more than happy to provide clarification to questions and update this document as we go along. Right - let's get to it.
V2 BLE Characteristic Info
SwitchMaster
SERVICE_UUID "42574065-18ed-41e9-a723-b85ac1d74000"
SwitchMaster MAXI
SERVICE_UUID "42574065-18ed-41e9-a723-b85ac1d74500"
Characteristics
METRICS_CHARACTERISTIC_UUID - Open Tx for switches, voltage and currents and current averages
2ff2caa4-7932-44c6-b73a-a7cfb897400a
Notes:
Open characteriscitc, no BLE AUTH required.
Read and notify
DEV_CONFIG_CHARACTERISTIC_UUID - Device configuration items Tx and Rx
2ff2caa4-7932-44c6-b73a-a7cfb897400c
Notes:
Secure characteristic, BLE AUTH required.
Read and Write
SW_CONFIG_CHARACTERISTIC_UUID - Device configuration items Tx and Rx
2ff2caa4-7932-44c6-b73a-a7cfb897400d
Notes:
Secure characteristic, BLE AUTH required.
Read, write and notify
SET_SWITCHES_CHARACTERISTIC_UUID - Secure channel for switching outputs
2ff2caa4-7932-44c6-b73a-a7cfb897401a
Notes:
Secure characteristic, BLE AUTH required.
Read and Write
TIMERS_CHARACTERISTIC_UUID - Secure channel for channel timers
2ff2caa4-7932-44c6-b73a-a7cfb897401d
Notes:
Secure characteristic, BLE AUTH required.
Read, write and notify
LOCKS_CHARACTERISTIC_UUID - Secure channel for channel lockouts
2ff2caa4-7932-44c6-b73a-a7cfb897401e
Notes:
Secure characteristic, BLE AUTH required.
Read, write and notify
TEMPS_CHARACTERISTIC_UUID - Secure channel for channel timeouts
2ff2caa4-7932-44c6-b73a-a7cfb897401f
Notes:
Secure characteristic, BLE AUTH required.
Read, write and notify
V2 Charecteristic Structure Info
This section contains the structure of each BLE packet. Packets that meet the correct overall size requirements but with incorrect information may produce odd behaviour - restarting the SwitchMaster will return it to normal. The SwitchMaster will recognise and drop packets that are of the incorrect length or data type.
General Notes
MAX_CHANNELS: 5 for SwitchMaster, 10 for SwitchMaster MAXI
METRICS - METRICS_CHARACTERISTIC_UUID
Size: 18 bytes
uint16_t outputs; // output bitmask, LSB = Output1
uint8_t usb; // usb on or off. 0 = off, 1 = on
uint16_t voltage; // voltage in 1mV steps
uint16_t current; // current in 1mA steps
uint16_t last_hour; // average current the last hour in 10mA steps
uint16_t last_12; // average current the last 12 hours in 10mA steps
uint8_t override_active; // is there an override active? 0 = No, 1 = Yes
uint16_t ch_temps[3]; // Individual temperature value in Kelvin * 100 (-273K is 0°C)
SWITCH SETTINGS - SET_SWITCHES_CHARACTERISTIC_UUID
Size: 3 bytes
uint16_t setting; // output bitmask, LSB = Output1
uint8_t usb; // usb on or off. 0 = off, 1 = on
DEVICE CONFIGURATION - DEV_CONFIG_CHARACTERISTIC_UUID
Size: 65 bytes
uint8_t ble_adr[6]; // device mac
uint8_t ssid[20]; // WiFi and BLE SSID
uint8_t pass[32]; // Redundant from V1. No longer in use in V2. Still required.
uint32_t pin; // BLE pin
uint16_t lowcut; // global battery cutout value
uint16_t gbltempcutout; // global temperature cutout in °C * 100 (Recommend 85°C)
(INDIVIDUAL OUTPUT CONFIG- SW_CONFIG_CHARACTERISTIC_UUID
Size: 21 bytes
uint8_t mode; // Tells the characteristic what to do. 0 = read the received switch # from NVS. 1 = store received switch info to NVS.
uint8_t switch_number; // Switch Number for configuration
uint8_t switch_name[14]; // Switch name. Max 14 chars.
uint16_t voltage_cutin; // Voltage in mV for when this switch should cut in. (mV: 12.5v = 12500). 0 = disabled.
uint16_t voltage_cutout; // Voltage in mV for when this switch should cut out. (mV: 12.5v = 12500). 0 = disabled.
Note: To write info to the SwitchMaster individual outputs - set the mode to 1 and fill in the rest of the packet with the required info. Requesting the switch information on the board requires the 'mode' setting above to be 0. When received the SwitchMaster will reply with data in the following format:
Size: 20 bytes
uint8_t switch_number; // Switch Number for configuration
uint8_t switch_name[14]; // Switch name. Max 14 chars.
uint16_t voltage_cutin; // Voltage in mV for when this switch should cut in. (mV: 12.5v = 12500). 0 = disabled.
uint16_t voltage_cutout; // Voltage in mV for when this switch should cut out. (mV: 12.5v = 12500). 0 = disabled.
SWITCH LOCKOUTS - LOCKS_CHARACTERISTIC_UUID
Size: SwitchMaster = 15 bytes, Maxi = 30 bytes
uint16_t ch_lockout[MAX_CHANNELS]; // individual lockout value - 0 off. 1 locked
SWITCH TIMEOUTS - TIMERS_CHARACTERISTIC_UUID
Size: SwitchMaster = 20 bytes, Maxi = 40 bytes
uint16_t ch_timeouts[MAX_CHANNELS]; // individual timer cutout value
TEMPERATURE CONTROL - TEMPS_CHARACTERISTIC_UUID
Size: 7 bytes
uint8_t mode; // Tells the characteristic what to do. 0 = read the received temp info from NVS. 1 = store received temp info to NVS.
uint8_t ch_temp_switch; // temperature channel to switch from
uint8_t switching_condition; // the switching condition. 0 = off, 1=(if greater than switching value do x), 2=(if lower than switching value do x)
uint16_t switching_value; // Individual temperature value in Kelvin * 100 (-273K is 0°C)
uint8_t switch_on; // single number with which switch to turn on or off. 0 based. (Allows only one)
Note: To write info to the SwitchMaster temperature automations - set the mode to 1 and fill in the rest of the packet with the required info. Requesting the switch information on the board requires the 'mode' setting above to be 0. When received the SwitchMaster will reply with data in the following format:
Size: 6 bytes
uint8_t ch_temp_switch; // temperature channel to switch from 0, 1 or 2
uint8_t switching_condition; // the switching condition. 0 = off, 1=(if greater than switching value do x), 2=(if lower than switching value do x)
uint16_t switching_value; // Individual temperature value in Kelvin * 100 (-273K is 0°C)
uint8_t switch_on; // single number with which switch to turn on or off. 0 based. (Allows only one)