API Reference

Note

This page is dynamically created using the sphinx.ext.autodoc extension.

CAME Domotic API

This module exposes the CAME Domotic API to the end-users.

class aiocamedomotic.came_domotic_api.CameDomoticAPI(auth: Auth, *, command_timeout: int = 30)

Main class, exposes all the public methods of the CAME Domotic API.

async async_activate_scenario_by_name(name: str) → None

Activate a scenario by its name, without fetching the scenario list.

This is the plant-level counterpart to async_activate(): the server resolves the scenario by name itself, so there is no need to first download the scenarios via async_get_scenarios() just to trigger one — which is precisely the value of this command.

The match is performed server-side on the exact name. Case sensitivity has not been verified, so pass the exact name as returned by async_get_scenarios() (the name property of each Scenario). If no scenario matches, the server silently performs no activation.

Parameters:

name (str) – The exact name of the scenario to activate.

Raises:
async async_add_user(username: str, password: str, group: str = '*') → User

Add a new user to the CAME Domotic server.

Parameters:

  • username (str) – The login name for the new user.

  • password (str) – The initial password for the new user.

  • group (str, optional) – The name of the permission group to assign to the new user (e.g. "ETI/Domo"). Defaults to "*". Use async_get_terminal_groups() to retrieve the available group names from the server.

Returns:

A User object representing the newly created user.

Return type:

User

Raises:
async classmethod async_create(host: str, username: str, password: str, *, websession: ClientSession | None = None, close_websession_on_disposal: bool = False, command_timeout: int = 30) → CameDomoticAPI

Create a CameDomoticAPI object.

Parameters:

  • host (str) – The host of the CAME Domotic server.

  • username (str) – The username to use for the API.

  • password (str) – The password to use for the API.

  • websession (aiohttp.ClientSession, optional) – The aiohttp session to use for the API. If not provided, a new aiohttp.ClientSession will be created.

  • close_websession_on_disposal (bool, default False) –

    Controls whether the aiohttp session is closed when this object is disposed.

    • False (default): the session is preserved on disposal. Use this when the caller owns the session and reuses it elsewhere — which is the typical case in Home Assistant and other frameworks that maintain a single long-lived aiohttp.ClientSession shared across multiple integrations. Closing it here would break every other component that relies on it.

    • True: the session is closed on disposal. Use this only when you explicitly want this object to take ownership of the provided session and close it when done.

    Note

    When no websession is provided, this argument is ignored: the internally created session is always closed on disposal.

  • command_timeout (int, optional) – the default timeout in seconds for all commands sent to the server (default: 30s).

Returns:

The CameDomoticAPI object.

Return type:

CameDomoticAPI

Raises:

CameDomoticServerNotFoundError – if the host doesn’t respond to an HTTP request or doesn’t expose the CAME Domotic API endpoint.

Note

The session is not logged in until the first request is made.

async async_dispose() → None

Dispose the CameDomoticAPI object.

async async_get_analog_inputs() → list[AnalogIn]

Get the list of all standalone analog input sensors on the server.

Analog inputs are read-only sensors (e.g. hygrometers, thermometers, barometers) exposed via the analogin feature. They are independent of the thermoregulation system’s analog sensors.

Returns:

List of analog input sensors.

Return type:

list[AnalogIn]

Raises:
async async_get_analog_sensors() → list[AnalogSensor]

Get analog sensor readings from the thermoregulation system.

Retrieves top-level temperature, humidity, and pressure sensor readings from the thermoregulation list response.

Returns:

List of analog sensors found in the response.

Return type:

list[AnalogSensor]

Raises:
async async_get_cameras() → list[Camera]

Get the list of all TVCC cameras defined on the server.

Cameras are read-only entities providing access to IP camera stream URIs. They do not support control commands.

Returns:

List of cameras.

Return type:

list[Camera]

Raises:
async async_get_digital_inputs() → list[DigitalInput]

Get the list of all digital input devices defined on the server.

Digital inputs are read-only binary sensors (e.g. physical buttons, contact sensors). They report their state but cannot be controlled.

Returns:

List of digital inputs.

Return type:

list[DigitalInput]

Raises:
async async_get_energy_meters() → list[EnergyMeter]

Get the list of all energy meters defined on the server.

Energy meters are read-only, plant-level entities exposed via the energy feature. They report the instantaneous power measured on a line and energy values, and have no floor/room placement.

Returns:

List of energy meters. Returns an empty list if none are defined or the server response lacks the array key.

Return type:

list[EnergyMeter]

Raises:
async async_get_floors() → list[Floor]

Get the list of all the floors defined on the server.

Returns:

List of floors.

Return type:

list[Floor]

Raises:
async async_get_irrigation_sectors() → list[Irrigation]

Get the list of all irrigation sectors defined on the server.

Irrigation sectors are schedulable watering zones. Each can be forced on/off and its weekly schedule enabled/disabled.

Note

Irrigation support is not verified against a live plant. See Irrigation for details.

Returns:

List of irrigation sectors.

Return type:

list[Irrigation]

Raises:
async async_get_lights() → list[Light]

Get the list of all the light devices defined on the server.

Returns:

List of lights.

Return type:

list[Light]

Raises:
async async_get_loadsctrl_meters() → list[LoadsCtrlMeter]

Get the list of all loads controllers defined on the server.

Loads controllers (loadsctrl feature) bind an energy meter to an overload threshold and manage the load-shedding of their associated loads. A plant may define any number of controllers (including zero).

Returns:

List of loads controllers. Returns an empty list if none are defined or the server response lacks the array key.

Return type:

list[LoadsCtrlMeter]

Raises:
async async_get_loadsctrl_relays(controller_id: int) → list[LoadsCtrlRelay]

Get the loads managed by the given loads controller.

Convenience passthrough for loadsctrl_relay_list_req; async_get_relays() is the ergonomic path.

Parameters:

controller_id – The loads-controller id (as returned by async_get_loadsctrl_meters()), not the energy meter’s id.

Returns:

List of managed loads. Returns an empty list if none are defined or the server response lacks the array key.

Return type:

list[LoadsCtrlRelay]

Raises:
async async_get_map_pages() → list[MapPage]

Get the list of all map pages (floor plans) from the server.

Maps provide a spatial view of the installation with positioned device elements overlaid on background images. Map data is read-only and cannot be modified through the API.

Returns:

List of map pages, each containing positioned elements. Returns an empty list if no maps are defined.

Return type:

list[MapPage]

Raises:
async async_get_openings() → list[Opening]

Get the list of all opening devices defined on the server.

Returns:

List of openings.

Return type:

list[Opening]

Raises:
async async_get_relays() → list[Relay]

Get the list of all relay devices defined on the server.

Relays are simple on/off switches that can be controlled remotely.

Returns:

List of relays.

Return type:

list[Relay]

Raises:
async async_get_rooms() → list[Room]

Get the list of all the rooms defined on the server.

Returns:

List of rooms.

Return type:

list[Room]

Raises:
async async_get_scenarios() → list[Scenario]

Get the list of all scenarios defined on the server.

Returns:

List of scenarios.

Return type:

list[Scenario]

Raises:
async async_get_server_datetime() → ServerDateTime

Get the current date and time of the CAME Domotic server.

Reads the server clock, returned both as a Unix epoch (UTC) and as a local wall-clock string, together with the server timezone and the current daylight-saving-time flag. Useful for diagnosing the timestamps carried by push updates.

Returns:

The server date/time information.

Return type:

ServerDateTime

Raises:
async async_get_server_info() → ServerInfo

Get the server information.

Provides info about the server (keycode, software version, etc.) and the list of features supported by the CAME Domotic server.

Returns:

Server information.

Return type:

ServerInfo

Raises:
async async_get_sound_zones() → list[SoundZone]

Get the list of all sound zones defined on the server.

Sound zones are audio output rooms. Each can be powered on/off, muted, adjusted in volume, and switched between the available input sources.

Note

Sound zone support is not verified against a live plant. See SoundZone for details.

Returns:

List of sound zones.

Return type:

list[SoundZone]

Raises:
async async_get_terminal_groups() → list[TerminalGroup]

Get the list of terminal groups defined on the server.

Terminal groups define the permission scope assigned to users at creation time. Call this method before async_add_user() to discover the available group names on the server.

The group parameter of async_add_user() accepts a group name (e.g. "ETI/Domo"), not its numeric ID. The special value "*" (the default) may be used when fine-grained group assignment is not required.

Returns:

Available groups. Returns an empty list if none are defined or the server response lacks the array key.

Return type:

list[TerminalGroup]

Raises:
async async_get_thermo_zones() → list[ThermoZone]

Get the list of all thermoregulation zones defined on the server.

Returns:

List of thermoregulation zones.

Return type:

list[ThermoZone]

Raises:
async async_get_timers() → list[Timer]

Get the list of all timers defined on the server.

Timers are scheduling entities that define time-based activation windows. They support enabling/disabling, day toggling, and timetable configuration.

Returns:

List of timers.

Return type:

list[Timer]

Raises:
async async_get_topology() → PlantTopology

Get the complete plant topology (floors and rooms).

Merges data from the standard floor_list_req / room_list_req endpoints with the nested device list commands (nested_light_list_req, nested_openings_list_req, nested_thermo_list_req) to build a comprehensive topology even on servers where the flat floor/room endpoints return empty.

Only nested commands for features supported by the server are sent.

Returns:

The merged plant topology.

Return type:

PlantTopology

Raises:
async async_get_updates(timeout: int | None = None) → UpdateList

Get status updates from the server using long polling.

This method performs a long-polling request: it blocks until the server sends one or more real-time status updates (e.g., a light turned on, a scenario activated), then returns them all at once.

Parameters:

timeout (int | None, optional) – the timeout in seconds for the long-polling request. If None, uses the instance-level command_timeout (default: 30s). Since this method uses long polling, a longer timeout (e.g. 120s) is recommended to avoid premature disconnections.

Returns:

List of status updates received from the server.

Return type:

UpdateList

Raises:
async async_get_users() → list[User]

Get the list of users defined on the server.

Returns:

List of users. Returns an empty list if no users are defined or if the server response doesn’t contain the users list.

Return type:

list[User]

Raises:
async async_ping() → float

Ping the CAME Domotic server and measure round-trip latency.

Sends a keep-alive request to verify connectivity. If the session has expired, it transparently re-authenticates first.

Returns:

Round-trip latency in milliseconds.

Return type:

float

Raises:
async async_reset_energy_counters() → None

Reset the stored energy measurement history on the server.

This is a plant-level command that clears the stored energy consumption history of all energy meters at once (e.g. the values behind last_24h_avg and last_month_avg); it cannot target a single meter. Instantaneous power readings are not affected.

Warning

The reset is irreversible: the server discards the stored energy history and there is no way to restore it.

Raises:
async async_set_relay_status_by_name(name: str, status: RelayStatus) → None

Set a relay’s status by its name, without fetching the relay list.

This is the plant-level counterpart to async_set_status(): the server resolves the relay by name itself, so there is no need to first download the relays via async_get_relays().

The match is performed server-side on the exact name; pass the exact name as returned by async_get_relays() (the name property of each Relay).

Note

The by-name variant has not been verified against a live plant (our relays have never been tested against a real server; see the ROADMAP). Behaviour may differ across firmware versions.

Parameters:

  • name (str) – The exact name of the relay to control.

  • status (RelayStatus) – Desired relay status (ON or OFF).

Raises:
async async_set_thermo_season(season: ThermoZoneSeason) → None

Set the global thermoregulation season for all zones.

This is a plant-level command that changes the season for the entire thermoregulation system.

Warning

Setting season to PLANT_OFF causes the CAME server to automatically switch all thermoregulation zones to ThermoZoneMode.OFF. Reverting the season back to WINTER or SUMMER does not restore the previous zone modes — each zone stays OFF until its mode is changed explicitly via async_set_mode() or async_set_config().

If your application needs to restore zone operation after re-enabling a season, you must track each zone’s previous mode yourself and re-apply it after changing the season.

Parameters:

season – The season to set. Valid values are WINTER, SUMMER, and PLANT_OFF.

Raises:
async async_start_scenario_recording(name: str) → None

Start recording a new custom (user-defined) scenario.

Puts the CAME server in scenario-recording mode: the actions performed on the plant after this call (e.g. switching lights on/off) are captured as the steps of a new scenario named name. Call async_stop_scenario_recording() to finalize the recording and save the scenario on the server.

Note

The recording verified against a real plant captures actions performed via physical switches. Actions sent through the API (e.g. async_set_status()) are expected to be captured as well — the official CAME app records its own commands this way — but this has not been verified yet.

Parameters:

name (str) – The name of the new scenario.

Raises:
async async_stop_scenario_recording() → Scenario | None

Stop the ongoing scenario recording and save the new scenario.

Finalizes the recording started with async_start_scenario_recording(): the server stores the captured actions as a new user-defined scenario.

Returns:

The newly created scenario, retrieved from the server by matching the name passed to async_start_scenario_recording() (if several user-defined scenarios share that name, the one with the highest ID is returned). Returns None if the recording was not started via this API instance or if the new scenario cannot be identified.

Return type:

Scenario | None

Raises:

Entity models

This module defines the Python representation of each of the entity types used by the CAME Domotic API.

class aiocamedomotic.models.AnalogIn(raw_data: dict[str, Any])

Standalone analog input sensor from the analogin_list_resp endpoint.

Represents a read-only analog sensor (e.g. hygrometer, thermometer, barometer) exposed via the analogin feature.

Parameters:

raw_data – Dictionary containing the sensor data from the API.

Raises:

ValueError – If name or act_id keys are missing from the input data.

property act_id: int

Unique actuator/sensor identifier.

property name: str

Display name of the sensor.

property unit: str

Unit of measurement (e.g. 'C', '%', 'hPa').

property value: float

Sensor reading in the unit reported by unit.

class aiocamedomotic.models.AnalogInUpdate(raw_data: dict[str, Any])

Typed update for an analog input sensor (analogin_status_ind / analogin_update_ind).

property act_id: int

Analog input actuator ID.

property unit: str

Unit of measurement.

property value: float

Sensor reading, with temperature scaling applied for unit 'C'.

class aiocamedomotic.models.AnalogSensor(raw_data: dict[str, Any], sensor_type: AnalogSensorType = AnalogSensorType.UNKNOWN)

Analog sensor from the CAME Domotic thermoregulation system.

Represents a top-level temperature, humidity, or pressure sensor reading from the thermoregulation list response. These sensors are separate from the thermoregulation zones.

Parameters:

  • raw_data – Dictionary containing the sensor data from the API.

  • sensor_type – The type of sensor (temperature, humidity, or pressure). Defaults to AnalogSensorType.UNKNOWN if not specified.

Note

The value property returns the real sensor reading in the unit reported by unit (e.g., degrees C, %, hPa).

Raises:

ValueError – If name or act_id keys are missing from the input data.

property act_id: int

ID of the analog sensor.

property name: str

Name of the analog sensor.

sensor_type: AnalogSensorType = 'unknown'

The type of sensor (temperature, humidity, or pressure).

property unit: str

Unit of measurement (e.g., ‘C’, ‘%’, ‘hPa’).

property value: float

Sensor reading in the unit reported by unit.

class aiocamedomotic.models.AnalogSensorType(*values)

Type of an analog sensor.

Allowed values are:

  • TEMPERATURE (“temperature”)

  • HUMIDITY (“humidity”)

  • PRESSURE (“pressure”)

  • UNKNOWN (“unknown”)

class aiocamedomotic.models.CameEntity

Base class for all the CAME entities.

class aiocamedomotic.models.Camera(raw_data: dict[str, Any], auth: Auth)

TVCC camera entity in the CameDomotic API.

Cameras are read-only devices that provide streaming video and still-image URIs for IP cameras connected to the CAME Domotic system. They cannot be controlled remotely — this is purely a viewing/monitoring feature.

Warning

The uri and uri_still fields point directly to camera HTTP endpoints on the local network. These URIs may contain embedded authentication credentials (e.g. http://user:pass@camera/stream). Avoid logging or displaying these values without sanitisation.

Raises:

ValueError – If name or id keys are missing from the input data or the auth argument is not an instance of the expected Auth class.

property id: int

Unique camera identifier.

Unlike other device models which use act_id, cameras use a plain id field as their primary key (JS field: id, idProperty).

property is_flash: bool

Whether this camera uses a Flash (SWF) stream.

Flash streams are obsolete — consumers should fall back to uri_still for cameras where this is True.

Derived from: stream_type == "swf" (same check as JS client, line 5493).

property name: str

name).

Type:

Camera display name (JS field

property stream_type: str

Raw stream format string as returned by the server.

The only known value with special semantics is "swf" (Flash). All other values are treated identically by the JS client (JS field: stream_type).

property uri: str

Primary streaming video URI.

Points directly to the camera’s stream endpoint on the LAN. The actual protocol/format is opaque — the JS client loads it in an iframe (JS field: uri).

property uri_still: str

Snapshot/still-image URI.

Returns a single JPEG frame from the camera. Useful for thumbnails or as a fallback when the primary stream format is not supported. Append ?t=<timestamp> for cache busting on repeated fetches (JS field: uri_still).

class aiocamedomotic.models.DeviceType(*values)

Device type IDs used by the CAME ETI/Domo system.

Each device in the CAME Domotic system is associated with one of these type identifiers. Not all device types are currently supported by this library.

Negative IDs are library-specific: they identify entity kinds that the CAME API does not assign a numeric type to.

Values:

  • LOADSCTRL_RELAY (-5)

  • LOADSCTRL_METER (-4)

  • ANALOG_INPUT (-3)

  • ENERGY_SENSOR (-2)

  • ANALOG_SENSOR (-1)

  • LIGHT (0)

  • OPENING (1)

  • THERMOSTAT (2)

  • PAGE (3)

  • SCENARIO (4)

  • CAMERA (5)

  • SECURITY_PANEL (6)

  • SECURITY_AREA (7)

  • SECURITY_SCENARIO (8)

  • SECURITY_INPUT (9)

  • SECURITY_OUTPUT (10)

  • GENERIC_RELAY (11)

  • GENERIC_TEXT (12)

  • SOUND_ZONE (13)

  • DIGITAL_INPUT (14)

  • TIMER (15)

class aiocamedomotic.models.DeviceUpdate(raw_data: dict[str, Any])

Base class for a typed status update from the CAME API.

Wraps the raw update dict and exposes common properties. Subclasses add device-specific accessors.

Parameters:

raw_data – The original dict from the status_update_resp result array.

property cmd_name: str

The indication cmd_name string from the raw update.

property device_id: int | None

Primary device identifier (act_id, open_act_id, or id).

Returns the first available identifier, or None if none is present.

property device_type: DeviceType | None

The DeviceType for this update, or None if the cmd_name is not recognized.

property name: str

Device name from the update.

property update_indicator: UpdateIndicator | None

The UpdateIndicator for this update, or None if the cmd_name is not recognized.

class aiocamedomotic.models.DigitalInput(raw_data: dict[str, Any], auth: Auth)

Digital input (binary sensor) entity in the CameDomotic API.

Digital inputs report their binary state (ACTIVE/IDLE) and cannot be switched remotely. Inputs that raise a technical alarm or keep a signalling counter can, however, be acknowledged via async_ack().

Raises:

ValueError – If name or act_id keys are missing from the input data or the auth argument is not an instance of the expected Auth class.

property act_id: int

ID of the digital input.

property addr: int

Address of the digital input.

async async_ack() → None

Acknowledge the digital input.

Some digital inputs raise a technical alarm or keep a signalling counter that stays latched until it is acknowledged. This command clears that pending signalling for the input; it has no effect on inputs that do not track one.

The command is keyed on addr (not act_id). The server replies with digitalin_ack_resp echoing the input record, which is validated.

Raises:
property name: str

Name of the digital input.

property status: DigitalInputStatus

ACTIVE (0) or IDLE (1).

ACTIVE means the input is triggered (e.g. a button is being pressed). IDLE means the input is in its normal resting state.

Returns DigitalInputStatus.UNKNOWN when the status field is absent from the server response (some digital inputs do not report a status until their first state change).

Type:

Status of the digital input

property type: DigitalInputType

Type of the digital input.

Returns DigitalInputType.UNKNOWN when the type value is not recognized.

property utc_time: int

UTC timestamp of the last event (Unix epoch seconds).

Returns 0 if the digital input has never been triggered.

class aiocamedomotic.models.DigitalInputStatus(*values)

Status of a digital input.

Allowed values are:

  • ACTIVE (0): the input is active (e.g. a button is pressed)

  • IDLE (1): the input is idle (e.g. a button is not pressed)

class aiocamedomotic.models.DigitalInputType(*values)

Type of a digital input.

Allowed values are:

  • STATUS (1): standard status input

class aiocamedomotic.models.DigitalInputUpdate(raw_data: dict[str, Any])

Typed update for a digital input (digitalin_status_ind / digitalin_update_ind).

property act_id: int

Digital input actuator ID.

property addr: int

Digital input address.

property status: int

Digital input status value.

property utc_time: int

UTC timestamp of the digital input event.

class aiocamedomotic.models.EnergyMeter(raw_data: dict[str, Any])

Read-only energy meter from the meters_list_resp endpoint.

Represents an energy meter exposed via the energy feature. Energy meters are plant-level entities keyed by id (they have no act_id, floor, or room). They report the current power reading and energy values, and cannot be controlled.

Parameters:

raw_data – Dictionary containing the meter data from the API.

Raises:

ValueError – If name or id keys are missing from the input data, or if id is not an integer.

property energy_unit: str

Unit of measurement ('Wh' observed) for the last_24h_avg and last_month_avg values.

property id: int

Unique meter identifier.

This is also the matching key for meter_instant_power_ind push updates (energy meters have no act_id).

property instant_power: int

Current power reading, in the unit reported by unit.

The value is passed through exactly as reported by the server (no unit conversion is applied).

property last_24h_avg: int

Raw last_24h_avg field from the server, in energy_unit.

The value is passed through exactly as reported by the server.

property last_month_avg: int

Raw last_month_avg field from the server, in energy_unit.

The value is passed through exactly as reported by the server.

property meter_type: EnergyMeterType

Type of the meter (POWER is the only value observed so far).

property name: str

Display name of the meter.

property produced: int

Raw produced field from the server.

0 observed on consumption meters; semantics for production meters are unverified.

property unit: str

Unit of measurement for instant_power ('W' observed).

class aiocamedomotic.models.EnergyMeterType(*values)

Type of an energy meter, as reported in the meter_type field.

Allowed values are:

  • POWER (1): Power meter (the only value observed on real servers).

  • UNKNOWN (-1): Returned when the server reports an unrecognised meter_type value.

class aiocamedomotic.models.EnergyMeterUpdate(raw_data: dict[str, Any])

Typed update for an energy meter (meter_instant_power_ind).

Pushed by the server when the power measured by a meter changes. The payload is a complete snapshot of the meter state (same shape as a meters_list_resp item), including refreshed energy values.

property device_id: int | None

For energy meters the primary ID is id.

property energy_unit: str

Unit of measurement ('Wh' observed) for the last_24h_avg and last_month_avg values.

property id: int

Meter identifier (energy meters have no act_id).

property instant_power: int

Current power reading, in the unit reported by unit.

The value is passed through exactly as reported by the server (no unit conversion is applied).

property last_24h_avg: int

Raw last_24h_avg field, in energy_unit.

The value is passed through exactly as reported by the server.

property last_month_avg: int

Raw last_month_avg field, in energy_unit.

The value is passed through exactly as reported by the server.

property meter_type: EnergyMeterType

Type of the meter (POWER is the only value observed so far).

property produced: int

Raw produced field (0 observed on consumption meters).

property unit: str

Unit of measurement for instant_power ('W' observed).

class aiocamedomotic.models.Floor(raw_data: dict[str, Any])

Floor entity in the CAME Domotic API.

Represents a floor in the building structure with its identifier and name.

property id: int

ID of the floor.

property name: str

Name of the floor.

class aiocamedomotic.models.Irrigation(raw_data: dict[str, Any], auth: Auth)

Irrigation sector entity in the CameDomotic API.

Represents a single schedulable watering zone. Sectors are keyed on their id (not act_id). They can be forced on/off via async_force() and their weekly schedule enabled/disabled via async_set_enabled().

Note

Not verified against a live plant — see the module docstring.

Raises:

ValueError – If the id key is missing from the input data, or the auth argument is not an instance of the expected Auth class.

async async_force() → None

Toggle a forced watering cycle for this sector.

The command is a toggle: sending it starts a forced cycle if the sector is idle, and stops the running cycle otherwise. Callers that want explicit on/off semantics should check is_running before issuing the command.

The server replies with a generic acknowledgement (no dedicated response command), so only the standard ack is validated.

Raises:
async async_set_enabled(enabled: bool) → None

Enable or disable the sector’s weekly schedule.

Parameters:

enabled – True to enable the schedule, False to disable it.

The server replies with a generic acknowledgement (no dedicated response command), so only the standard ack is validated.

Raises:
property days: int

Bitmask of active days (bit 0 = Monday, …, bit 6 = Sunday).

property enabled: bool

Whether the sector’s weekly schedule is enabled.

property end: Any

Raw end-window value, or None if absent.

The exact shape is firmware-dependent and passed through unchanged.

property forced: bool

Whether the sector is currently in a forced watering cycle.

property id: int

Unique irrigation sector identifier.

property is_running: bool

Whether the sector is currently watering.

True when the sector reports a non-zero status or is in a forced cycle.

property name: str | None

Display name of the sector, or None if the server omits it.

property perc: int

Water percentage configured for the sector (0 when absent).

property sprinklers: Any

Raw sprinkler configuration, or None if absent.

The exact shape is firmware-dependent and passed through unchanged.

property start: Any

Raw start-window value, or None if absent.

The exact shape is firmware-dependent and passed through unchanged.

property status: int

Raw running status reported by the server (0 when absent).

class aiocamedomotic.models.Light(raw_data: dict[str, Any], auth: Auth)

Light entity in the CameDomotic API.

Raises:

ValueError – If name or act_id keys are missing from the input data or the auth argument is not an instance of the expected Auth class.

property act_id: int

ID of the light.

async async_set_status(status: LightStatus, brightness: int | None = None, rgb: list[int] | None = None) → None

Control the light.

Parameters:

  • status (LightStatus) – Status of the light.

  • brightness (Optional[int]) – Brightness percentage of the light (range 0-100). If the brightness is not provided, it will stay unchanged. This argument is ignored for STEP_STEP lights.

  • rgb (Optional[List[int]]) – RGB color values as [R, G, B], each in range 0-255. If not provided, the color stays unchanged. This argument is ignored for non-RGB lights.

Raises:
property floor_ind: int | None

Floor index of the light.

property name: str

Name of the light.

property perc: int

Brightness percentage of the light (range 0-100). Non dimmable lights will always return 100.

property rgb: list[int] | None

RGB color values of the light as [R, G, B], each in range 0-255. Returns None for non-RGB lights.

property room_ind: int | None

Room index of the light.

property status: LightStatus

Status of the light. Allowed values are OFF (0), ON (1) and AUTO (4).

property type: LightType

Light type. Allowed values are “STEP_STEP” (normal lights), “DIMMER” (dimmable lights), and “RGB” (color lights).

Raises:

ValueError – If the light type is not recognized.

class aiocamedomotic.models.LightStatus(*values)

Status of a light.

Allowed values are:

  • OFF (0)

  • ON (1)

  • AUTO (4)

class aiocamedomotic.models.LightType(*values)

Type of a light.

Allowed values are:

  • STEP_STEP (normal lights)

  • DIMMER (dimmable lights)

  • RGB (color lights with brightness via HSV V channel)

class aiocamedomotic.models.LightUpdate(raw_data: dict[str, Any])

Typed update for a light device (light_switch_ind / light_update_ind).

property act_id: int

Light actuator ID.

property floor_ind: int

Floor index.

property light_type: LightType

Light type (STEP_STEP, DIMMER, RGB).

property perc: int

Brightness percentage (0-100). Defaults to 100 for non-dimmable.

property rgb: list[int] | None

RGB color values [R, G, B] (0-255 each), or None.

property room_ind: int

Room index.

property status: LightStatus

Light status (OFF, ON, AUTO).

class aiocamedomotic.models.LoadsCtrlMeter(raw_data: dict[str, Any], auth: Auth)

The loads controller bound to an energy meter (loadsctrl feature).

Binds an energy meter (meter_id) to an overload threshold (max_power), a hysteresis, and a weekly hourly threshold profile (profile_data). When consumption exceeds the threshold, the controller detaches its managed loads (fetched via async_get_relays()) in priority order — lower priority value first.

A plant may define any number of controllers (including zero); code should never assume a single controller.

Raises:

ValueError – If name or id keys are missing from the input data, if id is not an integer, or if the auth argument is not an instance of the expected Auth class.

async async_get_relays() → list[LoadsCtrlRelay]

Get the loads managed by this controller.

Sends loadsctrl_relay_list_req with this controller’s id. Relays are returned in server order; sort by LoadsCtrlRelay.priority (ascending) to get the detach-order view shown by the official app.

Returns:

List of managed loads. Returns an empty list if none are defined or the server response lacks the array key.

Return type:

list[LoadsCtrlRelay]

Raises:
async async_set_config(*, max_power: int | None = None, hysteresis: int | None = None, profile_data: LoadsCtrlProfile | None = None) → None

Update the controller configuration.

Sends loadsctrl_meter_set_req. The wire command requires the full triple, so any unspecified argument is re-sent with its current value from raw_data.

Parameters:

  • max_power – New overload threshold in Watts (positive integer), or None to keep the current value.

  • hysteresis – New hysteresis in Watts (non-negative integer; 0 disables the hysteresis band), or None to keep the current value.

  • profile_data – New weekly hourly threshold profile as a LoadsCtrlProfile (typically obtained from profile and edited), or None to keep the current value.

Raises:

  • ValueError – If max_power is not a positive integer, if hysteresis is not a non-negative integer, or if profile_data is not a LoadsCtrlProfile.

  • CameDomoticAuthError – If the authentication fails.

  • CameDomoticServerError – If the server returns an error.

async async_set_detach_order(relays: Sequence[LoadsCtrlRelay]) → None

Rewrite priorities so loads are shed in the given order.

The first element of relays is shed first (lower priority value = shed first). The method fetches the controller’s current relay list, takes the existing priority values, sorts them ascending, and reassigns them to relays in sequence order — sending one loadsctrl_relay_set_req per relay whose priority actually changes (the official app also writes only changed relays). Reusing the existing value set keeps whatever absolute numbering convention the plant uses intact.

Each write is issued through a freshly-fetched relay object (not the caller-supplied one), so it carries the enabled flag as of this call’s own relay-list fetch rather than whatever value the caller’s object happened to have cached — otherwise a stale caller-side enabled would be silently written back over a concurrent change made by another client. The caller-supplied objects are updated with the resulting state afterward, so they remain a valid source for further calls.

This method is not atomic: it issues one set command per changed relay, sequentially. If a call fails partway through, the plant can be left with two relays sharing the same priority value (the new value is written to one relay before the old value is cleared from the other). This is safe to recover from by simply calling the method again: duplicate priority values found on the plant are repaired into a strictly increasing sequence (each duplicate is bumped just above the value before it) before being reassigned, so a replay of the same request converges to the requested order. The same repair also applies to plants whose priorities contain duplicates for any other reason, in which case some relays end up with priority values not previously used on the plant; a warning is logged when this happens.

Parameters:

relays – The desired detach order. Must be a permutation of this controller’s relays (same IDs, no duplicates) — fetch them via async_get_relays() first.

Raises:

  • ValueError – If relays is not a permutation of this controller’s relays (same IDs, no duplicates).

  • CameDomoticAuthError – If the authentication fails.

  • CameDomoticServerError – If the server returns an error.

property hysteresis: int

Hysteresis around the overload threshold, in Watts.

property id: int

Loads-controller identifier (opaque server value).

Required by loadsctrl_relay_list_req; do not confuse it with the bound energy meter’s meter_id.

property max_power: int

Overload threshold in Watts.

property meter_id: int

The id of the associated energy meter (from the meters list).

property name: str

Controller name (mirrors the bound energy meter’s name).

property power: float

Current power reading in Watts (same as the meter’s power).

The value is passed through exactly as reported by the server (no unit conversion is applied).

property profile: LoadsCtrlProfile

Weekly hourly threshold profile (typed view).

Parsed fresh from raw_data on every access (never cached), so it always reflects the latest known server state. Edit it with the LoadsCtrlProfile methods and write it back via async_set_config().

Raises:

ValueError – If raw_data lacks a well-formed profile_data value.

property profile_data: list[str]

Weekly hourly threshold profile (raw wire format, copied).

Seven strings — one per weekday, Monday first — of 24 characters each (one per hour of day). Each character is a digit 1-5 selecting the power threshold active in that hour as a fraction of max_power. For a typed view use profile.

Returns a copy: mutating the returned list does not affect raw_data.

class aiocamedomotic.models.LoadsCtrlMeterUpdate(raw_data: dict[str, Any])

Typed update for a loads controller (loadsctrl_meter_ind).

Pushed by the server after an accepted loadsctrl_meter_set_req, to all clients — including the one that issued the set. The payload is a complete snapshot of the controller state (same shape as a loadsctrl_meter_list_resp item).

property device_id: int | None

For loads controllers the primary ID is id.

property hysteresis: int

Hysteresis around the overload threshold, in Watts.

property id: int

Loads-controller identifier (opaque server value).

property max_power: int

Overload threshold in Watts.

property meter_id: int

The id of the associated energy meter.

property power: float

Current power reading in Watts (no unit conversion applied).

property profile_data: list[str]

Weekly hourly threshold profile (raw wire format, copied).

class aiocamedomotic.models.LoadsCtrlProfile(rows: Sequence[Sequence[int]])

Weekly hourly threshold profile of a loads controller.

7 rows (Monday..Sunday) of 24 hourly slots; each level 1-5 selects the power threshold active in that hour as a fraction of the controller’s max_power (the five levels shown in the official app).

Used by LoadsCtrlMeter.profile and accepted by LoadsCtrlMeter.async_set_config().

DAYS: ClassVar[tuple[ProfileDay, ...]] = (ProfileDay.MONDAY, ProfileDay.TUESDAY, ProfileDay.WEDNESDAY, ProfileDay.THURSDAY, ProfileDay.FRIDAY, ProfileDay.SATURDAY, ProfileDay.SUNDAY)

The rows of the grid, in wire order.

WIRE_SLOTS_PER_DAY: ClassVar[int] = 24

Number of wire slots per day row (a multiple of 24).

class aiocamedomotic.models.LoadsCtrlRelay(raw_data: dict[str, Any], auth: Auth)

A load managed by a loads controller (loadsctrl feature).

Represents an appliance that the loads controller can detach (shed) when consumption exceeds the configured threshold. Loads are shed in priority order: lower priority value = detached first.

Writable properties are changed via async_set_enabled() and async_set_priority().

Raises:

ValueError – If name or id keys are missing from the input data, if id is not an integer, or if the auth argument is not an instance of the expected Auth class.

property act_id: int

Underlying actuator ID.

Not used by any loadsctrl command: all loadsctrl operations are keyed by id.

async async_set_enabled(enabled: bool) → None

Enable or disable this load’s participation in load shedding.

This is the equivalent of the per-appliance toggle in the official app. The wire command requires both fields, so the current priority is re-sent alongside the new enabled flag.

Parameters:

enabled – True to let the controller shed this load on overload, False to exclude it from load shedding.

Raises:
async async_set_priority(priority: int) → None

Set the detach-order priority (raw server value).

Lower priority value = detached first. The wire command requires both fields, so the current enabled flag is re-sent alongside the new priority.

Parameters:

priority – The new priority value (non-negative integer). The absolute numbering convention is plant-specific; the usual pattern is to swap/reuse the values already present on the plant (see LoadsCtrlMeter.async_set_detach_order()).

Raises:
property detached: bool

Whether the controller has currently shed this load.

property enabled: bool

Whether the load participates in load shedding.

This is the per-appliance on/off toggle shown in the official app.

property id: int

Load identifier.

This is the key used by loadsctrl_relay_set_req and carried by loadsctrl_relay_ind push updates (not act_id).

property loadtype: int

Raw loadtype field (opaque; 1 observed, semantics unknown).

property name: str

Appliance name (user-defined, plant-specific).

property priority: int

Detach-order priority (raw server value).

Lower value = detached first. The absolute numbering is a plant-specific convention.

property status: LoadsCtrlRelayStatus

Current relay output state (read-only).

class aiocamedomotic.models.LoadsCtrlRelayStatus(*values)

Current output state of a load-control relay.

Allowed values are:

  • OFF (0)

  • ON (1)

  • UNKNOWN (-1): Returned when the server reports an unrecognised status value.

The relay output state is read-only: the loadsctrl commands cannot switch the relay on or off directly.

class aiocamedomotic.models.LoadsCtrlRelayUpdate(raw_data: dict[str, Any])

Typed update for a load-control relay (loadsctrl_relay_ind).

Pushed by the server after every accepted loadsctrl_relay_set_req, to all clients — including the one that issued the set. The payload is a complete snapshot of the relay state (same shape as a loadsctrl_relay_list_resp item) and should be treated as the authoritative confirmation of the change.

property act_id: int

Underlying actuator ID (not used by loadsctrl commands).

property detached: bool

Whether the controller has currently shed this load.

property device_id: int | None

For loadsctrl relays the primary ID is id.

Both act_id and id are present in the payload and differ: id is the key every loadsctrl command uses.

property enabled: bool

Whether the load participates in load shedding.

property id: int

Load identifier (the key used by all loadsctrl commands).

property loadtype: int

Raw loadtype field (opaque; 1 observed).

property priority: int

Detach-order priority (lower value = detached first).

property status: LoadsCtrlRelayStatus

Current relay output state (OFF, ON).

class aiocamedomotic.models.MapPage(raw_data: dict[str, Any])

A page (floor plan) in the CAME Domotic map system.

Each page represents a spatial view containing positioned elements (lights, openings, thermostats, page links, scenarios, cameras) overlaid on a background image. Elements are returned as raw dictionaries preserving the server response structure.

The elements list contains dictionaries with at least the following common keys: x, y, width, height, type, label, aspect, icon_id, permission, read_only, address. Additional keys depend on the element type (e.g. act_id for devices, page for page links, scenario_id for scenarios).

Raises:

ValueError – If page_id or page_label keys are missing from the input data, or if page_id is not an integer.

property background: str

Relative URL path to the background image on the CAME server.

The URL may contain spaces (e.g. "maps/maps_pianta piano terra.png"). Consumers must percent-encode the path when making HTTP requests. The full URL is constructed as http://<server_host>/<background>.

property elements: list[dict[str, Any]]

Interactive elements placed on this map page.

Each element is a raw dictionary from the server response. Common keys include x, y, width, height, type, label, aspect, icon_id, permission, read_only, and address. Type-specific keys (act_id, page, scenario_id, status) are present only for applicable element types.

property page_id: int

Unique page identifier.

0 is the root/home page.

property page_label: str

Human-readable page title.

property page_scale: int

Coordinate space size for element positioning.

Element x/y values range from 0 to page_scale. Typically 1024.

class aiocamedomotic.models.Opening(raw_data: dict[str, Any], auth: Auth)

Opening entity in the CameDomotic API.

Raises:

ValueError – If name or open_act_id keys are missing from the input data or the auth argument is not an instance of the expected Auth class.

async async_set_status(status: OpeningStatus) → None

Control the opening (open, close, stop, slat open, slat close).

Parameters:

status (OpeningStatus) – Status to set for the opening.

Raises:
property close_act_id: int

Actuator ID for closing action.

property floor_ind: int | None

Floor index where the opening is located.

property name: str

Name of the opening.

property open_act_id: int

Actuator ID for opening action.

property partial_positions: list[str]

List of configured partial opening positions, if any.

property room_ind: int | None

Room index where the opening is located.

property status: OpeningStatus

STOPPED (0), OPENING (1), CLOSING (2), SLAT_OPEN (3) and SLAT_CLOSE (4).

Type:

Current status of the opening. Allowed values

property type: OpeningType

Opening type.

Raises:

ValueError – If the opening type is not recognized.

class aiocamedomotic.models.OpeningStatus(*values)

Status of an opening.

Allowed values are:

  • STOPPED (0)

  • OPENING (1)

  • CLOSING (2)

  • SLAT_OPEN (3)

  • SLAT_CLOSE (4)

class aiocamedomotic.models.OpeningType(*values)

Type of an opening.

Allowed values are:

  • SHUTTER (0)

  • AWNING (1)

  • VENETIAN_BLIND (2)

  • GATE (3)

class aiocamedomotic.models.OpeningUpdate(raw_data: dict[str, Any])

Typed update for an opening device (opening_move_ind / opening_update_ind).

property close_act_id: int

Actuator ID for the closing action.

property device_id: int | None

For openings the primary ID is open_act_id.

property floor_ind: int

Floor index.

property open_act_id: int

Actuator ID for the opening action.

property room_ind: int

Room index.

property status: OpeningStatus

Opening status (STOPPED, OPENING, CLOSING, etc.).

class aiocamedomotic.models.PlantTopology(floors: list[TopologyFloor])

Complete plant topology (floors and rooms).

Built by merging data from the standard floor_list_req / room_list_req endpoints and the nested device list commands (nested_light_list_req, nested_openings_list_req, nested_thermo_list_req).

floors: list[TopologyFloor]

All floors in the plant, each containing its rooms.

class aiocamedomotic.models.PlantUpdate(raw_data: dict[str, Any])

Marker update for plant_update_ind.

When this indication is received, all cached devices must be discarded and re-fetched from the server.

property is_plant_update: bool

Always returns True.

class aiocamedomotic.models.ProfileDay(*values)

A row of a weekly profile grid.

MONDAY..``SUNDAY`` are 0..``6``, matching both the wire row order (Monday first) and datetime.date.weekday(), so ProfileDay(some_date.weekday()) is always correct.

JOLLY (7) is the special thermo profile used while a thermo zone is in JOLLY mode; it is the 8th wire row of thermo profiles and is not a valid day for loadsctrl profiles.

class aiocamedomotic.models.ProfileSpan(start: time, end: time, level: int)

A run of consecutive slots sharing the same level (read-only view).

Produced by WeeklyProfile.spans(). The range is half-open: start is inclusive, end is exclusive; an end of time(0) means “through midnight” (end of day).

class aiocamedomotic.models.Relay(raw_data: dict[str, Any], auth: Auth)

Relay entity in the CameDomotic API.

Represents a generic relay (simple on/off switch) in the CAME Domotic system. Provides properties to read relay attributes and a method to control relay state.

Raises:

ValueError – If name or act_id keys are missing from the input data or the auth argument is not an instance of the expected Auth class.

property act_id: int

ID of the relay.

async async_set_status(status: RelayStatus) → None

Control the relay.

Parameters:

status (RelayStatus) – Desired relay status (ON or OFF).

Raises:
async async_set_status_timed(interval: int) → None

Activate the relay for a timed interval.

The relay switches ON and the server automatically switches it back OFF once interval elapses. The subsequent OFF transition is reported asynchronously by the server via the usual status update, so this method does not update the local status (which momentarily becomes ON).

Parameters:

interval (int) –

Activation time, passed verbatim to the server. Must be greater than 0.

Warning

The unit of interval is not documented by the CAME API nor by the reference implementations this method is based on, and has not been verified against a real server. Callers should confirm the behaviour on their own plant before relying on a precise duration.

Raises:
property floor_ind: int

Floor index of the relay.

property name: str

Name of the relay.

property room_ind: int

Room index of the relay.

property status: RelayStatus

Status of the relay. Allowed values are OFF (0) and ON (1).

class aiocamedomotic.models.RelayStatus(*values)

Status of a relay.

Allowed values are:

  • OFF (0)

  • ON (1)

  • UNKNOWN (-1): Returned when the server reports an unrecognised status value. Not a valid target for async_set_status.

class aiocamedomotic.models.RelayUpdate(raw_data: dict[str, Any])

Typed update for a relay device (relay_status_ind / relay_update_ind).

property act_id: int

Relay actuator ID.

property floor_ind: int

Floor index.

property room_ind: int

Room index.

property status: RelayStatus

Relay status (OFF, ON).

class aiocamedomotic.models.Room(raw_data: dict[str, Any])

Room entity in the CAME Domotic API.

Represents a room in the building structure with its identifier, name, and the floor it belongs to.

property floor_id: int

ID of the floor this room belongs to.

property id: int

ID of the room.

property name: str

Name of the room.

class aiocamedomotic.models.Scenario(raw_data: dict[str, Any], auth: Auth)

Scenario entity in the CameDomotic API.

Represents a pre-configured automation scenario that can be activated to control multiple devices at once.

Raises:

ValueError – If name or id keys are missing from the input data or the auth argument is not an instance of the expected Auth class.

async async_activate() → None

Activate the scenario.

Sends the scenario activation command to the CAME Domotic server.

Raises:
async async_delete() → None

Delete the scenario from the CAME Domotic server.

Warning

The deletion is irreversible: the server discards the scenario and there is no way to restore it.

Note

Deletion is meant for user-defined scenarios (see user_defined): the official CAME app does not allow deleting system-defined ones. The command is sent anyway, but the server behaviour on system-defined scenarios is unverified.

Raises:
async async_rename(name: str) → None

Rename the scenario.

Sends the scenario rename command to the CAME Domotic server and updates the local name accordingly.

Note

Renaming is meant for user-defined scenarios (see user_defined): the official CAME app does not allow renaming system-defined ones. The command is sent anyway, but the server behaviour on system-defined scenarios is unverified.

Parameters:

name (str) – The new name of the scenario.

Raises:
property icon_id: int

Icon ID associated with the scenario.

property id: int

ID of the scenario.

property name: str

Name of the scenario.

property scenario_status: ScenarioStatus

OFF (0), TRIGGERED (1), or ACTIVE (2).

Type:

Scenario-specific status

property status: int

General status of the scenario.

property user_defined: int

Whether the scenario is user-defined (1) or system-defined (0).

class aiocamedomotic.models.ScenarioStatus(*values)

Status of a scenario.

Allowed values are:

  • OFF (0): scenario is not active

  • TRIGGERED (1): scenario has just been activated and is executing

  • ACTIVE (2): scenario is currently in effect

class aiocamedomotic.models.ScenarioUpdate(raw_data: dict[str, Any])

Typed update for a scenario (scenario_status_ind / scenario_activation_ind / scenario_user_ind).

property device_id: int | None

For scenarios the primary ID is id.

property id: int

Scenario ID.

property scenario_status: ScenarioStatus

Scenario status (OFF, TRIGGERED, ACTIVE).

class aiocamedomotic.models.ServerDateTime(raw_data: dict[str, Any])

Date and time reported by a CAME Domotic server.

Returned by CameDomoticAPI.async_get_server_datetime(). Wraps the datetime_req response, which carries the server clock both as a Unix epoch (UTC) and as a local wall-clock string, plus the server timezone and the current daylight-saving-time flag.

Useful for diagnosing the timestamps carried by push updates.

property datetime_string: str | None

Local wall-clock time as a "YYYY-MM-DD HH:MM:SS" string.

Already offset for the server timezone and DST. None if the server response does not include it.

property daylight_saving_time: bool

Whether daylight saving time is currently in effect on the server.

property epoch: int

Server clock as a Unix epoch, in seconds (UTC).

property timezone_name: str | None

IANA timezone name of the server (e.g. "Europe/Rome").

None if the server response does not include it.

property utc_datetime: datetime

Server clock as a timezone-aware datetime (UTC).

Derived from epoch.

class aiocamedomotic.models.ServerFeature(*values)

Server feature identifiers reported by the CAME Domotic server.

Each member corresponds to a functional block (e.g. lights, openings). Because ServerFeature is a StrEnum, each member is its string value (e.g. ServerFeature.LIGHTS == "lights" is True), so members can be compared directly against the plain strings in features.

Values:

  • LIGHTS (“lights”) — on/off, dimmable and RGB lights

  • OPENINGS (“openings”) — shutters, awnings, and motorized covers

  • RELAYS (“relays”) — simple on/off relay switches

  • THERMOREGULATION (“thermoregulation”) — climate zones and analog sensors

  • SCENARIOS (“scenarios”) — pre-configured automation sequences

  • DIGITALIN (“digitalin”) — read-only binary sensors (buttons, contacts)

  • ANALOGIN (“analogin”) — read-only standalone analog sensors

  • ENERGY (“energy”) — energy meters

  • LOADSCTRL (“loadsctrl”) — load control / management

  • TIMERS (“timers”) — time-based scheduling entities

class aiocamedomotic.models.ServerInfo(keycode: str, serial: str, features: list[str], swver: str | None = None, type: str | None = None, board: str | None = None)

Server information of a CAME Domotic server.

board: str | None = None

Board type of the server.

features: list[str]

List of feature strings reported by the server.

Each feature corresponds to a functional block (e.g. lights, openings). Values are plain strings whose known values are defined in ServerFeature. Because ServerFeature is a StrEnum, you can compare entries against enum members directly (e.g. ServerFeature.LIGHTS in server_info.features).

The return type is kept as list[str] so that features introduced by newer firmware versions are preserved even if the library does not yet define them in ServerFeature.

keycode: str

Keycode of the server (CAME proprietary unique identifier).

serial: str

Serial number of the server.

swver: str | None = None

Software version of the server.

type: str | None = None

Type of the server.

class aiocamedomotic.models.SoundZone(raw_data: dict[str, Any], auth: Auth)

Sound zone entity in the CameDomotic API.

Represents a single audio zone. Zones are keyed on their id (not act_id). They can be powered on/off, muted, adjusted in volume, and switched between the available input sources.

Note

Not verified against a live plant — see the module docstring.

Raises:

ValueError – If the id key is missing from the input data, or the auth argument is not an instance of the expected Auth class.

async async_refresh() → None

Refresh this zone’s state from the server (sound_room_src_req).

Fetches the current state of this single zone and merges it into raw_data. The update is applied only if the response refers to this zone’s ID.

Raises:
async async_select_source(source_name: str) → None

Select an input source by name.

The name is matched against the normalized sources list and the corresponding source ID is sent to the server.

Parameters:

source_name – Name of the source to select, as reported in sources.

Raises:
async async_send_source_command(source_id: int, action: str) → None

Send an advanced command to an audio source (suftif_cmd_req).

This is a low-level primitive: the set of supported actions depends on the source device (e.g. tuner or media player transport commands) and is passed through to the server unchanged.

Parameters:

  • source_id – ID of the target source, as reported in sources.

  • action – Action string understood by the source device.

The server replies with a generic acknowledgement (no dedicated response command), so only the standard ack is validated.

Raises:
async async_set_mute(muted: bool) → None

Mute or unmute the zone.

Parameters:

muted – True to mute the zone, False to unmute it.

Raises:
async async_set_volume_level(volume_level: float) → None

Set the zone volume from a normalized 0.0–1.0 level.

The level is denormalized onto the server-provided min_volume/max_volume range and rounded to the nearest raw value.

Parameters:

volume_level – Desired volume in the 0.0–1.0 range.

Raises:

  • ValueError – If volume_level is outside the 0.0–1.0 range, or the zone does not report its volume range.

  • CameDomoticAuthError – If the authentication fails.

  • CameDomoticServerError – If the server returns an error.

async async_turn_off() → None

Put the zone in standby.

Raises:
async async_turn_on() → None

Power on the zone (leave standby).

Raises:
property id: int

Unique sound zone identifier.

property is_muted: bool

Whether the zone is muted.

property is_on: bool

Whether the zone is powered on (i.e. not in standby).

property max_volume: int | None

Upper bound of the raw volume range, or None if absent.

property min_volume: int | None

Lower bound of the raw volume range, or None if absent.

property name: str | None

Display name of the zone, or None if the server omits it.

property source: str | None

Name of the currently selected source, or None if unknown.

property sources: list[dict[str, Any]]

Available input sources, normalized to {"name", "id"} dicts.

Depending on the firmware, the server reports sources either as a sources array (items carrying source or source_name plus id) or as flat source_N fields with an optional id_source_N companion (defaulting to N - 1). Both formats are merged and deduplicated by (name, id).

property volume: int | None

Raw volume value reported by the server, or None if absent.

property volume_level: float | None

Volume normalized to the 0.0–1.0 range.

Returns None when the raw volume or its range is unknown, and 0.0 when the server reports an empty range (max_volume == min_volume). Values are clamped to 0.0–1.0.

class aiocamedomotic.models.SoundZoneAction(*values)

Actions accepted by the sound_switch_req command.

Values:

  • STANDBY (“standby”): power the zone on/off

  • MUTE (“mute”): mute/unmute the zone

  • VOLUME (“volume”): set the raw volume value

  • SOURCE (“source”): select an input source by ID

class aiocamedomotic.models.TerminalGroup(raw_data: dict[str, Any])

Terminal group in the CAME Domotic API.

Represents a user permission group (e.g. "ETI/Domo"). Groups are assigned to users at creation time via CameDomoticAPI.async_add_user(). Use CameDomoticAPI.async_get_terminal_groups() to retrieve the available group names before creating a user.

property id: int

Numeric ID of the group.

property name: str

Name of the group (e.g. "ETI/Domo").

class aiocamedomotic.models.ThermoProfile(rows: Sequence[Sequence[int]])

Weekly setpoint-level profile of a thermo zone.

8 rows — Monday..Sunday plus ProfileDay.JOLLY as the 8th row — of 96 quarter-hour wire slots; each level 1-5 selects one of the five setpoint levels shown in the official app. The app edits thermo profiles per hour, so this class exposes hours only (see WeeklyProfile).

Currently a read/edit value type only: the thermo profile set command has never been observed in captured traffic, so writing a profile back to a zone is not yet supported by the library.

DAYS: ClassVar[tuple[ProfileDay, ...]] = (ProfileDay.MONDAY, ProfileDay.TUESDAY, ProfileDay.WEDNESDAY, ProfileDay.THURSDAY, ProfileDay.FRIDAY, ProfileDay.SATURDAY, ProfileDay.SUNDAY, ProfileDay.JOLLY)

The rows of the grid, in wire order.

WIRE_SLOTS_PER_DAY: ClassVar[int] = 96

Number of wire slots per day row (a multiple of 24).

class aiocamedomotic.models.ThermoZone(raw_data: dict[str, Any], auth: Auth)

Thermoregulation zone entity in the CameDomotic API.

Represents a single thermoregulation zone with its current state, including temperature readings, setpoint, operating mode, and season.

Temperature values from the API are integers multiplied by 10 (e.g., 215 = 21.5 degrees C). Properties in this class return converted float values in degrees.

Raises:

ValueError – If name or act_id keys are missing from the input data, or the auth argument is not an instance of the expected Auth class.

property act_id: int

ID of the thermoregulation zone.

property antifreeze: float | None

Antifreeze temperature in degrees Celsius, or None if not set.

async async_set_config(mode: ThermoZoneMode, set_point: float, *, fan_speed: ThermoZoneFanSpeed | None = None) → None

Configure the thermoregulation zone.

Note

The season cannot be changed via this method. Use CameDomoticAPI.async_set_thermo_season() to change the season at the plant level.

Parameters:

  • mode – Operating mode to set.

  • set_point – Target temperature in degrees Celsius.

  • fan_speed – Fan speed setting (optional, requires extended info).

Raises:
async async_set_fan_speed(fan_speed: ThermoZoneFanSpeed) → None

Set the fan speed, keeping the current mode and temperature.

Parameters:

fan_speed – Fan speed to set.

Raises:
async async_set_mode(mode: ThermoZoneMode) → None

Set the operating mode, keeping the current target temperature.

Parameters:

mode – Operating mode to set.

Raises:
async async_set_temperature(temperature: float) → None

Set the target temperature, keeping the current operating mode.

Warning

This method only has an effect when the zone is in ThermoZoneMode.MANUAL mode. When the zone is in any other mode (e.g. AUTO, JOLLY), the server accepts the request without error but silently discards the new setpoint. Use async_set_config() with mode=ThermoZoneMode.MANUAL to guarantee that the setpoint is applied.

Parameters:

temperature – Target temperature in degrees Celsius.

Raises:
property dehumidifier_enabled: bool

Whether the dehumidifier is enabled for this zone.

property dehumidifier_setpoint: float | None

Dehumidifier humidity setpoint in percent, or None if not set.

property fan_speed: ThermoZoneFanSpeed

Fan speed setting for the thermoregulation zone.

Returns ThermoZoneFanSpeed.UNKNOWN for unrecognized values.

property floor_ind: int | None

Floor index of the thermoregulation zone.

property leaf: bool

Whether this is an actual zone (leaf node) in the hierarchy.

property mode: ThermoZoneMode

Operating mode of the thermoregulation zone.

Returns ThermoZoneMode.UNKNOWN for unrecognized mode values.

property name: str

Name of the thermoregulation zone.

property profile: ThermoProfile

Weekly setpoint-level profile (typed view).

Parsed fresh from raw_data on every access (never cached).

Raises:

ValueError – If raw_data lacks a well-formed profile_data value.

property profile_data: list[str]

Weekly setpoint-level profile (raw wire format, copied).

Eight strings — Monday..Sunday plus the JOLLY profile as the 8th row — of 96 characters each (one per quarter hour of day). Each character is a digit 1-5 selecting one of the five setpoint levels shown in the official app. For a typed view use profile.

Read-only: the thermo profile set command has never been observed in captured traffic, so writing a profile back to the zone is not yet supported by the library.

Returns a copy: mutating the returned list does not affect raw_data. Returns an empty list if the zone data carries no profile (push updates do not include it).

property room_ind: int | None

Room index of the thermoregulation zone.

property season: ThermoZoneSeason

Season setting for the thermoregulation zone.

Returns ThermoZoneSeason.UNKNOWN for unrecognized season values.

property set_point: float

Target temperature in degrees Celsius.

property status: ThermoZoneStatus

Status of the thermoregulation zone (OFF or ON).

property t1: float | None

Temperature sensor 1 reading in degrees Celsius, or None.

property t2: float | None

Temperature sensor 2 reading in degrees Celsius, or None.

property t3: float | None

Temperature sensor 3 reading in degrees Celsius, or None.

property temperature: float

Current temperature in degrees Celsius.

Handles both temp (from list responses) and temp_dec (from status indications) field names.

class aiocamedomotic.models.ThermoZoneFanSpeed(*values)

Fan speed setting for a thermoregulation zone.

Allowed values are:

  • OFF (0)

  • SLOW (1)

  • MEDIUM (2)

  • FAST (3)

  • AUTO (4)

class aiocamedomotic.models.ThermoZoneMode(*values)

Operating mode of a thermoregulation zone.

Allowed values are:

  • OFF (0)

  • MANUAL (1)

  • AUTO (2)

  • JOLLY (3)

class aiocamedomotic.models.ThermoZoneSeason(*values)

Season setting for a thermoregulation zone.

Allowed values are:

  • PLANT_OFF (“plant_off”)

  • WINTER (“winter”)

  • SUMMER (“summer”)

class aiocamedomotic.models.ThermoZoneStatus(*values)

Status of a thermoregulation zone.

Allowed values are:

  • OFF (0)

  • ON (1)

class aiocamedomotic.models.ThermoZoneUpdate(raw_data: dict[str, Any])

Typed update for a thermostat zone (thermo_zone_info_ind / thermo_update_ind).

property act_id: int

Zone actuator ID.

property dehumidifier_enabled: bool

Whether the dehumidifier is enabled.

property dehumidifier_setpoint: float | None

Dehumidifier humidity setpoint in percent, or None if not present.

property fan_speed: ThermoZoneFanSpeed

Fan speed setting (OFF, SLOW, MEDIUM, FAST, AUTO).

property floor_ind: int

Floor index.

property mode: ThermoZoneMode

Operating mode (OFF, MANUAL, AUTO, JOLLY).

property room_ind: int

Room index.

property season: ThermoZoneSeason

Season setting (PLANT_OFF, WINTER, SUMMER).

property set_point: float

Target temperature in degrees Celsius (converted from set_point).

property status: ThermoZoneStatus

Zone status (OFF, ON).

property t1: float | None

Temperature sensor 1 reading in degrees Celsius.

property t2: float | None

Temperature sensor 2 reading in degrees Celsius.

property t3: float | None

Temperature sensor 3 reading in degrees Celsius.

property temperature: float

Current temperature in degrees Celsius (converted from temp_dec).

class aiocamedomotic.models.Timer(raw_data: dict[str, Any], auth: Auth)

Timer entity in the CameDomotic API.

Represents a scheduling timer with time-based activation windows. Supports enabling/disabling, day-of-week toggling, and timetable configuration via the CAME API.

The days field is a 7-bit bitmask (bit 0 = Monday, …, bit 6 = Sunday). For example, days=85 (binary 1010101) means Monday, Wednesday, Friday, and Sunday.

Raises:

ValueError – If name or id keys are missing from the input data or the auth argument is not an instance of Auth.

property active_days: list[str]

Human-readable names of the days the timer is active on.

async async_disable() → None

Disable the timer.

Raises:
async async_disable_day(day: int) → None

Disable the timer for a specific day of the week.

Parameters:

day – Day index (0=Monday, 1=Tuesday, …, 6=Sunday).

Raises:
async async_enable() → None

Enable the timer.

Raises:
async async_enable_day(day: int) → None

Enable the timer for a specific day of the week.

Parameters:

day – Day index (0=Monday, 1=Tuesday, …, 6=Sunday).

Raises:
async async_set_timetable(slots: list[tuple[int, int, int] | None]) → None

Set the timer’s timetable.

Sends the complete timetable to the server. The list must contain exactly 4 entries — one per available slot. Use None for empty slots.

Parameters:

slots – List of 4 entries. Each entry is either a (hour, min, sec) tuple for an active slot, or None for an empty slot.

Raises:
property bars: int

Number of timetable bars reported by the server.

property days: int

Bitmask of active days (bit 0 = Monday, …, bit 6 = Sunday).

property enabled: bool

Whether the timer is globally enabled.

property id: int

Unique timer identifier.

is_active_on_day(day_index: int) → bool

Check whether the timer is active on a specific day.

Parameters:

day_index – Day index (0=Monday, 1=Tuesday, …, 6=Sunday).

Returns:

True if the timer is scheduled for this day, False otherwise (including when day_index is out of range).

property name: str

Display name of the timer.

property timetable: list[TimerTimeSlot]

Scheduled time slots.

Malformed entries are skipped with a warning.

class aiocamedomotic.models.TimerTimeSlot(raw_data: dict[str, Any])

A single time window within a timer’s timetable.

On some firmware versions, the stop and active fields may be absent. Properties return None for missing optional fields.

Parameters:

raw_data – Dictionary from a single timetable array entry.

Raises:

ValueError – If index or start keys are missing.

property active: bool | None

Whether this time window is active, or None if absent.

property index: int

Zero-based slot position in the timetable (0-3).

property start_hour: int

Start time hour (0-23). Defaults to 0 if missing.

property start_min: int

Start time minute (0-59). Defaults to 0 if missing.

property start_sec: int

Start time second (0-59). Defaults to 0 if missing.

property stop_hour: int | None

Stop time hour, or None if the stop field is absent.

property stop_min: int | None

Stop time minute, or None if the stop field is absent.

property stop_sec: int | None

Stop time second, or None if the stop field is absent.

class aiocamedomotic.models.TimerUpdate(raw_data: dict[str, Any])

Typed update for a timer (timer_info_ind / timer_update_ind).

property bars: int

Number of timetable bars reported by the server.

property days: int

Days bitmask (bit 0 = Monday, …, bit 6 = Sunday).

property device_id: int | None

For timers the primary ID is id.

property enabled: bool

Whether the timer is enabled.

property id: int

Timer ID.

property timetable: list[dict[str, Any]]

Raw timetable entries from the update.

class aiocamedomotic.models.TopologyFloor(id: int, name: str, rooms: list[TopologyRoom])

A floor in the plant topology.

Contains the list of rooms discovered on this floor.

id: int

Numeric identifier of the floor (floor_ind).

name: str

Human-readable name of the floor.

rooms: list[TopologyRoom]

Rooms belonging to this floor.

class aiocamedomotic.models.TopologyRoom(id: int, name: str)

A room in the plant topology.

Lightweight representation used by PlantTopology to describe the building structure independently of any specific device type.

id: int

Numeric identifier of the room (room_ind).

name: str

Human-readable name of the room.

class aiocamedomotic.models.UpdateIndicator(*values)

Known status-update indication cmd_names from the CAME API.

These identify the type of state change in a status_update_resp result item. Some indicators have two variants: one observed in real API traffic and one documented in API_reference.md. Both are mapped for firmware compatibility.

Values:

  • LIGHT (“light_switch_ind”)

  • OPENING (“opening_move_ind”)

  • RELAY (“relay_status_ind”)

  • THERMOSTAT (“thermo_zone_info_ind”)

  • DIGITAL_INPUT (“digitalin_status_ind”)

  • ANALOG_INPUT (“analogin_status_ind”)

  • SCENARIO_STATUS (“scenario_status_ind”)

  • SCENARIO_ACTIVATION (“scenario_activation_ind”)

  • ENERGY_METER (“meter_instant_power_ind”)

  • LOADSCTRL_METER (“loadsctrl_meter_ind”)

  • LOADSCTRL_RELAY (“loadsctrl_relay_ind”)

  • PLANT (“plant_update_ind”)

  • LIGHT_LEGACY (“light_update_ind”)

  • OPENING_LEGACY (“opening_update_ind”)

  • THERMOSTAT_LEGACY (“thermo_update_ind”)

  • RELAY_LEGACY (“relay_update_ind”)

  • DIGITAL_INPUT_LEGACY (“digitalin_update_ind”)

  • ANALOG_INPUT_LEGACY (“analogin_update_ind”)

  • TIMER (“timer_info_ind”)

  • SCENARIO_USER_LEGACY (“scenario_user_ind”)

  • TIMER_LEGACY (“timer_update_ind”)

class aiocamedomotic.models.UpdateList(updates: UserList[dict[str, Any]] | None = None)

Chronological list of status updates from the CameDomotic API.

Extends UserList to maintain backward compatibility: iterating yields raw dict objects. Additional methods provide typed access and filtering.

get_by_device_type(device_type: DeviceType) → list[dict[str, Any]]

Return raw update dicts filtered to the given device type.

Parameters:

device_type – The DeviceType to filter by.

Returns:

A list of raw update dicts whose cmd_name maps to device_type.

get_typed_by_device_type(device_type: DeviceType) → list[DeviceUpdate]

Parse and filter updates by device type.

Parameters:

device_type – The DeviceType to filter by.

Returns:

Typed DeviceUpdate instances whose device_type matches device_type.

get_typed_updates() → list[DeviceUpdate]

Parse all updates into typed DeviceUpdate objects.

Returns:

A list of DeviceUpdate subclass instances, one per raw update dict.

property has_plant_update: bool

Whether any update in this list is a plant_update_ind.

When True, the consumer should discard all cached devices and re-fetch them from the server.

class aiocamedomotic.models.User(raw_data: dict[str, Any], auth: Auth)

User in the CAME Domotic API.

Raises:

ValueError – If name key is missing from the input data the auth argument is not an instance of the expected Auth class.

async async_change_password(current_password: str, new_password: str) → None

Change the password of this user on the CAME Domotic server.

Parameters:

  • current_password (str) – The user’s current password.

  • new_password (str) – The desired new password.

Note

Changing the password does not invalidate existing active sessions for that user — they remain valid until they expire. The new password will be required at the next login.

If the changed user is the currently authenticated user, the stored credentials are updated automatically in the active session — no additional action is required.

Raises:
async async_delete() → None

Delete this user from the CAME Domotic server.

Sends a delete-user request to the server for the user identified by this object’s name property.

Raises:
async async_set_as_current_user(password: str) → None

Set the user as the current user in the CAME Domotic API session.

Parameters:

password (str) – Password of the user.

Raises:

CameDomoticAuthError – If the authentication fails.

Note

This method logs out the current user and logs in with the new user. If login with the new credentials fails, a CameDomoticAuthError is raised and the previous credentials are restored so the API client remains connected as the original user.

property name: str

Name of the user.

class aiocamedomotic.models.WeeklyProfile(rows: Sequence[Sequence[int]])

Immutable weekly schedule grid (abstract base).

Concrete subclasses (LoadsCtrlProfile, ThermoProfile) define the grid shape via DAYS and WIRE_SLOTS_PER_DAY; all parsing, reading, and editing logic lives here.

Instances are immutable value objects: editing methods (with_level(), with_day_copied()) return a new instance, and equality/hashing are by value (two profiles of the same class with the same grid are equal). Construct instances via from_wire() or constant().

The public API speaks in hours (the official app edits per hour); the internal grid keeps the wire resolution, so serializing an unedited profile reproduces the server bytes exactly.

DAYS: ClassVar[tuple[ProfileDay, ...]]

The rows of the grid, in wire order.

LEVELS: ClassVar[frozenset[int]] = frozenset({1, 2, 3, 4, 5})

Allowed level values (the five levels shown in the official app).

WIRE_SLOTS_PER_DAY: ClassVar[int]

Number of wire slots per day row (a multiple of 24).

classmethod constant(level: int) → Self

Create a profile with every slot of every row set to level.

Raises:

  • TypeError – If called on the abstract WeeklyProfile class.

  • ValueError – If level is not in LEVELS.

classmethod from_wire(data: Sequence[str]) → Self

Parse a profile from its raw wire format.

The wire format is a list of digit strings, one per row of DAYS in order, each of exactly WIRE_SLOTS_PER_DAY characters, each character a digit in LEVELS.

Guarantee: cls.from_wire(x).to_wire() == x byte-for-byte — nothing is normalized or reinterpreted.

On profile types with sub-hour wire slots, a row whose hours are not uniform (different levels within the same hour) is unexpected — the official app edits per hour — so a warning is logged, but the data is accepted and preserved exactly.

Parameters:

data – The raw profile rows, e.g. from a server response.

Raises:

  • TypeError – If called on the abstract WeeklyProfile class.

  • ValueError – If the shape or any character is invalid.

level_at(day: ProfileDay | int, at: time | datetime | int) → int

Return the level active on day at the given moment.

Parameters:

  • day – The profile row to read (a ProfileDay or its integer value).

  • at – The moment of day: an int hour (0-23), a datetime.time, or a datetime.datetime (its time of day is used; the date is not used to pick day). Any time is accepted — it resolves to the containing wire slot, so no hour alignment is required for reads.

Raises:

ValueError – If day is not a row of this profile type or at is not a valid moment of day.

spans(day: ProfileDay | int) → list[ProfileSpan]

Return day’s schedule as runs of consecutive equal levels.

Each ProfileSpan is a half-open [start, end) range; the last span’s end is time(0), meaning “through midnight”. For app-written data the boundaries fall on whole hours.

Raises:

ValueError – If day is not a row of this profile type.

to_wire() → list[str]

Serialize to the raw wire format (a fresh list of digit strings).

For a profile obtained via from_wire() and not edited since, this returns exactly the original input.

with_day_copied(source: ProfileDay | int, to: ProfileDay | int | Iterable[ProfileDay | int]) → Self

Return a copy with source’s whole row copied over to.

The “copy this day to other days” operation. Rows are copied at wire resolution, so the copy is lossless. The original profile is not modified.

Parameters:

  • source – The row to copy from.

  • to – The row(s) to copy onto: a single ProfileDay (or its integer value) or an iterable of them.

Raises:

ValueError – If source or any target is not a row of this profile type.

with_level(level: int, *, days: ProfileDay | int | Iterable[ProfileDay | int] | None = None, start: time | int = 0, end: time | int | None = None) → Self

Return a copy with [start, end) on days set to level.

The original profile is not modified. The full week is always kept (and later sent to the server) — this method only chooses which cells of the copy get the new level.

Parameters:

  • level – The level to set (must be in LEVELS).

  • days – The rows to change: a single ProfileDay (or its integer value), an iterable of them, or None (the default) for every row of this profile type — on thermo profiles that includes ProfileDay.JOLLY; pass WEEKDAYS to target Monday..Sunday only.

  • start – Start hour, inclusive: an int (0-23) or a whole-hour datetime.time. Defaults to 0 (midnight).

  • end – End hour, exclusive: an int (1-24), a whole-hour datetime.time (time(0) means end of day), or None (the default) for end of day. Edits are hour-based, so start/end must be whole hours (no rounding is applied) and spans cannot cross midnight — split such an edit into two calls.

Raises:

ValueError – If level, days, start, or end are invalid, or if start >= end.

aiocamedomotic.models.get_update_device_type(update: dict[str, Any]) → DeviceType | None

Return the device type for a status update dict, or None if unknown.

Parameters:

update – A single update dict from the status_update_resp result array. Must contain a cmd_name key.

Returns:

The corresponding DeviceType, or None if the cmd_name is not recognized.

aiocamedomotic.models.parse_update(raw: dict[str, Any]) → DeviceUpdate

Parse a raw update dict into the appropriate typed DeviceUpdate subclass.

Parameters:

raw – A single update dict from the status_update_resp result array.

Returns:

A typed DeviceUpdate subclass instance. If the cmd_name is not recognized, a generic DeviceUpdate is returned so that the consumer can still access raw_data.

Constants

Constants for the CAME Domotic API.

class aiocamedomotic.const.AckErrorCode(*values)

ACK error codes returned by the CAME Domotic server.

Each member carries a human-readable message and an is_auth flag indicating whether the error is authentication-related.

Because AckErrorCode is an IntEnum, members compare equal to their integer value (e.g. AckErrorCode.INVALID_USER == 1).

Values:

  • INVALID_USER (1): Invalid user. [auth]

  • TOO_MANY_SESSIONS (3): Too many sessions during login. [auth]

  • JSON_SYNTAX_ERROR (4): Error occurred in JSON Syntax.

  • NO_SESSION_COMMAND_TAG (5): No session layer command tag.

  • UNRECOGNIZED_SESSION_COMMAND (6): Unrecognized session layer command.

  • NO_CLIENT_ID (7): No client ID in request.

  • WRONG_CLIENT_ID (8): Wrong client ID in request.

  • WRONG_APPLICATION_COMMAND (9): Wrong application command.

  • NO_REPLY (10): No reply to application command, maybe service down.

  • WRONG_APPLICATION_DATA (11): Wrong application data.

property is_auth: bool

Whether this error code indicates an authentication failure.

property message: str

Human-readable error message for this ACK code.

class aiocamedomotic.const.DeviceType(*values)

Device type IDs used by the CAME ETI/Domo system.

Each device in the CAME Domotic system is associated with one of these type identifiers. Not all device types are currently supported by this library.

Negative IDs are library-specific: they identify entity kinds that the CAME API does not assign a numeric type to.

Values:

  • LOADSCTRL_RELAY (-5)

  • LOADSCTRL_METER (-4)

  • ANALOG_INPUT (-3)

  • ENERGY_SENSOR (-2)

  • ANALOG_SENSOR (-1)

  • LIGHT (0)

  • OPENING (1)

  • THERMOSTAT (2)

  • PAGE (3)

  • SCENARIO (4)

  • CAMERA (5)

  • SECURITY_PANEL (6)

  • SECURITY_AREA (7)

  • SECURITY_SCENARIO (8)

  • SECURITY_INPUT (9)

  • SECURITY_OUTPUT (10)

  • GENERIC_RELAY (11)

  • GENERIC_TEXT (12)

  • SOUND_ZONE (13)

  • DIGITAL_INPUT (14)

  • TIMER (15)

class aiocamedomotic.const.UpdateIndicator(*values)

Known status-update indication cmd_names from the CAME API.

These identify the type of state change in a status_update_resp result item. Some indicators have two variants: one observed in real API traffic and one documented in API_reference.md. Both are mapped for firmware compatibility.

Values:

  • LIGHT (“light_switch_ind”)

  • OPENING (“opening_move_ind”)

  • RELAY (“relay_status_ind”)

  • THERMOSTAT (“thermo_zone_info_ind”)

  • DIGITAL_INPUT (“digitalin_status_ind”)

  • ANALOG_INPUT (“analogin_status_ind”)

  • SCENARIO_STATUS (“scenario_status_ind”)

  • SCENARIO_ACTIVATION (“scenario_activation_ind”)

  • ENERGY_METER (“meter_instant_power_ind”)

  • LOADSCTRL_METER (“loadsctrl_meter_ind”)

  • LOADSCTRL_RELAY (“loadsctrl_relay_ind”)

  • PLANT (“plant_update_ind”)

  • LIGHT_LEGACY (“light_update_ind”)

  • OPENING_LEGACY (“opening_update_ind”)

  • THERMOSTAT_LEGACY (“thermo_update_ind”)

  • RELAY_LEGACY (“relay_update_ind”)

  • DIGITAL_INPUT_LEGACY (“digitalin_update_ind”)

  • ANALOG_INPUT_LEGACY (“analogin_update_ind”)

  • TIMER (“timer_info_ind”)

  • SCENARIO_USER_LEGACY (“scenario_user_ind”)

  • TIMER_LEGACY (“timer_update_ind”)

Utilities

async aiocamedomotic.utils.async_is_came_endpoint(host: str, websession: ClientSession | None = None, timeout: int = 10) → bool

Check whether a host exposes the CAME Domotic API endpoint.

Performs a credential-free HTTP GET on the CAME API URL to determine if the host is a CAME ETI/Domo server. Suitable for network autodiscovery alongside CAME_MAC_PREFIXES.

Parameters:

  • host – IP address or hostname of the device to check (e.g., "192.168.1.100", "came-server.local").

  • websession – Optional aiohttp.ClientSession to reuse. When provided, the caller retains ownership and the session will not be closed by this function. When omitted, a temporary session is created and closed automatically.

  • timeout – HTTP request timeout in seconds (default: 10).

Returns:

True if the host responds with HTTP 200 on the CAME API endpoint, False otherwise (network error, timeout, wrong status, etc.).

Anonymization utilities for HTTP traffic logging.

This module provides automatic redaction of sensitive fields in CAME Domotic API request and response payloads, enabling safe sharing of traffic logs for debugging purposes.

The traffic logger (aiocamedomotic.traffic) is a child of the main library logger and can be configured independently:

import logging
logging.getLogger("aiocamedomotic.traffic").setLevel(logging.DEBUG)
aiocamedomotic.anonymizer.TRAFFIC_LOGGER = <Logger aiocamedomotic.traffic (WARNING)>

Dedicated logger for HTTP traffic. Enable at DEBUG level to see anonymized request/response payloads with elapsed times.

Errors

This module contains the exceptions that can be raised by the CAME Domotic API.

Exception hierarchy and suggested Home Assistant mapping:

exception aiocamedomotic.errors.CameDomoticAuthError

Raised when there is an authentication error with the remote server.

exception aiocamedomotic.errors.CameDomoticError

Base exception class for the CAME Domotic package.

exception aiocamedomotic.errors.CameDomoticServerError

Raised if an error occurs while interacting with the remote CAME Domotic server.

static create_ack_error(ack_code: int) → CameDomoticError

Create appropriate exception based on ACK error code.

Parameters:

ack_code (int) – The ACK error code from the server.

Returns:

Appropriate exception instance based on error code.

Return type:

CameDomoticError

static format_ack_error(ack_code: int) → str

Formats the ack code in a human-readable format.

Parameters:

ack_code (int) – The ACK error code from the server.

Returns:

The formatted error message.

Return type:

str

exception aiocamedomotic.errors.CameDomoticServerNotFoundError

Raised when the specified host is not available.

exception aiocamedomotic.errors.CameDomoticServerTimeoutError

Raised when a request to the CAME Domotic server times out.

This exception indicates a transient failure. When using this library with Home Assistant, it should be mapped to ConfigEntryNotReady to allow the integration to retry with exponential backoff.

See also the exception hierarchy mapping for Home Assistant integrations:

Auth module

This module manages the HTTP interaction with the CAME Domotic API.

Note

As a consumer of the CAME Domotic library, it’s quite unlikely that you will need to use this class directly: you should use the CameDomoticAPI and the CameEntity classes instead.

In case of special needs, consider requesting the implementation of the desired feature in the CAME Domotic library, or forking the library and implement the feature yourself.

class aiocamedomotic.auth.Auth(websession: ClientSession, host: str, username: str, password: str, *, close_websession_on_disposal: bool = False)

Class to make authenticated requests to the CAME Domotic API server.

Security features:

  • Credential protection — username and password are encrypted in memory using Fernet symmetric encryption with a runtime-generated key. Credentials are explicitly cleared on disposal and as a safety net on garbage collection.

Note

This class is not meant to be used directly, but through the CameDomoticAPI class. To create an instance of this class, use the factory method async_create.

async classmethod async_create(websession: ClientSession, host: str, username: str, password: str, *, close_websession_on_disposal: bool = False, command_timeout: int = 30) → Auth

Create an Auth instance.

Parameters:

  • websession (ClientSession) – the aiohttp client session.

  • host (str) – the host of the CAME Domotic server.

  • username (str) – the username to use for the authentication.

  • password (str) – the password to use for the authentication.

  • close_websession_on_disposal (bool, optional) – whether to close the websession when disposing the Auth instance (default: False).

  • command_timeout (int, optional) – the default timeout in seconds for commands sent to the server (default: 30s).

Raises:

CameDomoticServerNotFoundError – if the host doesn’t respond to an HTTP request or doesn’t expose the CAME Domotic API endopoint.

Returns:

the Auth instance.

Return type:

Auth

Note

The session is not logged in until the first request is made.

async async_dispose() → None

Dispose the Auth instance, eventually logging out if needed.

This method also explicitly clears sensitive attributes (username, password, and cipher_suite) to enhance security when the Auth instance is disposed.

async async_get_valid_client_id() → str

Get a valid client ID, eventually logging in if needed.

Returns:

the client ID.

Return type:

str

Raises:

CameDomoticAuthError – if an error occurs during the login.

async async_keep_alive() → None

Keep the session alive, eventually logging in again if needed.

Raises:
async async_login() → None

Login to the CAME Domotic server.

Raises:

CameDomoticAuthError – if an error occurs during the login.

async async_logout() → None

Logout from the CAME Domotic server.

Raises:

CameDomoticServerError – if an error occurs during the logout.

async static async_raise_for_status_and_ack(response: ClientResponse) → None

Check the response status and raise an error if necessary.

Parameters:

response (ClientResponse) – the response.

Raises:
async async_send_command(command: dict[str, Any], *, response_command: str | None = None, timeout: int | None = None, skip_ack_check: bool = False, command_type: str = 'sl_data_req', additional_payload: dict[str, Any] | None = None, _caller_holds_lock: bool = False) → dict[str, Any]

Send a command to the CAME Domotic server.

Parameters:

  • command (dict) – the command to send.

  • response_command (str, optional) – expected response command name to validate against the server response (default: None).

  • timeout (int | None, optional) – the timeout in seconds. If None, uses the instance-level command_timeout (default: 30s).

  • skip_ack_check (bool, optional) – whether to skip the ACK check (default: False).

  • command_type (str, optional) – the command type to send (default: “sl_data_req”).

  • additional_payload (dict, optional) – additional key-value pairs to include in the request payload (default: None).

  • _caller_holds_lock (bool, optional) – when True, the caller already holds self._lock and has validated the session, so this method uses self.client_id directly instead of calling async_get_valid_client_id() (which would deadlock). For internal use only (default: False).

Returns:

the JSON response from the server.

Return type:

dict

Raises:
async async_validate_host(timeout: int = 10) → None

Validate the host asynchronously using aiohttp.

Parameters:

timeout (int, optional) – the timeout in seconds (default: 10s).

Raises:

CameDomoticServerNotFoundError – if the host doesn’t respond to an HTTP request or doesn’t expose the CAME Domotic API endopoint.

backup_auth_credentials() → tuple[bytes | None, bytes | None, str, float, int, int]

Backup the current authentication credentials.

static create_cypher_suite() → Fernet

Create a cypher suite.

property current_username: str | None

Return the decrypted username for the current session, or None.

Returns:

The plaintext username, or None if the cipher suite has not been initialised (e.g. after async_dispose).

Return type:

str | None

Note

Usernames are not secret — they appear in plaintext in all API payloads. This property is intended for internal comparisons (e.g. preventing deletion of the current user). Avoid logging its return value unnecessarily.

get_endpoint_url() → str

Get the CAME Domotic endpoint URL.

Returns:

the endpoint URL.

Return type:

str

is_session_valid() → bool

Check whether the session is still valid or not.

restore_auth_credentials(backup_state: tuple[bytes | None, bytes | None, str, float, int, int]) → None

Restore authentication credentials from a backup.

Parameters:

backup_state (tuple) – Username and password.

update_auth_credentials(username: str, password: str) → None

Update the authentication credentials.

Parameters:

  • username (str) – New username.

  • password (str) – New password.

aiocamedomotic.auth.handle_came_domotic_errors(func: _F) → _F

Decorator to handle CAME Domotic API errors.

The decorator catches the following exceptions: - aiohttp.ClientResponseError: for HTTP errors (4xx, 5xx) - TimeoutError: for timeouts (asyncio.TimeoutError, ServerTimeoutError) - aiohttp.ClientError: for other network-related errors - CameDomoticAuthError: for authentication errors - any other exception: for unforeseen errors

Raises: