harmony-hub-setup 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. harmony_hub_setup-0.2.0/PKG-INFO +295 -0
  2. harmony_hub_setup-0.2.0/README.md +269 -0
  3. harmony_hub_setup-0.2.0/pyproject.toml +37 -0
  4. harmony_hub_setup-0.2.0/src/harmony_hub_setup/__init__.py +5 -0
  5. harmony_hub_setup-0.2.0/src/harmony_hub_setup/bt_socket.py +152 -0
  6. harmony_hub_setup-0.2.0/src/harmony_hub_setup/cli.py +721 -0
  7. harmony_hub_setup-0.2.0/src/harmony_hub_setup/client.py +189 -0
  8. harmony_hub_setup-0.2.0/src/harmony_hub_setup/lan_client.py +156 -0
harmony_hub_setup-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,295 @@
1
+ Metadata-Version: 2.4
2
+ Name: harmony-hub-setup
3
+ Version: 0.2.0
4
+ Summary: Configure a Logitech Harmony Hub over Bluetooth (Wi-Fi setup, scanning, status)
5
+ Keywords: harmony,logitech,bluetooth,rfcomm,home-automation,iot,wifi,provisioning
6
+ Author: Corey Gallon
7
+ Author-email: Corey Gallon <366332+captivus@users.noreply.github.com>
8
+ License-Expression: MIT
9
+ Classifier: Development Status :: 4 - Beta
10
+ Classifier: Environment :: Console
11
+ Classifier: Intended Audience :: End Users/Desktop
12
+ Classifier: License :: OSI Approved :: MIT License
13
+ Classifier: Operating System :: POSIX :: Linux
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Programming Language :: Python :: 3.10
16
+ Classifier: Programming Language :: Python :: 3.11
17
+ Classifier: Programming Language :: Python :: 3.12
18
+ Classifier: Programming Language :: Python :: 3.13
19
+ Classifier: Topic :: Home Automation
20
+ Classifier: Topic :: Utilities
21
+ Requires-Python: >=3.10
22
+ Project-URL: Homepage, https://github.com/captivus/harmony-hub-setup
23
+ Project-URL: Repository, https://github.com/captivus/harmony-hub-setup
24
+ Project-URL: Issues, https://github.com/captivus/harmony-hub-setup/issues
25
+ Description-Content-Type: text/markdown
26
+
27
+ # Harmony Hub Setup
28
+
29
+ [![PyPI version](https://img.shields.io/pypi/v/harmony-hub-setup.svg)](https://pypi.org/project/harmony-hub-setup/)
30
+ [![Python versions](https://img.shields.io/pypi/pyversions/harmony-hub-setup.svg)](https://pypi.org/project/harmony-hub-setup/)
31
+ [![PyPI status](https://img.shields.io/pypi/status/harmony-hub-setup.svg)](https://pypi.org/project/harmony-hub-setup/)
32
+ [![PyPI downloads](https://img.shields.io/pypi/dm/harmony-hub-setup.svg)](https://pypi.org/project/harmony-hub-setup/)
33
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
34
+ [![Platform: Linux](https://img.shields.io/badge/Platform-Linux-blue.svg)](#requirements)
35
+
36
+ Configure a factory-reset Logitech Harmony Hub far enough for the official
37
+ Harmony mobile app to finish account/profile restore.
38
+
39
+ This tool performs **Phase 1** only:
40
+
41
+ 1. Connects to the hub over Bluetooth.
42
+ 2. Finds the target Wi-Fi network.
43
+ 3. Connects the hub to Wi-Fi.
44
+ 4. Sends the dummy discovery provisioning command (`mode=2`).
45
+ 5. Verifies the hub is still pre-account and reachable on the local network.
46
+
47
+ The official Harmony iPhone or Android app performs **Phase 2**:
48
+
49
+ 1. Finds the hub on the network.
50
+ 2. Logs in to the Logitech account.
51
+ 3. Restores the hub's devices, activities, and account profile.
52
+
53
+ ## Why this exists
54
+
55
+ Since early 2025, connecting to my Logitech Harmony Hub from the iPhone app
56
+ has become increasingly difficult and buggy. The usual recovery path --
57
+ factory reset the hub and let the iPhone app re-provision it from my Logitech
58
+ account -- has itself become fraught and unreliable on the iPhone in that
59
+ same window. The hub frequently fails to join Wi-Fi during the app's setup
60
+ flow even when the network is healthy and well in range, leaving the hub
61
+ unreachable.
62
+
63
+ This tool exists to take that fragile Wi-Fi join out of the iPhone app's
64
+ hands. It does the Bluetooth handshake, Wi-Fi join, and dummy discovery
65
+ provisioning over RFCOMM from a Linux computer, then verifies the hub is
66
+ sitting on the network in the pre-account state the app expects. From that
67
+ point the iPhone app only has to do its Phase 2 work (find the hub on the
68
+ network, sign in, restore the profile), which in my experience has been
69
+ the more reliable half of the flow.
70
+
71
+ ## Disclaimer
72
+
73
+ This is an unofficial, third-party tool. It is **not affiliated with,
74
+ endorsed by, or supported by Logitech**. "Harmony", "Logitech", and the
75
+ Logitech logo are trademarks of their respective owners and are used here
76
+ only to identify the device this tool interacts with.
77
+
78
+ The Bluetooth setup protocol used by this tool was reverse-engineered from
79
+ the publicly distributed Harmony Android app and the hub's own observable
80
+ behavior. Use this tool only with Harmony Hubs that you own.
81
+
82
+ ## Requirements
83
+
84
+ - Linux with Bluetooth support.
85
+ - `bluetoothctl` from BlueZ available on `PATH`.
86
+ - `uv` for running the project from source.
87
+ - A Harmony Hub that has been factory reset.
88
+ - The Wi-Fi network name and password for the network the hub should join.
89
+
90
+ ## Factory Reset the Hub
91
+
92
+ Phase 1 setup assumes the hub starts from a clean factory-reset state.
93
+
94
+ Unplug your hub and then hold the **Pair/Reset** button on the back while
95
+ plugging it back in. The light on the front of the hub will flicker red for
96
+ approximately 30 seconds as the hub restores itself to factory defaults.
97
+
98
+ ![Harmony Hub Pair/Reset button location](docs/images/harmony-hub-pair-reset.png)
99
+
100
+ Once the flickering stops and the hub re-enters Bluetooth setup mode, continue
101
+ with the next section.
102
+
103
+ ## Discover the Hub
104
+
105
+ After factory reset, plug in the hub and wait for it to enter Bluetooth setup
106
+ mode. Then run:
107
+
108
+ ```bash
109
+ uv run harmony-hub-setup discover
110
+ ```
111
+
112
+ The command scans with `bluetoothctl` and prints nearby devices. A typical
113
+ result looks like:
114
+
115
+ ```text
116
+ Bluetooth devices:
117
+ AA:BB:CC:DD:EE:FF Harmony Hub [Harmony candidate]
118
+ ```
119
+
120
+ If a Harmony candidate is listed, use that address with `--address`. If setup is
121
+ run without `--address`, it will auto-discover and use the address only when
122
+ exactly one Harmony-looking device is found.
123
+
124
+ ## Phase 1 Setup
125
+
126
+ Run:
127
+
128
+ ```bash
129
+ uv run harmony-hub-setup setup \
130
+ --ssid "Your Wi-Fi Name" \
131
+ --password "Your Wi-Fi Password" \
132
+ --encryption WPA2-PSK
133
+ ```
134
+
135
+ Or pass the Bluetooth address explicitly:
136
+
137
+ ```bash
138
+ uv run harmony-hub-setup \
139
+ --address AA:BB:CC:DD:EE:FF \
140
+ setup \
141
+ --ssid "Your Wi-Fi Name" \
142
+ --password "Your Wi-Fi Password" \
143
+ --encryption WPA2-PSK
144
+ ```
145
+
146
+ The setup command prints numbered progress steps. Phase 1 is complete when it
147
+ prints:
148
+
149
+ ```text
150
+ PHASE 1 COMPLETE
151
+ The hub is on Wi-Fi, in mode=2, and reachable through the local setup endpoint.
152
+ Open the Harmony mobile app and continue account/profile restore from there.
153
+ ```
154
+
155
+ At that point, open the Harmony mobile app, select the hub found on the network,
156
+ log in to the Logitech account, and let the app restore the profile.
157
+
158
+ ## Example Output
159
+
160
+ A successful run looks like this (placeholders shown for the Bluetooth address,
161
+ SSID, and IP):
162
+
163
+ ```text
164
+ No Bluetooth address provided; scanning for Harmony Hub candidates...
165
+ Bluetooth devices:
166
+ AA:BB:CC:DD:EE:FF Harmony Hub [Harmony candidate]
167
+
168
+ Using discovered Harmony Hub: AA:BB:CC:DD:EE:FF Harmony Hub
169
+
170
+ Waiting for Harmony Hub Bluetooth...
171
+ (Factory reset the hub if you haven't already)
172
+
173
+ Connected on attempt 1!
174
+
175
+ [1/8] Verify Bluetooth command channel
176
+ Hub alive (uuid=...)
177
+
178
+ [2/8] Scan for target Wi-Fi network
179
+ Found target SSID (signal=212, security=WPA2-PSK, channel=2422)
180
+
181
+ [3/8] Get Bluetooth nonce
182
+ Nonce received (32 chars).
183
+
184
+ [4/8] Connect hub to Wi-Fi (Your Wi-Fi Name)
185
+ Wi-Fi command attempt 1 returned code=500; retrying.
186
+ Wi-Fi command accepted on attempt 2.
187
+ Connected! IP: 192.0.2.200
188
+
189
+ [5/8] Set discovery provisioning over Bluetooth
190
+ Provision command accepted.
191
+
192
+ [6/8] Confirm pre-account Phase 1 handoff state over Bluetooth
193
+ Bluetooth provision-info: mode=2, account=not set, secure=True
194
+
195
+ [7/8] Read Bluetooth setup gates
196
+ RF info response: code=200
197
+ Firmware: 4.15.600
198
+ Wi-Fi: connected
199
+ SSID: Your Wi-Fi Name
200
+ IP: 192.0.2.200
201
+
202
+ [8/8] Verify local hub setup endpoint
203
+ LAN ping OK: http://192.0.2.200:8088
204
+ LAN system-info OK.
205
+ Hub firmware: 4.15.600
206
+ LAN provision-info OK.
207
+ Provision mode: 2
208
+ Account ID: not set
209
+ Auth token: not set
210
+ LAN Phase 1 handoff: mode=2, account=not set, secure=True
211
+ LAN discovery-info OK.
212
+ LAN paired-device info OK.
213
+ LAN firmware check OK.
214
+
215
+ Final state
216
+ Discovery server: https://svcs.myharmony.com/Discovery/Discovery.svc
217
+ SUS channel: Production
218
+ Mode: 2
219
+
220
+ PHASE 1 COMPLETE
221
+ The hub is on Wi-Fi, in mode=2, and reachable through the local setup endpoint.
222
+ Open the Harmony mobile app and continue account/profile restore from there.
223
+ ```
224
+
225
+ The `PHASE 1 COMPLETE` block at the end is the cue to switch to the Harmony
226
+ mobile app for Phase 2.
227
+
228
+ ## Phase 2: Restore Your Account in the App
229
+
230
+ Open the Harmony mobile app, select your hub from the list, and sign in to
231
+ your Logitech account. The app will start restoring your hub's profile.
232
+
233
+ ### Press the Pair/Reset button when the app asks
234
+
235
+ Roughly a third of the way through the restore (around the **Preparing Your
236
+ Hub** step), the app will pause and ask you to press the **Pair/Reset**
237
+ button on the back of the hub again. This is expected every time -- it is
238
+ not a sign that anything has gone wrong.
239
+
240
+ ![Restoring Account progress screen at the Pair/Reset prompt](docs/images/harmony-app-restore-pair-prompt.png)
241
+
242
+ Press the button once, then let the app continue. The remainder of the
243
+ restore should complete without further prompts.
244
+
245
+ ### Wait before unplugging
246
+
247
+ After the app reports restore is complete, **leave the hub powered for at
248
+ least two minutes** before you unplug it to move it. This gives the hub
249
+ time to fully persist the new configuration to flash. Unplugging too soon
250
+ has been observed to roll the hub back to an unprovisioned state, forcing
251
+ a fresh factory reset.
252
+
253
+ ## What Success Means
254
+
255
+ Successful Phase 1 means:
256
+
257
+ - Bluetooth setup commands worked.
258
+ - The hub joined Wi-Fi and has a local IP address.
259
+ - Local setup probes work over `http://<hub-ip>:8088`.
260
+ - Provision info reports `mode=2`.
261
+ - Account ID, auth token, email, username, and active remote ID are not set.
262
+
263
+ It does **not** mean the hub has been fully account-provisioned. Full restore is
264
+ complete only after the Harmony mobile app finishes Phase 2.
265
+
266
+ ## Troubleshooting
267
+
268
+ If discovery finds no Harmony candidate:
269
+
270
+ - Confirm the hub was factory reset.
271
+ - Keep the hub powered on and near the computer.
272
+ - Run `bluetoothctl scan on` manually to confirm Linux can see Bluetooth
273
+ devices.
274
+ - Re-run setup with `--address` if you know the hub's Bluetooth address.
275
+
276
+ If setup fails during Wi-Fi connection:
277
+
278
+ - Confirm the SSID and password.
279
+ - Confirm the hub is close enough to the Wi-Fi access point.
280
+ - Re-run setup after another factory reset if the hub is in an unknown state.
281
+
282
+ If the mobile app cannot find the hub after Phase 1 completes:
283
+
284
+ - Confirm the phone is on the same network as the hub.
285
+ - Wait briefly for the hub to appear in the app.
286
+ - Run `harmony-hub-setup --address <address> status` while Bluetooth is still
287
+ available to inspect the hub state.
288
+
289
+ ## Releasing (maintainer)
290
+
291
+ Releases are cut from the project root with `release X.Y.Z` (or `release` for
292
+ an interactive version prompt). The tool bumps `pyproject.toml`, commits,
293
+ tags, pushes -- which triggers the PyPI publish workflow via GitHub Actions
294
+ Trusted Publishing. Release notes auto-generate from commit messages between
295
+ tags, so commits should read well as changelog entries.
harmony_hub_setup-0.2.0/README.md ADDED
@@ -0,0 +1,269 @@
1
+ # Harmony Hub Setup
2
+
3
+ [![PyPI version](https://img.shields.io/pypi/v/harmony-hub-setup.svg)](https://pypi.org/project/harmony-hub-setup/)
4
+ [![Python versions](https://img.shields.io/pypi/pyversions/harmony-hub-setup.svg)](https://pypi.org/project/harmony-hub-setup/)
5
+ [![PyPI status](https://img.shields.io/pypi/status/harmony-hub-setup.svg)](https://pypi.org/project/harmony-hub-setup/)
6
+ [![PyPI downloads](https://img.shields.io/pypi/dm/harmony-hub-setup.svg)](https://pypi.org/project/harmony-hub-setup/)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
8
+ [![Platform: Linux](https://img.shields.io/badge/Platform-Linux-blue.svg)](#requirements)
9
+
10
+ Configure a factory-reset Logitech Harmony Hub far enough for the official
11
+ Harmony mobile app to finish account/profile restore.
12
+
13
+ This tool performs **Phase 1** only:
14
+
15
+ 1. Connects to the hub over Bluetooth.
16
+ 2. Finds the target Wi-Fi network.
17
+ 3. Connects the hub to Wi-Fi.
18
+ 4. Sends the dummy discovery provisioning command (`mode=2`).
19
+ 5. Verifies the hub is still pre-account and reachable on the local network.
20
+
21
+ The official Harmony iPhone or Android app performs **Phase 2**:
22
+
23
+ 1. Finds the hub on the network.
24
+ 2. Logs in to the Logitech account.
25
+ 3. Restores the hub's devices, activities, and account profile.
26
+
27
+ ## Why this exists
28
+
29
+ Since early 2025, connecting to my Logitech Harmony Hub from the iPhone app
30
+ has become increasingly difficult and buggy. The usual recovery path --
31
+ factory reset the hub and let the iPhone app re-provision it from my Logitech
32
+ account -- has itself become fraught and unreliable on the iPhone in that
33
+ same window. The hub frequently fails to join Wi-Fi during the app's setup
34
+ flow even when the network is healthy and well in range, leaving the hub
35
+ unreachable.
36
+
37
+ This tool exists to take that fragile Wi-Fi join out of the iPhone app's
38
+ hands. It does the Bluetooth handshake, Wi-Fi join, and dummy discovery
39
+ provisioning over RFCOMM from a Linux computer, then verifies the hub is
40
+ sitting on the network in the pre-account state the app expects. From that
41
+ point the iPhone app only has to do its Phase 2 work (find the hub on the
42
+ network, sign in, restore the profile), which in my experience has been
43
+ the more reliable half of the flow.
44
+
45
+ ## Disclaimer
46
+
47
+ This is an unofficial, third-party tool. It is **not affiliated with,
48
+ endorsed by, or supported by Logitech**. "Harmony", "Logitech", and the
49
+ Logitech logo are trademarks of their respective owners and are used here
50
+ only to identify the device this tool interacts with.
51
+
52
+ The Bluetooth setup protocol used by this tool was reverse-engineered from
53
+ the publicly distributed Harmony Android app and the hub's own observable
54
+ behavior. Use this tool only with Harmony Hubs that you own.
55
+
56
+ ## Requirements
57
+
58
+ - Linux with Bluetooth support.
59
+ - `bluetoothctl` from BlueZ available on `PATH`.
60
+ - `uv` for running the project from source.
61
+ - A Harmony Hub that has been factory reset.
62
+ - The Wi-Fi network name and password for the network the hub should join.
63
+
64
+ ## Factory Reset the Hub
65
+
66
+ Phase 1 setup assumes the hub starts from a clean factory-reset state.
67
+
68
+ Unplug your hub and then hold the **Pair/Reset** button on the back while
69
+ plugging it back in. The light on the front of the hub will flicker red for
70
+ approximately 30 seconds as the hub restores itself to factory defaults.
71
+
72
+ ![Harmony Hub Pair/Reset button location](docs/images/harmony-hub-pair-reset.png)
73
+
74
+ Once the flickering stops and the hub re-enters Bluetooth setup mode, continue
75
+ with the next section.
76
+
77
+ ## Discover the Hub
78
+
79
+ After factory reset, plug in the hub and wait for it to enter Bluetooth setup
80
+ mode. Then run:
81
+
82
+ ```bash
83
+ uv run harmony-hub-setup discover
84
+ ```
85
+
86
+ The command scans with `bluetoothctl` and prints nearby devices. A typical
87
+ result looks like:
88
+
89
+ ```text
90
+ Bluetooth devices:
91
+ AA:BB:CC:DD:EE:FF Harmony Hub [Harmony candidate]
92
+ ```
93
+
94
+ If a Harmony candidate is listed, use that address with `--address`. If setup is
95
+ run without `--address`, it will auto-discover and use the address only when
96
+ exactly one Harmony-looking device is found.
97
+
98
+ ## Phase 1 Setup
99
+
100
+ Run:
101
+
102
+ ```bash
103
+ uv run harmony-hub-setup setup \
104
+ --ssid "Your Wi-Fi Name" \
105
+ --password "Your Wi-Fi Password" \
106
+ --encryption WPA2-PSK
107
+ ```
108
+
109
+ Or pass the Bluetooth address explicitly:
110
+
111
+ ```bash
112
+ uv run harmony-hub-setup \
113
+ --address AA:BB:CC:DD:EE:FF \
114
+ setup \
115
+ --ssid "Your Wi-Fi Name" \
116
+ --password "Your Wi-Fi Password" \
117
+ --encryption WPA2-PSK
118
+ ```
119
+
120
+ The setup command prints numbered progress steps. Phase 1 is complete when it
121
+ prints:
122
+
123
+ ```text
124
+ PHASE 1 COMPLETE
125
+ The hub is on Wi-Fi, in mode=2, and reachable through the local setup endpoint.
126
+ Open the Harmony mobile app and continue account/profile restore from there.
127
+ ```
128
+
129
+ At that point, open the Harmony mobile app, select the hub found on the network,
130
+ log in to the Logitech account, and let the app restore the profile.
131
+
132
+ ## Example Output
133
+
134
+ A successful run looks like this (placeholders shown for the Bluetooth address,
135
+ SSID, and IP):
136
+
137
+ ```text
138
+ No Bluetooth address provided; scanning for Harmony Hub candidates...
139
+ Bluetooth devices:
140
+ AA:BB:CC:DD:EE:FF Harmony Hub [Harmony candidate]
141
+
142
+ Using discovered Harmony Hub: AA:BB:CC:DD:EE:FF Harmony Hub
143
+
144
+ Waiting for Harmony Hub Bluetooth...
145
+ (Factory reset the hub if you haven't already)
146
+
147
+ Connected on attempt 1!
148
+
149
+ [1/8] Verify Bluetooth command channel
150
+ Hub alive (uuid=...)
151
+
152
+ [2/8] Scan for target Wi-Fi network
153
+ Found target SSID (signal=212, security=WPA2-PSK, channel=2422)
154
+
155
+ [3/8] Get Bluetooth nonce
156
+ Nonce received (32 chars).
157
+
158
+ [4/8] Connect hub to Wi-Fi (Your Wi-Fi Name)
159
+ Wi-Fi command attempt 1 returned code=500; retrying.
160
+ Wi-Fi command accepted on attempt 2.
161
+ Connected! IP: 192.0.2.200
162
+
163
+ [5/8] Set discovery provisioning over Bluetooth
164
+ Provision command accepted.
165
+
166
+ [6/8] Confirm pre-account Phase 1 handoff state over Bluetooth
167
+ Bluetooth provision-info: mode=2, account=not set, secure=True
168
+
169
+ [7/8] Read Bluetooth setup gates
170
+ RF info response: code=200
171
+ Firmware: 4.15.600
172
+ Wi-Fi: connected
173
+ SSID: Your Wi-Fi Name
174
+ IP: 192.0.2.200
175
+
176
+ [8/8] Verify local hub setup endpoint
177
+ LAN ping OK: http://192.0.2.200:8088
178
+ LAN system-info OK.
179
+ Hub firmware: 4.15.600
180
+ LAN provision-info OK.
181
+ Provision mode: 2
182
+ Account ID: not set
183
+ Auth token: not set
184
+ LAN Phase 1 handoff: mode=2, account=not set, secure=True
185
+ LAN discovery-info OK.
186
+ LAN paired-device info OK.
187
+ LAN firmware check OK.
188
+
189
+ Final state
190
+ Discovery server: https://svcs.myharmony.com/Discovery/Discovery.svc
191
+ SUS channel: Production
192
+ Mode: 2
193
+
194
+ PHASE 1 COMPLETE
195
+ The hub is on Wi-Fi, in mode=2, and reachable through the local setup endpoint.
196
+ Open the Harmony mobile app and continue account/profile restore from there.
197
+ ```
198
+
199
+ The `PHASE 1 COMPLETE` block at the end is the cue to switch to the Harmony
200
+ mobile app for Phase 2.
201
+
202
+ ## Phase 2: Restore Your Account in the App
203
+
204
+ Open the Harmony mobile app, select your hub from the list, and sign in to
205
+ your Logitech account. The app will start restoring your hub's profile.
206
+
207
+ ### Press the Pair/Reset button when the app asks
208
+
209
+ Roughly a third of the way through the restore (around the **Preparing Your
210
+ Hub** step), the app will pause and ask you to press the **Pair/Reset**
211
+ button on the back of the hub again. This is expected every time -- it is
212
+ not a sign that anything has gone wrong.
213
+
214
+ ![Restoring Account progress screen at the Pair/Reset prompt](docs/images/harmony-app-restore-pair-prompt.png)
215
+
216
+ Press the button once, then let the app continue. The remainder of the
217
+ restore should complete without further prompts.
218
+
219
+ ### Wait before unplugging
220
+
221
+ After the app reports restore is complete, **leave the hub powered for at
222
+ least two minutes** before you unplug it to move it. This gives the hub
223
+ time to fully persist the new configuration to flash. Unplugging too soon
224
+ has been observed to roll the hub back to an unprovisioned state, forcing
225
+ a fresh factory reset.
226
+
227
+ ## What Success Means
228
+
229
+ Successful Phase 1 means:
230
+
231
+ - Bluetooth setup commands worked.
232
+ - The hub joined Wi-Fi and has a local IP address.
233
+ - Local setup probes work over `http://<hub-ip>:8088`.
234
+ - Provision info reports `mode=2`.
235
+ - Account ID, auth token, email, username, and active remote ID are not set.
236
+
237
+ It does **not** mean the hub has been fully account-provisioned. Full restore is
238
+ complete only after the Harmony mobile app finishes Phase 2.
239
+
240
+ ## Troubleshooting
241
+
242
+ If discovery finds no Harmony candidate:
243
+
244
+ - Confirm the hub was factory reset.
245
+ - Keep the hub powered on and near the computer.
246
+ - Run `bluetoothctl scan on` manually to confirm Linux can see Bluetooth
247
+ devices.
248
+ - Re-run setup with `--address` if you know the hub's Bluetooth address.
249
+
250
+ If setup fails during Wi-Fi connection:
251
+
252
+ - Confirm the SSID and password.
253
+ - Confirm the hub is close enough to the Wi-Fi access point.
254
+ - Re-run setup after another factory reset if the hub is in an unknown state.
255
+
256
+ If the mobile app cannot find the hub after Phase 1 completes:
257
+
258
+ - Confirm the phone is on the same network as the hub.
259
+ - Wait briefly for the hub to appear in the app.
260
+ - Run `harmony-hub-setup --address <address> status` while Bluetooth is still
261
+ available to inspect the hub state.
262
+
263
+ ## Releasing (maintainer)
264
+
265
+ Releases are cut from the project root with `release X.Y.Z` (or `release` for
266
+ an interactive version prompt). The tool bumps `pyproject.toml`, commits,
267
+ tags, pushes -- which triggers the PyPI publish workflow via GitHub Actions
268
+ Trusted Publishing. Release notes auto-generate from commit messages between
269
+ tags, so commits should read well as changelog entries.
harmony_hub_setup-0.2.0/pyproject.toml ADDED
@@ -0,0 +1,37 @@
1
+ [project]
2
+ name = "harmony-hub-setup"
3
+ version = "0.2.0"
4
+ description = "Configure a Logitech Harmony Hub over Bluetooth (Wi-Fi setup, scanning, status)"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ authors = [
8
+ { name = "Corey Gallon", email = "366332+captivus@users.noreply.github.com" }
9
+ ]
10
+ keywords = ["harmony", "logitech", "bluetooth", "rfcomm", "home-automation", "iot", "wifi", "provisioning"]
11
+ classifiers = [
12
+ "Development Status :: 4 - Beta",
13
+ "Environment :: Console",
14
+ "Intended Audience :: End Users/Desktop",
15
+ "License :: OSI Approved :: MIT License",
16
+ "Operating System :: POSIX :: Linux",
17
+ "Programming Language :: Python :: 3",
18
+ "Programming Language :: Python :: 3.10",
19
+ "Programming Language :: Python :: 3.11",
20
+ "Programming Language :: Python :: 3.12",
21
+ "Programming Language :: Python :: 3.13",
22
+ "Topic :: Home Automation",
23
+ "Topic :: Utilities",
24
+ ]
25
+ requires-python = ">=3.10"
26
+
27
+ [project.scripts]
28
+ harmony-hub-setup = "harmony_hub_setup.cli:main"
29
+
30
+ [project.urls]
31
+ Homepage = "https://github.com/captivus/harmony-hub-setup"
32
+ Repository = "https://github.com/captivus/harmony-hub-setup"
33
+ Issues = "https://github.com/captivus/harmony-hub-setup/issues"
34
+
35
+ [build-system]
36
+ requires = ["uv_build>=0.9.17,<0.10.0"]
37
+ build-backend = "uv_build"
harmony_hub_setup-0.2.0/src/harmony_hub_setup/__init__.py ADDED
@@ -0,0 +1,5 @@
1
+ """Harmony Hub Bluetooth setup tool."""
2
+
3
+ from .client import HarmonyHubClient
4
+
5
+ __all__ = ["HarmonyHubClient"]