Hoymiles MS integration

Overview

The ioBroker.hoymiles-ms adapter integrates Hoymiles MicroStorage systems (currently supporting the Hoymiles MS-A2 model) into ioBroker. This adapter enables monitoring and control of your Hoymiles MS-A2 energy storage system through the ioBroker platform.

The Hoymiles MS-A2 is a MicroStorage unit that combines solar inverter and battery storage capabilities. More information about the device can be found here.

Note: This adapter is not affiliated with Hoymiles and is an independent community project.

Features

• Real-time monitoring: Battery status, power consumption, grid interaction
• Energy tracking: Monitor energy production, consumption, and storage
• Grid monitoring: Track grid-connected and off-grid operations
• System statistics: Comprehensive overview of system performance
• Power control: Set and control power output levels
• Multiple device support: Handle multiple MS-A2 units simultaneously
• MQTT communication: Reliable communication via MQTT protocol

Prerequisites

Before setting up the adapter, ensure you have:

1. ioBroker system running (Node.js >= 20)
2. Hoymiles MS-A2 MicroStorage unit
3. S-Miles Home App installed on your mobile device
4. Network connectivity between ioBroker and MS-A2 unit
5. Free TCP port for MQTT communication (default: 1881)

Adapter Setup and Configuration

Step 1: Install the Adapter

Install the adapter through the ioBroker admin interface:

1. Open the ioBroker admin interface in your web browser
2. Navigate to the "Adapters" tab
3. Search for "hoymiles-ms" in the adapter repository
4. Click the "Install" button next to the adapter

Important: Never install ioBroker adapters using npm directly. Always use the ioBroker admin interface for proper installation and dependency management.

Step 2: Configure the Adapter

1. Open the ioBroker admin interface
2. Navigate to "Adapters" and find "hoymiles-ms"
3. Click on the configuration (gear) icon
4. Configure the following settings:

MQTT Server Configuration

Important Notes:

• The adapter currently operates only in MQTT server mode
• Authentication is not yet supported - ensure your network is secure
• Port 1881 is chosen to avoid conflicts with ioBroker.mqtt (1883) and ioBroker.shelly (1882)

Step 3: Save and Start the Adapter

1. Click "Save & Close" in the configuration dialog
2. Enable the adapter instance
3. The adapter will start and begin listening for MQTT connections

Hoymiles MS-A2 Device Setup

To connect your MS-A2 unit to the ioBroker adapter, you need to configure it using the S-Miles Home App.

Step 1: Open S-Miles Home App

1. Launch the S-Miles Home App on your mobile device
2. Ensure you're connected to the same network as your MS-A2 unit

Step 2: Access MQTT Configuration

1. Navigate to the Configuration page (gear icon in upper right corner)
2. Scroll down to find the "MQTT-Service" section
3. Enable the MQTT Service

Step 3: Configure MQTT Settings

Example Configuration:

• Server Address: 192.168.1.100 (replace with your ioBroker IP)
• Port: 1881
• Client Prefix: MSA
• Username: (leave empty)
• Password: (leave empty)

Step 4: Apply Settings

1. Save the MQTT configuration in the S-Miles Home App
2. The MS-A2 unit will restart its MQTT service
3. Check the ioBroker logs for connection confirmation

Operation and Data Flow

Data Update Intervals

The MS-A2 unit sends data at different intervals (these are defined by the Hoymiles API and cannot be configured):

• Configuration data: Sent once upon connection establishment
• Real-time data: Updated every 1 second
• System statistics: Updated every 5 minutes

Device Connection Status

• The adapter monitors device connectivity automatically
• Devices are considered offline if no data is received for 30 seconds
• Connection status is displayed in the info.online state

States Created by the Adapter

The adapter dynamically creates states based on the data received from your MS-A2 unit. States are organized in a hierarchical structure:

Device Information States

Battery States

Grid Connection States (Grid On)

Grid Connection States (Grid Off)

Inverter States

Real-time Data States

System Statistics States

Power Control States

Information States

EMS Control States

Power Control Functionality

The adapter provides power control capabilities through specific writable states:

Setting Power Output

To control the power output of your MS-A2 unit:

1. Set EMS Mode: First set ems_mode.command to mqtt_ctrl
2. Set Power Level: Write desired power value to power_ctrl.set
3. Valid Range: Power value must be between power_ctrl.min and power_ctrl.max
4. Step Size: Use power_ctrl.step for appropriate increments

Example Power Control

// Enable MQTT control mode
setState('hoymiles-ms.0.MSA_12345.ems_mode.command', 'mqtt_ctrl');

// Set power output to 500W (example)
setState('hoymiles-ms.0.MSA_12345.power_ctrl.set', 500);

Power Control Notes

• Power control is only available when the device is in mqtt_ctrl mode
• Power settings are applied immediately by the MS-A2 unit
• Monitor the real-time states to verify power changes
• Return to general mode to restore automatic operation

Multiple Device Support

The adapter automatically handles multiple MS-A2 units:

• Each device is identified by its unique client ID
• States are created dynamically for each connected device
• Device objects are organized under separate folders
• Online status is tracked individually for each device

Troubleshooting

Common Issues

Device Not Connecting:

1. Verify network connectivity between ioBroker and MS-A2
2. Check MQTT server configuration in adapter settings
3. Ensure port 1881 is not blocked by firewall
4. Verify MQTT settings in S-Miles Home App

States Not Updating:

1. Check device online status (info.online)
2. Verify timestamp updates (info.timestamp)
3. Check adapter logs for error messages
4. Restart adapter if necessary

Power Control Not Working:

1. Ensure EMS mode is set to mqtt_ctrl
2. Verify power value is within min/max range
3. Check that device is online and responding
4. Monitor real-time states for changes

Log Analysis

Enable detailed logging by setting the adapter log level to "debug" or "silly":

• Info level: Connection events and basic operations
• Debug level: Detailed MQTT communication
• Silly level: All MQTT messages and state updates

Network Requirements

• Port 1881/TCP: Must be accessible from MS-A2 to ioBroker
• Firewall: Ensure MQTT traffic is allowed
• Network stability: Stable connection required for reliable operation

FAQ

Q: Can I use a different MQTT port? A: Yes, configure any free port in the adapter settings and update the MS-A2 configuration accordingly.

Q: Does the adapter support authentication? A: Not yet. Authentication support is planned for future releases.

Q: Can I monitor multiple MS-A2 units? A: Yes, each unit will appear as a separate device with its own states.

Q: How often is data updated? A: Real-time data updates every second, system statistics every 5 minutes (controlled by Hoymiles API).

Q: Can I control charge/discharge schedules? A: Currently, only power output control is supported. Advanced scheduling may be added in future versions.

Q: What happens if the network connection is lost? A: The adapter will detect offline devices and mark them accordingly. Data will resume when connection is restored.

Q: Are there any limitations? A: The adapter is currently limited to read-only monitoring and basic power control. Advanced features depend on Hoymiles API capabilities.

Support and Contributing

For issues, questions, or contributions:

• GitHub Issues: Report issues here
• ioBroker Forum: Community support and discussions
• Documentation: This document and inline code comments

If you like this adapter, please consider a donation:

This adapter is an independent community project and is not affiliated with Hoymiles.

Changelog

0.2.2 (2026-01-10)

• (mcm1957) Subscription code has been fixed to allow operation with hoymiles mqtt v3.0
• (mcm1957) NOTE: TOU topics are not yet supported and raising warnings currently.

0.2.1 (2026-01-09)

• (mcm1957) ignore empty and invalid payloads. [#90]
• (mcm1957) Dependencies have been updated

0.2.0 (2025-08-23)

• (mcm1957) States are created dynamically now. So no states should be created if a system does not provide data for it (i.e slave micro storage).
• (mcm1957) State values are reset during startup now to prevent stale information.
• (mcm1957) Support to control power consumption and delivery has been added.
• (mcm1957) Dependencies have been updated

0.1.2 (2025-08-03)

• (mcm1957) Warnings raised from slave systems have been removed
• (mcm1957) Dependencies have been updated

0.1.1 (2025-07-27)

• (mcm1957) Handling of configuration has been corrected
• (mcm1957) Translations have been adapted

0.1.0 (2025-07-26)

• (mcm1957) initial release

License

MIT License

Copyright (c) 2025-2026 mcm1957 mcm57@gmx.at

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.