Api Module

class JciHitachi.api.Peripheral(peripheral_json: dict)[source]

Bases: object

Peripheral (Device) Information.

Parameters:: peripheral_json (dict) – Peripheral json of specific device.

classmethod from_device_names(peripherals_json: dict, device_names: list[str] | str | None) → dict[str, object][source]

Use device names to pick peripheral_jsons accordingly.

Parameters:

peripherals_json (dict) – Peripherals_json retrieved from GetPeripheralsByUser.
device_names (list of str or str or None) – Device name. If None is given, all available devices will be included, by default None.

Returns:

A dict of Peripheral instances with device name key.

Return type:

dict

property available: bool

Whether the device is available.

Returns:: Return True if the device is available.
Return type:: bool

property brand: str

Device brand.

Returns:: Device brand.
Return type:: str

property commander: JciHitachiCommand | None

Return a new JciHitachiCommand instance based on peripheral’s type.

Returns:: JciHitachiCommand instance.
Return type:: JciHitachiCommand or None

property gateway_id: int

Gateway ID.

Returns:: Gateway ID.
Return type:: int

property gateway_mac_address: str

Gateway mac address.

Returns:: Gateway mac address.
Return type:: str

property model: str

Device model.

Returns:: Device model.
Return type:: str

property name: str

Device name.

Returns:: Device name.
Return type:: str

property picked_peripheral: dict

Picked peripheral.

Returns:: Picked peripheral.
Return type:: dict

property status_code: str

Peripheral’s status code (LValue) reported by the API.

Returns:: Status code.
Return type:: str

property support_code: str

Peripheral’s support code (LValue) reported by the API.

Returns:: Status code.
Return type:: str

property supported_status: JciHitachiStatusSupport

Peripheral’s supported status converted from support_code.

Returns:: Supported status.
Return type:: JciHitachiStatusSupport

property type: str

Device type.

Returns:: Device type. If not supported, ‘unknown’ will be returned. (currently supports: AC, DH)
Return type:: str

class JciHitachi.api.JciHitachiAPI(email: str, password: str, device_names: list[str] | str | None = None, max_retries: int = 5, device_offline_timeout: float = 45.0, print_response: bool = False)[source]

Bases: object

Jci-Hitachi API.

Parameters:

email (str) – User email.
password (str) – User password.
device_names (list of str or str or None, optional) – Device names. If None is given, all available devices will be included, by default None.
max_retries (int, optional) – Maximum number of retries when setting status, by default 5.
device_offline_timeout (float, optional) – Device offline timeout, by default 45.0.
print_response (bool, optional) – If set, all responses of httpx and MQTT will be printed, by default False.

property peripherals: dict[str, Peripheral]

Picked peripherals.

Returns:: A dict of Peripherals.
Return type:: dict

property user_id: int | None

User ID.

Returns:: User ID.
Return type:: int

property task_id: int

Task ID.

Returns:: Serial number counted from 0, with maximum 999.
Return type:: int

login() → None[source]

Login API.

Raises:: RuntimeError – If a login error occurs, RuntimeError will be raised.

logout() → None[source]: Logout API.

change_password(new_password: str) → None[source]

Change password.

Parameters:: new_password (str) – New password.
Raises:: RuntimeError – If an error occurs, RuntimeError will be raised.

get_status(device_name: str | None = None) → dict[str, JciHitachiStatus][source]

Get device status after refreshing status.

Parameters:: device_name (str, optional) – Getting a device’s status by its name. If None is given, all devices’ status will be returned, by default None.
Returns:: Return a dict of JciHitachiStatus instances according to device type. For example, if the device type is AC, then return JciHitachiAC instance.
Return type:: dict of JciHitachiStatus.

get_supported_status(device_name: str | None = None) → dict[str, JciHitachiStatusSupport][source]

Get supported device status after refreshing status.

Parameters:: device_name (str, optional) – Getting a device’s status by its name. If None is given, all devices’ status will be returned, by default None.
Returns:: Return a dict of JciHitachiStatusSupport instances according to device type. For example, if the device type is AC, then return JciHitachiACSupport instance.
Return type:: dict of JciHitachiStatusSupport.

refresh_status(device_name: str | None = None) → None[source]

Refresh device status from the API.

Parameters:: device_name (str, optional) – Refreshing a device’s status by its name. If None is given, all devices’ status will be refreshed, by default None.
Raises:: RuntimeError – If an error occurs, RuntimeError will be raised.

set_status(status_name: str, status_value: int, device_name: str) → bool[source]

Set status to a peripheral.

Parameters:

status_name (str) – Status name, which has to be in idx dict. E.g. JciHitachiAC.idx
status_value (int) – Status value.
device_name (str) – Device name.

Returns:

Return True if the command has been successfully executed. Otherwise, return False.

Return type:

bool

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

class JciHitachi.api.AWSThing(thing_json: dict)[source]

Bases: object

AWS thing (device) information.

Parameters:: thing_json (dict) – Thing json of a specific device.

classmethod from_device_names(things_json: dict, device_names: list[str] | str | None) → dict[str, object][source]

Use device names to pick things_json accordingly.

Parameters:

things_json (dict) – things_json retrieved from aws_connection.GetAllDevice.
device_names (list of str or str or None) – Device name. If None is given, all available devices will be included, by default None.

Returns:

A dict of AWSThing instances with device name key.

Return type:

dict

property available: bool

Whether the device is available.

Returns:: Return True if the device is available.
Return type:: bool

property brand: str

Device brand.

Returns:: Device brand.
Return type:: str

property firmware_version: str

Firmware version.

Returns:: Device firmware version.
Return type:: str

property firmware_code: str

Firmware code.

Returns:: Device firmware code.
Return type:: str

property gateway_mac_address: str

Gateway mac address.

Returns:: Gateway mac address.
Return type:: str

property model: str

Device model.

Returns:: Device model.
Return type:: str

property name: str

Device name.

Returns:: Device name.
Return type:: str

property picked_thing: dict

Picked thing.

Returns:: Picked thing.
Return type:: dict

property shadow: dict | None

Thing’s shadow reported by the API.

Returns:: Shadow.
Return type:: dict

property status_code: JciHitachiAWSStatus | None

Thing’s status code reported by the API.

Returns:: Status code.
Return type:: JciHitachiAWSStatus

property support_code: JciHitachiAWSStatusSupport | None

Thing’s support code reported by the API.

Returns:: Status code.
Return type:: JciHitachiAWSStatusSupport

property monthly_data: list[dict] | None

Thing’s monthly data reported by the API.

Returns:: Monthly data.
Return type:: Optional[list[dict]]

property type: str

Device type.

Returns:: Device type. If not supported, ‘unknown’ will be returned.
Return type:: str

class JciHitachi.api.JciHitachiAWSAPI(email: str, password: str, device_names: list[str] | str | None = None, max_retries: int = 5, device_offline_timeout: float = 10.0, print_response: bool = False)[source]

Bases: object

Jci-Hitachi API.

Parameters:

email (str) – User email.
password (str) – User password.
device_names (list of str or str or None, optional) – Device names. If None is given, all available devices will be included, by default None.
max_retries (int, optional) – Maximum number of retries when setting status, by default 5.
device_offline_timeout (float, optional) – For future use.
print_response (bool, optional) – If set, all responses of httpx and MQTT will be printed, by default False.

property things: dict[str, AWSThing]

Picked things.

Returns:: A dict of AWSThing instances.
Return type:: dict of AWSThing

property task_id: int

Task ID.

Returns:: Serial number counted from 0, with maximum 999.
Return type:: int

login() → None[source]

Login API.

Raises:: RuntimeError – If a login error occurs, RuntimeError will be raised.

logout() → None[source]: Logout API.

reauth() → None[source]: Reauthenticate with AWS Cognito Service.

change_password(new_password: str) → None[source]

Change password.

Warning: Use this function carefully, be sure you specify a strong enough password; otherwise, your password might be accepted by the Hitachi account management but not be accepted by AWS Cognito or vice versa, which will result in a login failure in the APP.

Parameters:: new_password (str) – New password.
Raises:: RuntimeError – If an error occurs, RuntimeError will be raised.

refresh_monthly_data(months: int, device_name: str) → None[source]

Refresh available monthly data (power consumption) from the API.

Parameters:

months (int) – Number of months to get.
device_name (str) – Device name.

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

refresh_status(device_name: str | None = None, refresh_support_code: bool = False, refresh_shadow: bool = False) → None[source]

Refresh device status from the API.

Parameters:

device_name (str, optional) – Refreshing a device’s status by its name. If None is given, all devices’ status will be refreshed, by default None.
refresh_support_code (bool, optional) – Whether or not to refresh support code, by default False.
refresh_shadow (bool, optional) – Whether or not to refresh AWS IoT Shadow, by default False.

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.

get_status(device_name: str | None = None, legacy: bool = False) → dict[str, JciHitachiAWSStatus][source]

Get device status after refreshing status.

Parameters:

device_name (str, optional) – Getting a device’s status by its name. If None is given, all devices’ status will be returned, by default None.
legacy (bool, optional) – Whether or not to return status with legacy status name, by default False.

Returns:

A dict of JciHitachiAWSStatus instances.

Return type:

dict of JciHitachiAWSStatus.

set_status(status_name: str, device_name: str, status_value: int | None = None, status_str_value: str | None = None) → bool[source]

Set status to a thing. Either status_value or status_str_value must be specified.

Parameters:

status_name (str) – Status name.
device_name (str) – Device name.
status_value (int, optional) – Status value, by default None.
status_str_value (str, optional) – Status string value, by default None.

Returns:

Return True if the command has been successfully executed. Otherwise, return False.

Return type:

bool

Raises:

RuntimeError – If an error occurs, RuntimeError will be raised.