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_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_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_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_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_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_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_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:

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.

Values:

  • 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 are read-only devices that report their binary state (ACTIVE/IDLE). They cannot be controlled remotely.

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.

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.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.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

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

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.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)

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.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:
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:
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.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.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.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

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 room_ind: int

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.

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.

Values:

  • 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) - aiohttp.ServerTimeoutError: for timeouts - aiohttp.ClientError: for other network-related errors - CameDomoticAuthError: for authentication errors - any other exception: for unforeseen errors

Raises: