Hunter Douglas PowerView (Gen 3)

Local Gateway REST API driver for Hunter Douglas PowerView Gen 3 motorized shades. One Gateway is one device; every paired shade is a zone keyed by its PowerView shade id. Roller, roman, duette, silhouette, pirouette, and banded shades are all supported by the same /home/shades API.

The driver targets the Gen 3 Gateway hardware introduced in 2022 — the older Gen 2 Hub speaks a different, incompatible XML-style API and is not supported by this driver.

Prerequisites

• A PowerView Gen 3 Gateway running stock firmware. The Gen 3 Gateway is a small black puck sold as PWGB / PV3-HUB; if you have the older square hub it is Gen 2 and this driver will not connect.
• The Gateway must be reachable on TCP port 80 from the GEM host.
• All shades that GEM should control must be paired with the Gateway from the PowerView mobile app first. GEM does not perform shade pairing.
• A static DHCP reservation for the Gateway is strongly recommended — the API does not advertise hostnames.

Setup

1. In the PowerView mobile app, open Settings → Network Information and copy the Gateway IP address.
2. On the Devices page choose System → Devices → Add Device and pick the driver hunter_douglas_powerview. Set:
   • ip — the Gateway IP from step 1.
   • port — defaults to 80; only change if a port mapping is in place.
   • status_interval — default 10000 ms; raise for very large installs.
3. Save the device. Once it shows connected in the Devices grid, run the get_devices command. The response is a JSON array of shade descriptors; note each shade's id.
4. Create the zones yourself — the driver does not auto-create them. It only publishes position and battery readings to zones that already exist and are bound to this Gateway. For each shade, add one zone under Zones, bound (Device field) to this PowerView device:
   • Subsystem — a default GEM install ships a Shades subsystem (shades); use it. The driver hints shade (singular), which does not match the seeded shades, so the zone editor will not pre-select it — choose Shades yourself.
   • Address — the shade id (integer) from step 3.
   • Leave Open State Threshold (open_threshold) unset unless you want a non-default cutoff (default 5 — any reported primary position of 5% or more reads as open).
5. Optionally run get_scenes to enumerate PowerView scenes. Each scene has an id; create GEM macros that issue activate_scene with that scene_id to weave PowerView scenes into GEM automations.

Device attributes

Attribute	Required	Description
ip	yes	LAN IP of the PowerView Gen 3 Gateway.
port	no	HTTP port; default 80.
status_interval	no	Poll cadence in milliseconds; default 10000.
request_timeout	no	Per-request timeout in milliseconds; default 10000.

Zone attributes

Attribute	Required	Description
address	yes	PowerView shade id (integer).
open_threshold	no	Primary-position percentage at or above which the zone state reports open. Default 5.

Polled state (zone read-back)

On connect and on every poll the driver writes the current shade state onto each bound zone. These are read-only telemetry — use them as trigger sources or on zone tiles, don't edit them by hand:

Attribute	Type	Notes
state	string	open / closed, derived from primary position vs open_threshold.
level	int	Primary position as 0..100 (100 = fully open, 0 = fully closed).
battery_status	string	Gateway-reported battery status code. Battery-powered shades only — hardwired shades never report it.
battery_strength	int	Gateway-reported battery strength reading. Battery-powered shades only.

Battery telemetry is a good low-battery trigger source: build an attribute trigger on battery_strength (or battery_status) to flag shades that need a recharge before they stop responding mid-travel.

Zone address format

Plain integer shade id as returned by /home/shades, e.g. 17. The id is stable across Gateway reboots but is reassigned if a shade is factory-reset and re-paired — re-run get_devices after any re-pairing and refresh the affected zone.address values.

Supported commands

Command	Args	What it does
open	address	Drive shade primary position to 1.0 (fully open).
close	address	Drive shade primary position to 0.0 (fully closed).
stop	address	Halt the motor mid-travel.
set_level	address, level	Drive primary to level% (0..100); accepts 0..1 floats too.
set_position	address, primary, secondary, tilt	Set the full position vector. Any field omitted is left at its cached value.
jog	address	Briefly jog the shade to physically identify it.
calibrate	address	Run the shade's self-calibration routine.
activate_scene	scene_id	Fire a PowerView scene.
get_devices	—	List all paired shades.
get_scenes	—	List all PowerView scenes.
get_status	address	Live-read one shade's descriptor (position + battery) from the Gateway and refresh its cache.

set_level always writes the primary channel. Use set_position to drive secondary (middle rail on top-down/bottom-up duette / silhouette / banded shades) or tilt (pirouette / silhouette tilt-only).

Known limitations

• PowerView automation/schedule CRUD is out of scope — manage automations from the PowerView app.
• Multi-room scene grouping is exposed only at the scene level; GEM cannot edit which shades belong to a scene.
• Repeater diagnostics and firmware updates are out of scope.
• The legacy Gen 2 Hub (different, incompatible XML-style API) is not supported. If you have Gen 2 hardware, contact Hunter Douglas about upgrading to the Gen 3 Gateway.
• Battery-powered shades sleep between moves; their reported position can lag the physical position by a few seconds after a manual cord pull.

Troubleshooting

Connection test fails with ECONNREFUSED — verify port 80 reachability with curl http://<gateway-ip>/home/shades (the endpoint the driver polls; it should return a JSON array). If the LAN segments are firewalled, route the GEM host to the Gateway subnet.

get_devices returns an empty array — shades have to be paired into the Gateway from the PowerView app first. GEM cannot pair shades.

Set-position commands return 404 — shade ids change after a factory reset or re-pairing. Re-run get_devices and update any zone whose address no longer appears.

Shade state reads "backwards" (e.g. a top-down shade you want to read open at a low primary position) — this driver has no direction-invert switch and does not use relay-state mapping. state is derived strictly from primary position ≥ open_threshold, and level always tracks primary position (100 = fully open per PowerView). You can move where the open/closed line falls by raising or lowering open_threshold, but you cannot reverse the direction of travel from GEM — set the shade's travel limits and orientation in the PowerView app instead.

Polling spam — raise status_interval. Past 30 s the position update can lag a manual move noticeably, so 10 s is a good default; 30–60 s is fine in installs that never touch the shades manually.