Class OverkizClient

Namespace

OverKizApi

Assembly

OverKizApi.dll

C# client for the Overkiz API, functionally equivalent to the Python python-overkiz-api library. Supports cloud (standard, Somfy OAuth, CozyTouch JWT, Nexity SSO) and local API modes.

public sealed class OverkizClient : IAsyncDisposable

Inheritance

object

OverkizClient

Implements

IAsyncDisposable

Inherited Members

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

object.GetType()

Constructors

OverkizClient(string, string, OverkizServer, string?, HttpClient?)

Creates a new OverkizClient.

public OverkizClient(string username, string password, OverkizServer server, string? token = null, HttpClient? httpClient = null)

Parameters

username string

Account username / email.

password string

Account password.

server OverkizServer

Target OverkizServer (use SupportedServers).

token string

Pre-existing bearer token (optional; bypasses login).

httpClient HttpClient

Optional externally-managed HttpClient. If null, one is created internally.

Properties

ApiType

Whether the client is operating against the cloud API or a local gateway API.

public APIType ApiType { get; }

Property Value

APIType

Devices

All devices from the most recently retrieved setup. Populated by GetSetup(bool); empty until that method is called.

public List<Device> Devices { get; }

Property Value

List<Device>

EventListenerId

The event listener ID returned by the last successful RegisterEventListener() call, or null if no listener is currently registered.

public string? EventListenerId { get; }

Property Value

string

Gateways

All gateways from the most recently retrieved setup. Populated by GetSetup(bool); empty until that method is called.

public List<Gateway> Gateways { get; }

Property Value

List<Gateway>

Password

Account password used to authenticate with the Overkiz server.

public string Password { get; }

Property Value

string

SelectedGatewayId

The currently selected Rexel gateway ID, or null if none has been selected.

public string? SelectedGatewayId { get; }

Property Value

string

Server

The target server this client is connected to.

public OverkizServer Server { get; }

Property Value

OverkizServer

Setup

The most recently retrieved Setup, or null if GetSetup(bool) has not yet been called.

public Setup? Setup { get; }

Property Value

Setup

Username

Account username or e-mail address used to authenticate with the Overkiz server.

public string Username { get; }

Property Value

string

Methods

ActivateLocalToken(string, string, string, string)

Registers a generated local API token on the gateway so that it can be used for local API calls.

public Task<string> ActivateLocalToken(string gatewayId, string token, string label, string scope = "devmode")

Parameters

gatewayId string

Serial number of the gateway to register the token on.

token string

The raw token string returned by GenerateLocalToken(string).

label string

A human-readable label to identify this token in the token list.

scope string

Access scope to grant (default "devmode").

Returns

Task<string>

The request ID of the activation request.

Exceptions

OverkizException

Thrown when the server does not return a request ID.

CancelExecution(string)

Cancels a running or queued execution.

public Task CancelExecution(string execId)

Parameters

execId string

The execution ID returned by ExecuteDeviceAction(string, IEnumerable<Command>, string) or ExecuteScenario(string).

Returns

Task

CozytouchLogin()

Authenticates against the Atlantic/CozyTouch OAuth endpoint and returns the JWT token required for the subsequent Overkiz login call.

public Task<string> CozytouchLogin()

Returns

Task<string>

The JWT string to pass to the Overkiz login endpoint.

Exceptions

CozyTouchBadCredentialsException

Thrown when the Atlantic OAuth server rejects the credentials.

CozyTouchServiceException

Thrown when the Atlantic token or JWT endpoint returns an unexpected response.

DeleteLocalToken(string, string)

Revokes and deletes a local API token.

public Task<bool> DeleteLocalToken(string gatewayId, string uuid)

Parameters

gatewayId string

Serial number of the gateway the token belongs to.

uuid string

UUID of the token to delete (see Uuid).

Returns

Task<bool>

true on success.

DiscoverRexelGateways()

Discovers Rexel homes and gateways available to the current bearer token.

public Task<IReadOnlyList<GatewayCandidate>> DiscoverRexelGateways()

Returns

Task<IReadOnlyList<GatewayCandidate>>

A read-only list of gateway candidates.

Exceptions

InvalidOperationException

Thrown when the current server is not Rexel or no bearer token is available.

DisposeAsync()

Releases resources owned by this client. If an event listener is registered it is unregistered (best-effort) before disposal. If the HttpClient was created internally it is also disposed.

public ValueTask DisposeAsync()

Returns

ValueTask

ExecuteDeviceAction(string, IEnumerable<Command>, string)

Sends a set of commands to a device as a single execution action.

public Task<string> ExecuteDeviceAction(string deviceUrl, IEnumerable<Command> commands, string label = "Execute")

Parameters

deviceUrl string

URL of the target device.

commands IEnumerable<Command>

One or more Command objects to execute.

label string

Optional human-readable label recorded in the execution history.

Returns

Task<string>

The execution ID (execId) assigned by the server.

Exceptions

OverkizException

Thrown when the server does not return an execution ID.

ExecuteScenario(string)

Triggers immediate execution of a stored scenario.

public Task<string> ExecuteScenario(string oid)

Parameters

oid string

The OID of the scenario to execute (see Oid).

Returns

Task<string>

The execution ID assigned by the server.

Exceptions

OverkizException

Thrown when the server does not return an execution ID.

ExecuteScheduledScenario(string, long)

Schedules a scenario to execute at a specific point in time.

public Task<string> ExecuteScheduledScenario(string oid, long timestamp)

Parameters

oid string

The OID of the scenario to schedule.

timestamp long

Unix epoch millisecond timestamp at which to trigger the scenario.

Returns

Task<string>

The trigger ID assigned by the server.

Exceptions

OverkizException

Thrown when the server does not return a trigger ID.

FetchEvents()

Fetches all queued events from the registered event listener and clears the server-side queue. Call this method repeatedly (polling) to receive device state change notifications.

public Task<IReadOnlyList<EventObject>> FetchEvents()

Returns

Task<IReadOnlyList<EventObject>>

A list of EventObject objects; may be empty if no events are pending.

Exceptions

NoRegisteredEventListenerException

Thrown when no event listener is registered. Call RegisterEventListener() first.

FetchEventsRaw()

Like FetchEvents() but also returns the raw JSON response string for diagnostics.

public Task<(IReadOnlyList<EventObject> Events, string RawJson)> FetchEventsRaw()

Returns

Task<(IReadOnlyList<EventObject> Events, string RawJson)>

GenerateLocalToken(string)

Generates a new local API token for the specified gateway. The token must then be activated with ActivateLocalToken(string, string, string, string) before it can be used.

public Task<string> GenerateLocalToken(string gatewayId)

Parameters

gatewayId string

Serial number of the gateway to generate a token for.

Returns

Task<string>

The raw token string to pass to ActivateLocalToken(string, string, string, string).

Exceptions

OverkizException

Thrown when the server does not return a token.

GetCurrentExecutions()

Returns all executions that are currently active (in-progress or queued) on the gateway.

public Task<IReadOnlyList<Execution>> GetCurrentExecutions()

Returns

Task<IReadOnlyList<Execution>>

A read-only list of Execution objects; empty if nothing is running.

GetDevice(string)

Returns a single device identified by its URL.

public Task<Device> GetDevice(string deviceUrl)

Parameters

deviceUrl string

The device URL (e.g. io://1234-5678-9012/12345678).

Returns

Task<Device>

The matching Device.

Exceptions

OverkizException

Thrown when the response cannot be deserialised.

GetDeviceStates(string)

Returns the current live states for a device.

public Task<IReadOnlyList<State>> GetDeviceStates(string deviceUrl)

Parameters

deviceUrl string

The device URL to query.

Returns

Task<IReadOnlyList<State>>

A read-only list of State objects.

GetDevices()

Returns all devices registered across all gateways in the setup.

public Task<IReadOnlyList<Device>> GetDevices()

Returns

Task<IReadOnlyList<Device>>

A read-only list of Device objects.

GetExecutionHistory()

Returns the execution history log stored on the gateway.

public Task<IReadOnlyList<HistoryExecution>> GetExecutionHistory()

Returns

Task<IReadOnlyList<HistoryExecution>>

A read-only list of HistoryExecution records, most-recent first.

GetGateways()

Returns all gateways registered in the setup.

public Task<IReadOnlyList<Gateway>> GetGateways()

Returns

Task<IReadOnlyList<Gateway>>

A read-only list of Gateway objects.

GetLocalTokens(string, string)

Returns all active local API tokens for a gateway filtered by scope.

public Task<IReadOnlyList<LocalToken>> GetLocalTokens(string gatewayId, string scope = "devmode")

Parameters

gatewayId string

Serial number of the gateway to query.

scope string

Token scope to filter by (default "devmode").

Returns

Task<IReadOnlyList<LocalToken>>

A read-only list of LocalToken descriptors.

GetPlaces()

Returns the root of the place hierarchy (house → floors → rooms).

public Task<Place> GetPlaces()

Returns

Task<Place>

The root Place containing all sub-places.

Exceptions

OverkizException

Thrown when the response cannot be deserialised.

GetScenarios()

Returns all named scenarios (action groups) stored in the setup.

public Task<IReadOnlyList<Scenario>> GetScenarios()

Returns

Task<IReadOnlyList<Scenario>>

A read-only list of Scenario objects.

GetSetup(bool)

Retrieves the complete home setup including all gateways, devices, zones, places and location. The result is cached; pass refresh as true to force a fresh API call.

public Task<Setup> GetSetup(bool refresh = false)

Parameters

refresh bool

When true the cached result is discarded and a new API call is made.

Returns

Task<Setup>

The Setup for the authenticated account.

Exceptions

OverkizException

Thrown when the response cannot be deserialised.

GetSetupOption(string)

Returns a specific option subscription by option ID.

public Task<OptionObject?> GetSetupOption(string option)

Parameters

option string

Option ID to look up (e.g. "ADVANCED_SCENARIOS").

Returns

Task<OptionObject>

The OptionObject, or null if the option is not subscribed.

GetSetupOptionParameter(string, string)

Returns a single configuration parameter of a setup option.

public Task<OptionParameter?> GetSetupOptionParameter(string option, string parameter)

Parameters

option string

Option ID (e.g. "ADVANCED_SCENARIOS").

parameter string

Parameter name to retrieve.

Returns

Task<OptionParameter>

The OptionParameter, or null if not found.

GetSetupOptions()

Returns all option subscriptions active on the authenticated setup.

public Task<IReadOnlyList<OptionObject>> GetSetupOptions()

Returns

Task<IReadOnlyList<OptionObject>>

A read-only list of OptionObject objects.

Login(bool)

Authenticate and open an API session. Must be called before other operations unless a token was supplied.

public Task<bool> Login(bool registerEventListener = true)

Parameters

registerEventListener bool

Register an event listener after login (default true).

Returns

Task<bool>

NexityLogin()

Authenticates against the Nexity AWS Cognito SRP endpoint and returns the SSO token required for the subsequent Overkiz login call.

public Task<string> NexityLogin()

Returns

Task<string>

The Nexity SSO token string.

Remarks

This method is a stub. Nexity authentication requires the AWS Cognito SRP protocol which depends on AWSSDK.CognitoIdentityProvider. Add that package and override (or replace) this method with a real SRP implementation.

Exceptions

NotSupportedException

Always thrown by the default stub implementation.

RefreshAllDeviceStates()

Asks the gateway to refresh all device states from the physical devices. Updated states will be pushed through the event listener.

public Task RefreshAllDeviceStates()

Returns

Task

RefreshToken()

Refreshes the Somfy access token using the stored refresh token. This is called automatically by RefreshTokenIfExpired() when the token is near expiry; you do not normally need to call it manually.

public Task RefreshToken()

Returns

Task

Remarks

No-op if the current server is not SupportedServers[SomfyEurope].

Exceptions

InvalidOperationException

Thrown when no refresh token is available (i.e. Login(bool) was not called first).

SomfyBadCredentialsException

Thrown when the refresh token has been revoked.

SomfyServiceException

Thrown when the Somfy token endpoint returns an unexpected response.

RegisterEventListener()

Register an event listener to receive device state changes.

public Task RegisterEventListener()

Returns

Task

Remarks

The assigned listener ID is stored in EventListenerId after this call completes.

Exceptions

OverkizException

Thrown when the server does not return a valid listener ID.

SelectRexelGateway(string)

Selects the Rexel gateway to scope subsequent requests to.

public void SelectRexelGateway(string gatewayId)

Parameters

gatewayId string

Gateway identifier returned by DiscoverRexelGateways().

Exceptions

InvalidOperationException

Thrown when the current server is not Rexel.

SomfyTahomaGetAccessToken()

Authenticate via Somfy identity and acquire an access token.

public Task<string> SomfyTahomaGetAccessToken()

Returns

Task<string>

The raw access token string stored in _accessToken.

Exceptions

SomfyBadCredentialsException

Thrown when the supplied credentials are rejected by the Somfy OAuth server.

SomfyServiceException

Thrown when the Somfy token endpoint returns an unexpected response.

UnregisterEventListener()

Unregisters the event listener and clears EventListenerId. Safe to call when no listener is registered (no-op).

public Task UnregisterEventListener()

Returns

Task