Battery Monitor Device Connectivity and Remote Configuration Tool.
Sign in to like and favorite skills
Battery Monitor Device Connectivity and Remote Configuration Tool.
KHF-Net is a program designed to connect Junctek's KH-F series battery monitor devices to an MQTT broker using an RS485 bus interface. Its primary function is to facilitate seamless communication to these devices. KHF-Net is specifically designed to operate on the Linux platform. I might be portable to other operating systems by introducing additional work.
In addition to connecting devices, KHF-Net includes a telnet access feature to offer remote configuration capabilities for KH-F series devices. This functionality allows users to adjust settings remotely for convenient management. Furthermore this telnet interface serves for debugging purposes.
The program serves as a utility to bridge communication between the battery monitor devices and an MQTT broker while providing remote configuration and debugging functionalities.
It also supports networked serial ports, enabling remote connection to KH-F series battery monitor devices over a network. This feature expands connectivity options beyond physical serial ports.
This project is licensed under the European Union Public License 1.2 (EUPL-1.2). For the full license text see the
LICENSEgit clone <repository_url>
To build the project:
./build.sh
To clean the build artefacts in the build dir:
./clean.sh
To clean the build directory pristine:
./distclean.sh
If you prefer to do the build steps manually, here it is (out-of-source build):
mkdir -p build && cd build cmake -G "Unix Makefiles" .. make make install
Optional: Clean build artifacts (if needed):
make clean
A lot of aspects of the MQTT connection are configurable. See the command help output for details.
The serial port connection is also configurable. The most important option is the
--tty-path115200The program does no special RS485 handling on the serial port hardware. It is assumed, that all the bus direction handling is done in hardware or in the device driver. If some special settings are on the wish list, it should be easy to implement them.
The program is successfully tested with some FTDI-232 based RS485-to- USB adapters and with some CH340C RS485-to-USB adapters sold by Reichelt Eletronik
If someone has a serial port server, which is capable of raw 8-bit-mode (no telnet mode and no RFC-2217 mode), then the hostname and the TCP port number can be given, to access this serial port server.
Examples for using a serial port server might be the famous
ser2netAn other example is using
socatsocat /dev/ttyS1,b115200,raw,echo=0 tcp-listen:2020,reuseaddr
The
khf-net--help$ ./build/bin/khf-net --help KH-F series battery monitor network connector Valid options are: RS485 bus configuration: -d, --tty-path=PATH PATH to serial port device for RS485 bus (default: /dev/ttyUSB0) --baudrate=BAUD baudrate for the serial port, i.e. 115200 (default: 115200) --tty-net-host=HOSTNAME network HOSTNAME or IP, which provides serial port device, enables networked serial port mode --tty-net-port=PORT use TCP port number PORT for TTY access (raw mode only) (default: 2020) -i, --batt-poll-interval=ms battery poll interval (default: 1000) -t, --batt-comm-timeout=ms battery request timeout (default: 100) MQTT configuration: -h, --mqtt-broker=HOSTNAME HOSTNAME or IP of MQTT broker (default: localhost) -p, --mqtt-port=PORT PORT number at MQTT broker (default: 1883) --mqtt-client-id=CLIENT-ID CLIENT-ID at MQTT broker --mqtt-user=USER-NAME USER-NAME at MQTT broker --mqtt-pass=PASSWORD PASSWORD at MQTT broker --mqtt-clean-session open a clean session at the broker (default) --mqtt-continue-session continue a session at the broker (opposite of clean session) --device-topic=TOPIC MQTT device topic (default: khf-net) --cmd-prefix=PREFIX MQTT topic PREFIX for command subscriptions (default: cmd) --log-prefix=PREFIX MQTT topic PREFIX for log messages (default: log) --feedback-prefix=PREFIX MQTT topic PREFIX for command feedback messages and settings publication (default: feedback) --actuator-prefix=PREFIX MQTT topic PREFIX for actuator command subscriptions (default: actuator) --sensor-prefix=PREFIX MQTT topic PREFIX for sensor value publication (default: sensor) --online-prefix=PREFIX MQTT topic PREFIX for online message (default: connected) --online-suffix=SUFFIX MQTT topic SUFFIX for online message (default: LWT) --online-msg=MESSAGE MQTT online MESSAGE to publish on broker connection (default: online) --online-retain retain MQTT online message --lwt-prefix=PREFIX MQTT topic PREFIX for LWT message (default: connected) --lwt-suffix=SUFFIX MQTT topic SUFFIX for LWT message (default: LWT) --lwt-msg=MESSAGE MQTT offline MESSAGE to set as LWT message (default: offline) --lwt-retain retain MQTT offline message --sensor-refresh=min interval time in minutes for full sensor value array publication (0 = off) (default: 60) --disable-khf-devinfo-log disable KHF device information logging to MQTT --disable-khf-misc-log disable KHF miscelleneous logging to MQTT --disable-khf-settings-feedback disable KHF settings feedback to MQTT --disable-khf-configuration disable all KHF configuration commands from MQTT --disable-khf-relay-control disable KHF relays as actuators from MQTT Set MQTT online or offline suffix to empty string (''), to disable the message. Network shell configuration: --tap-net-port[=PORT] enable telnet TAP service (test access port) on PORT (default: 4223) Other configuration: --debug[=INT] enable debug output (default: 0) -h, --help display this help list and exit -V, --version print program version and exit debug flags: 0x00001 MQTT message log 0x00002 tty ctrl log 0x00004 KHF bus debug 0x00008 UART data . . .
(The output was shortened; the program also tells all the MQTT topics, it publishes and subscribes, which would be lengthy here. See section MQTT topics for more details on that.)
Please refer to the device manual, what all the detailed MQTT topics might be on, a lot of them is self-explanatory. So this is a list of the published and subscribed topics:
MQTT topic structure with default prefixes and device topic from command line configuration (@@ is placeholder for the device bus address without leading zero, i.e. '2' or '33'): connected/khf-net/LWT publishing the online state and LWT of khf-net actuator/khf-net/@@/relay subscription for relay control cmd/khf-net/poll_interval_ms subscription for poll_interval_ms command cmd/khf-net/comm_timeout_ms subscription for comm_timeout_ms command cmd/khf-net/scan_bus subscription for scan_bus command (no payload) cmd/khf-net/populate_address subscription for populate_address command cmd/khf-net/@@/reload_device_info subscription, command reloads device information cmd/khf-net/@@/refresh_all_measurements subscription, command sends all measurements (no payload) cmd/khf-net/@@/refresh_all_misc subscription, command sends all misc values (no payload) cmd/khf-net/@@/reload_settings subscription, command reloads all settings cmd/khf-net/@@/bus_address subscription for device control cmd/khf-net/@@/over_voltage_protection_mV subscription for device control cmd/khf-net/@@/under_voltage_protection_mV subscription for device control cmd/khf-net/@@/discharge_over_current_protection_mA subscription for device control cmd/khf-net/@@/charge_over_current_protection_mA subscription for device control cmd/khf-net/@@/over_power_protection_mW subscription for device control cmd/khf-net/@@/high_temperature_protection_degC subscription for device control cmd/khf-net/@@/low_temperature_protection_degC subscription for device control cmd/khf-net/@@/protection_delay_time_s subscription for device control cmd/khf-net/@@/protection_recovery_time_s subscription for device control cmd/khf-net/@@/battery_total_capacity_mAh subscription for device control cmd/khf-net/@@/voltage_calibration_factor_percent subscription for device control cmd/khf-net/@@/current_calibration_factor_percent subscription for device control cmd/khf-net/@@/temperature_calibration_offset_K subscription for device control cmd/khf-net/@@/clock_speed_calibration_factor_percent subscription for device control cmd/khf-net/@@/relay_normally_closed_mode subscription for device control cmd/khf-net/@@/empty_detection_voltage_mV subscription for device control cmd/khf-net/@@/full_charge_detection_voltage_mV subscription for device control cmd/khf-net/@@/full_charge_tail_current_percent_C subscription for device control cmd/khf-net/@@/full_charge_detection_time_s subscription for device control cmd/khf-net/@@/temperature_unit_is_farenheit subscription for device control cmd/khf-net/@@/ble_password subscription for device control cmd/khf-net/@@/data_logging_interval_s subscription for device control cmd/khf-net/@@/low_capacity_alarm_percent subscription for device control cmd/khf-net/@@/data_logging_enabled subscription for device control cmd/khf-net/@@/set_device_time subscription for device control cmd/khf-net/@@/manual_relay_setting subscription for device control cmd/khf-net/@@/trigger_current_zero_calibration subscription for device control cmd/khf-net/@@/trigger_factory_reset subscription for device control cmd/khf-net/@@/set_remaining_capacity_percent subscription for device control feedback/khf-net/poll_interval_ms publishing command feedback feedback/khf-net/comm_timeout_ms publishing command feedback feedback/khf-net/@@/relay publishing relay control feedback feedback/khf-net/@@/bus_address publishing device command feedback feedback/khf-net/@@/over_voltage_protection_mV publishing device command feedback feedback/khf-net/@@/under_voltage_protection_mV publishing device command feedback feedback/khf-net/@@/discharge_over_current_protection_mA publishing device command feedback feedback/khf-net/@@/charge_over_current_protection_mA publishing device command feedback feedback/khf-net/@@/over_power_protection_mW publishing device command feedback feedback/khf-net/@@/high_temperature_protection_degC publishing device command feedback feedback/khf-net/@@/low_temperature_protection_degC publishing device command feedback feedback/khf-net/@@/protection_delay_time_s publishing device command feedback feedback/khf-net/@@/protection_recovery_time_s publishing device command feedback feedback/khf-net/@@/battery_total_capacity_mAh publishing device command feedback feedback/khf-net/@@/voltage_calibration_factor_percent publishing device command feedback feedback/khf-net/@@/current_calibration_factor_percent publishing device command feedback feedback/khf-net/@@/temperature_calibration_offset_K publishing device command feedback feedback/khf-net/@@/clock_speed_calibration_factor_percent publishing device command feedback feedback/khf-net/@@/relay_normally_closed_mode publishing device command feedback feedback/khf-net/@@/empty_detection_voltage_mV publishing device command feedback feedback/khf-net/@@/full_charge_detection_voltage_mV publishing device command feedback feedback/khf-net/@@/full_charge_tail_current_percent_C publishing device command feedback feedback/khf-net/@@/full_charge_detection_time_s publishing device command feedback feedback/khf-net/@@/temperature_unit_is_farenheit publishing device command feedback feedback/khf-net/@@/ble_password publishing device command feedback feedback/khf-net/@@/data_logging_interval_s publishing device command feedback feedback/khf-net/@@/low_capacity_alarm_percent publishing device command feedback feedback/khf-net/@@/data_logging_enabled publishing device command feedback log/khf-net/@@/error publishing device errors log/khf-net/@@/device_found publishing device related log output log/khf-net/@@/device_type publishing device related log output log/khf-net/@@/fw_version publishing device related log output log/khf-net/@@/serial_number publishing device related log output log/khf-net/@@/log_entries_count publishing device related log output log/khf-net/@@/protection_relay_state publishing device related log output log/khf-net/@@/remaining_charge_discharge_time_min publishing device related log output log/khf-net/@@/clock_speed_adjustment_percent publishing device related log output log/khf-net/@@/device_time publishing device related log output sensor/khf-net/@@/battery_voltage_mV publishing measurement value sensor/khf-net/@@/battery_current_mA publishing measurement value sensor/khf-net/@@/battery_power_mW publishing measurement value sensor/khf-net/@@/battery_capacity_mAh publishing measurement value sensor/khf-net/@@/battery_capacity_mWh publishing measurement value sensor/khf-net/@@/battery_capacity_percent publishing measurement value sensor/khf-net/@@/discharged_energy_mWh publishing measurement value sensor/khf-net/@@/charged_energy_mWh publishing measurement value sensor/khf-net/@@/sensor_temperature_degC publishing measurement value
scan_busSending this topic (no payload necessary, it is ignored anyway), the
khf-netpopulate_addressSending this topic with a valid bus address as payload in ASCII text, i.e.
142tbd.
If you use your KH-F device together with the original display module, then there might be problems arising from two hosts acessing the module bus. The
khf-netOne solution to this bus contention problem is, to disable the display host mode in the display settings, then
khf-netOne other possible solution could be, to implement a pure sniffing mode in
khf-netThe OK button on the display is for toggeling the relay state on a short press. This is available, when the display is lit, else not.
If someone hits the OK button accidentally, while the display is lit, the relay toggles and could, i.e. trigger a overcurrent cutoff.
This can be avoided, to my own experiments, when the display host mode is disabled. In this configuration state, the OK button seems not any more doing this function.
current calibration error
Some KH-F device firmware versions do not respect the current calibration factor, namely the KH-F firmware version 132. This issue is solved in the firmware version 137.
eternal capacity error
The combination of KH-F firmware version 134 and Android Bluetooth-App V1.4.1 destroys the remaining capacity value, when the Bluetooth connection is established.
This is no fault of the
khf-netContributions are welcome, submit issues or do pull-requests. My time is very limited, I'll try my best to catch up with your contributions.
The project uses the MQTT-C library as an external dependency and all the MQTT lifting is done using this library.
Thanks to the authors of this library, making MQTT access this easy.
Ask on the project hosting site for support in the issues section.