ComAp Genset for Home Assistant

comap_genset is a HACS-compatible custom integration for the ComAp InteliLite 4 AMF20 controller.

The integration is built around the real UMOD export from this installation:

• comap_amf20_actual_profile_from_uploaded_umod.json
• comap_amf20_uploaded_registers.csv

It does not use the public sample map as the primary source of register addresses.

Features

• Local LAN only, Modbus/TCP only
• Config flow and options flow
• DataUpdateCoordinator based polling
• Separate sensor, binary_sensor, and button platforms
• Multi-register decoding for string and int32
• Profile-driven scaling and display precision
• Read-only by default
• Optional raw unknown register exposure from the CSV export
• Experimental start_stop_test control via coil 4700, gated behind an option
• Optional user-configured Modbus coil controls for alarm acknowledge, reset, start, and stop
• Diagnostics endpoint

Supported MVP telemetry

• RPM
• Load active power total and L1/L2/L3
• Generator frequency
• Generator voltage L1-N / L2-N / L3-N
• Load current L1 / L2 / L3
• Battery voltage
• Oil pressure
• Coolant temperature
• Fuel level
• Genset kWh
• Running hours
• Controller mode raw
• Engine state raw
• Connection type raw
• ID string
• Firmware version
• Alarm word 1..8

The JSON profile contains more named values, and the integration exposes them as sensors as well.

Installation with HACS

This repository is currently prepared as a HACS custom repository.

Repository URL:

• https://github.com/wrybak/comap-genset-ha

Quick link:

• Open in My Home Assistant

Steps:

1. Open HACS in Home Assistant.
2. Open the menu in the top-right corner.
3. Select Custom repositories.
4. Add https://github.com/wrybak/comap-genset-ha.
5. Select repository type Integration.
6. Click Add.
7. Search HACS for ComAp Genset.
8. Open the repository page and click Download.
9. Restart Home Assistant.
10. Go to Settings -> Devices & services -> Add integration.
11. Select ComAp Genset.
12. Enter:

• controller IP or local hostname
• TCP port, usually 502
• Modbus unit_id
• poll interval in seconds

After installation, HACS stores the integration under custom_components/comap_genset.

Troubleshooting unit_id

unit_id is the Modbus device address used inside the Modbus/TCP request.

Start with:

• 1 if you do not know the configured value

How to tell what is wrong:

• Wrong host or port: the integration usually cannot open the TCP connection at all, setup fails immediately, and Home Assistant logs connection errors such as timeout, refused connection, or unreachable host.
• Wrong unit_id: TCP connection to the controller works, but register reads fail because the controller does not answer for that slave address or returns Modbus errors. Setup may fail even though the IP and port are correct.

Practical checks:

1. Confirm the controller IP address and that Modbus/TCP is enabled on port 502.
2. Try unit_id: 1 first.
3. If that fails but the controller is reachable on the network, verify the Modbus slave address in the ComAp controller settings or ComAp service tool.
4. If another SCADA, PLC, or Home Assistant Modbus setup already talks to this controller, reuse the same unit_id.

Options

• poll_interval_seconds
• unit_id
• expose_raw_unknown_registers default false
• enable_experimental_control default false
• enable_write_controls default false
• enable_dangerous_controls default false
• optional confirmed coil addresses:
  • acknowledge_alarm_coil
  • reset_fault_coil
  • start_genset_coil
  • stop_genset_coil

When experimental control is enabled, the integration logs a clear warning and exposes:

• button entity Start/Stop Test
• service comap_genset.start_stop_test
• optional configured buttons/services for:
  • acknowledge_alarm
  • reset_fault
  • start_genset
  • stop_genset
• advanced experimental services:
  • comap_genset.pulse_coil
  • comap_genset.write_register

Service

service: comap_genset.start_stop_test
data:
  entry_id: "YOUR_CONFIG_ENTRY_ID"

If only one ComAp controller is configured, entry_id can be omitted.

Named configured command example:

service: comap_genset.acknowledge_alarm
data:
  entry_id: "YOUR_CONFIG_ENTRY_ID"

Generic experimental write examples:

service: comap_genset.pulse_coil
data:
  entry_id: "YOUR_CONFIG_ENTRY_ID"
  address: 4700

service: comap_genset.write_register
data:
  entry_id: "YOUR_CONFIG_ENTRY_ID"
  address: 5000
  value: 1

Example automations

Low fuel notification:

alias: ComAp Low Fuel Alert
triggers:
  - trigger: numeric_state
    entity_id: sensor.<your_controller_name>_fuel_level
    below: 20
actions:
  - action: notify.mobile_app_phone
    data:
      message: "Generator fuel level dropped below 20%."
mode: single

Running hours threshold:

alias: ComAp Maintenance Reminder
triggers:
  - trigger: numeric_state
    entity_id: sensor.<your_controller_name>_running_hours
    above: 250
actions:
  - action: persistent_notification.create
    data:
      title: "ComAp maintenance"
      message: "Running hours crossed 250h. Review the genset service interval."
mode: single

Alarm word change watcher:

alias: ComAp Alarm Word Changed
triggers:
  - trigger: state
    entity_id:
      - sensor.<your_controller_name>_alarm_word_1
      - sensor.<your_controller_name>_alarm_word_2
      - sensor.<your_controller_name>_alarm_word_3
      - sensor.<your_controller_name>_alarm_word_4
actions:
  - action: logbook.log
    data:
      name: "ComAp Genset"
      message: "Alarm word changed: {{ trigger.entity_id }} -> {{ trigger.to_state.state }}"
mode: queued

Notes and limitations

• The integration is intentionally read-only by default.
• Additional write controls are available only when you explicitly enable them in options and provide confirmed addresses.
• Raw BinaryObject entities are best-effort. If the controller does not expose direct discrete input reads for some unknown bits, those entities will remain unavailable.
• The UMOD export used here contains no Setpoint section, so writable holding-register control is intentionally not implemented in the MVP.
• Enum decoding tables for controller_mode_raw, engine_state_raw, and connection_type_raw are not included yet. Those values are exposed as numeric raw sensors.
• This repository does not guess write addresses for acknowledge_alarm, start_genset, stop_genset, reset_fault, or controller mode changes. You must confirm those addresses from your actual controller documentation or service tooling before enabling them.

Release process

The repository is prepared for HACS releases with:

• hacs.json
• GitHub Actions for HACS validate and Hassfest
• GitHub Releases using semantic version tags matching manifest.json

Current release line:

• 0.2.2