API documentation

Control Linear Garage Doors.

Linear

A Linear account.

Instantiate this class then run login() with your credentials to connect.

Example

from linear_garage_door import Linear

async def on_device_state_event(data: dict[str, dict[str, str] | str]):
    print(data)

linear = Linear(on_device_state_event=on_device_state_event)

# Log in to the account
await linear.login("email@email.com", "password", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

# Get the sites on the account
sites = await linear.get_sites()

# Loop through each site and get the devices
for site in sites:
    devices = await linear.get_devices(site["id"])
    for device in devices:
        print("")
        print(device["name"], "----")
        device_state = await linear.get_device_state(device["id"])
        for key in device_state.keys():
            print(key, "--")
            print("")
            for attribute in device_state[key].keys():
                print(attribute, "=", device_state[key][attribute])
            print("")

await linear.close()

__init__(on_device_state_event=None)

Initialize the Linear account.

Parameters:

Name	Type	Description	Default
on_device_state_event	function | None	Pass a function to subscribe to device state events. The function provided will be called with the data similar to the data returned by login(). Defaults to None.	None

close() async

Close the WebSocket.

get_device_state(device_id) async

Get state of device.

Example

from linear_garage_door import Linear

async def on_device_state_event(data: dict[str, dict[str, str] | str]):
    print(data)

linear = Linear(on_device_state_event=on_device_state_event)

# Log in to the account
await linear.login("email@email.com", "password", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

# Get the sites on the account
sites = await linear.get_sites()

# Loop through each site and get the devices
for site in sites:
    devices = await linear.get_devices(site["id"])
    for device in devices:
        print("")
        print(device["name"], "----")
        device_state = await linear.get_device_state(device["id"])
        for key in device_state.keys():
            print(key, "--")
            print("")
            for attribute in device_state[key].keys():
                print(attribute, "=", device_state[key][attribute])
            print("")

await linear.close()

Parameters:

Name	Type	Description	Default
device_id	str	The device ID to get the state of.	required

Raises:

Type	Description
NotOpen	The WebSocket has not been opened.

Returns:

Type	Description
dict[str, dict[str, str]]	A dictionary that shows each subdevice and their respective states.

get_devices(site) async

Get devices available under a specific site.

Example

from linear_garage_door import Linear

linear = Linear()
await linear.login("email@email.com", "password", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

sites = await linear.get_sites()
for site in sites:
    devices = await linear.get_devices(site["id"])
    for device in devices:
        print(device["name"], "(", device["id"], ") has the following subdevices:")
        for subdevice in device["subdevices"]:
            print(subdevice)

await linear.close()

Parameters:

Name	Type	Description	Default
site	str	The site ID to fetch the devices from. Get site IDs by calling get_sites().	required

Raises:

Type	Description
NotOpen	The WebSocket has not been opened.

Returns:

Type	Description
list[dict[str, list[str] | str]]	A list of dictionaries that contains the ID, name, and subdevices of that device. (Subdevices usually are GDO, Light, etc...)

get_sites() async

Get sites available under this account.

Example

from linear_garage_door import Linear

linear = Linear()
await linear.login("email@email.com", "password", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

sites = await linear.get_sites()
for site in sites:
    print(site["name"], "has id", site["id"])

await linear.close()

Raises:

Type	Description
NotOpen	The WebSocket has not been opened.

Returns:

Type	Description
list[dict[str, str]]	A list of dicts that contain the device's ID and name.

login(email, password, device_id=None, client_session=None) async

Logs in to a Linear account.

Tip

Need a device ID? Grab one here.

Example

from linear_garage_door import Linear

linear = Linear()
await linear.login("email@email.com", "password", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

await linear.close()

Parameters:

Name	Type	Description	Default
email	str	The email of the account to log in to.	required
password	str	The password of the account to log in to.	required
device_id	str | None	The device ID of your choice. Must be a UUID. Defaults to a random UUID.	None

Raises:

Type	Description
InvalidLogin	The login provided is invalid.
InvalidDeviceID	The device ID provided is invalid.

Returns:

Type	Description
dict[str, Any] | None	A dict with the type of response, most likely "WELCOME", the headers of the response, and the body.

operate_device(device_id, subdevice, subdevice_state) async

Operate a device.

Here are the known states for each subdevice:

• GDO: Open or Close (Not Closed!)
• Light: On or Off

More reverse engineering will be required in the future for setting the Light brightness and getting the progress of door opening.

This does not return anything. Events will be fired from the server and can give you a state.

Example

from linear_garage_door import Linear

linear = Linear()

await linear.login("email@email.com", "password", "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx")

await linear.operate_device(device["id"], "GDO", "Open")

Parameters:

Name	Type	Description	Default
device_id	str	The device ID you want to operate. You can get this from get_devices()	required
subdevice	str	The subdevice you want to operate. The list of subdevices is also available from get_devices()	required
subdevice_state	str	The state to set the subdevice to. I don't know where the full list of states are, but you can get a good guess from get_device_state()	required

Raises:

Type	Description
NotOpen	The WebSocket has not been opened.

errors

InvalidDeviceIDError

Bases: Exception

The device ID provided is invalid.

InvalidLoginError

Bases: Exception

The login provided is invalid.

NotOpenError

Bases: Exception

The WebSocket has not been opened.