ShadeConnector CLI

This CLI wraps the Connector cloud API used by the ShadeConnector Android application and now also speaks the local multicast protocol emitted by the Connector hub. It lets you log in, list your devices, and send open/close commands to motorised blinds from the terminal—either through the cloud or directly on your LAN once the necessary tokens have been captured.

Further reading:

• RESEARCH.md summarises the decompiled Android app (endpoints, hashing, LAN protocol).
• ARCHITECTURE.md documents this CLI’s modules and data flow.

Important: The tool talks directly to the production ShadeConnector API. Use it responsibly, and only with credentials/devices you own.

Prerequisites

• Node.js 18 or newer.
• Network access to the Connector cloud endpoints (default: https://connectoreu.shadeconnector.com:8443).

Setup

npm install

This installs the dependencies and creates a node_modules folder plus package-lock.json.

Usage

Run the CLI with npx or via the locally installed binary:

npx shadeconnector --help

Global options allow you to override the API base URL, app code, timeout, TLS behaviour, and LAN socket parameters.

Programmatic usage

Install the package (once published) via npm:

npm install shadeconnector-cli

Node.js (cloud + LAN)

const { ConnectorClient } = require('shadeconnector-cli');
const { LanController } = require('shadeconnector-cli/node');

const client = new ConnectorClient();
const devices = await client.getDevices(accessToken);

const lan = new LanController({ accessToken });
await lan.start();
await lan.setBlindPosition(childMac, deviceType, 50);
await lan.stop();

• The default import (shadeconnector-cli) exposes cross-platform helpers (ConnectorClient, helper functions).
• Node-specific features (LanController, config helpers) live under the shadeconnector-cli/node subpath to keep browser bundles lean.

Browser (cloud-only)

import { ConnectorClient } from 'shadeconnector-cli';

const client = new ConnectorClient();
const result = await client.login(email, password);

In browsers, only the REST API helpers are available; LAN multicast functionality depends on Node.js UDP sockets and is therefore excluded.

1. Log in

npx shadeconnector login -u [email protected] -p yourPassword

By default the CLI reproduces the Android app’s bcrypt-based "v2" hashing (MD5 → low16 → Base64 → bcrypt). The command stores your access and refresh tokens in ~/.shadeconnector-cli.json. Use --md5 to fall back to the legacy MD5 scheme, --hashed if you want to supply the final hash yourself, or --no-save to skip persisting tokens.

2. List devices

npx shadeconnector devices

This prints a table with the MAC address, device type, and current/target position (when available). The command also caches device metadata locally so later actions can infer the deviceType automatically. Use --json for the raw API payload.

To discover hubs and capture their LAN tokens directly from the multicast channel, run:

npx shadeconnector lan-devices --listen 4000

Time is milliseconds; adjust based on how long you want to listen for heartbeats. The command warns on timeouts but keeps any packets it overhears.

3. Control blinds

# Fully open
npx shadeconnector open --mac AA:BB:CC:DD:EE:FF

# Fully close (targetPosition = 100)
npx shadeconnector close --mac AA:BB:CC:DD:EE:FF

# Move to a custom position
npx shadeconnector open --mac AA:BB:CC:DD:EE:FF --position 30

If the CLI cannot find the device type in its cache, provide it explicitly via --type <deviceType>.

Add --status to the open/close command to fetch and display the device state immediately after the control request.

LAN mode

Once you have logged in (so the CLI can derive the AES key from your access token) you can operate purely on the LAN multicast channel:

# Discover hubs/devices and their LAN tokens
npx shadeconnector lan-devices --listen 4000

# Drive a blind locally (no cloud call)
npx shadeconnector open --mac AA:BB:CC:DD:EE:FF --lan --status

# Fetch state over LAN
npx shadeconnector status --mac AA:BB:CC:DD:EE:FF --lan

Global --lan-interface and --lan-timeout options adjust the multicast binding and acknowledgement timeout if needed. The CLI stores discovered LAN tokens alongside your other configuration data so subsequent runs can reuse them without re-discovery.

4. Check a single device

npx shadeconnector status --mac AA:BB:CC:DD:EE:FF

Returns the detailed deviceService/getDeviceInfo payload and shows parsed position data. Add --json to see the raw response.

Configuration file

• Location: ~/.shadeconnector-cli.json
• Contents: stored tokens, latest base URL/app code, and a cache of known devices.
• Print the path with npx shadeconnector config-path.

Advanced options

• --base-url <url>: Point the CLI at a different Connector environment.
• --app-code <code>: Override the appCode sent during authentication (default is 92c9c09a-b7b5-4c6c-bbb9-028b761763d9).
• --timeout <ms>: Set a custom HTTP timeout.
• --insecure: Allow self-signed certificates (sets rejectUnauthorized: false).
• --token <token>: Supply a token manually instead of using the stored one.
• --lan-interface <address>: Bind the multicast socket to a specific local interface (helpful on multi-homed hosts).
• --lan-timeout <ms>: Override the acknowledgement timeout used for LAN requests.
• --md5: Use MD5 hashing when sending the login request (legacy servers).
• --hashed: Send the password exactly as provided (no hashing).

Testing

npm test

The suite exercises the password hashing helpers and verifies that LAN AES token generation matches the Android implementation.

Notes

• The CLI checks retCode values and echoes errors returned by the service (e.g. needing to re-authenticate).
• Cloud and LAN modes share the same device cache; ensure you target child MACs when moving blinds.
• Extending LAN support (e.g. scenes, group operations) can be built on LanController.sendOperation.
• When consuming the library from Node.js, import LanController from shadeconnector-cli/node; browser bundles should stick to the root export to avoid pulling in UDP/FS dependencies.

Troubleshooting

• Error 20102 or 20108 means the session expired—run shadeconnector login again.
• If the TLS handshake fails, try --insecure (only if you trust the endpoint) or verify local CA certificates.
• Use --json outputs to inspect returned payloads when adding new behaviour.