@o-lukas/homebridge-smartthings-tv 2.6.0-next.3 → 2.6.0

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 (4) hide show
  1. package/README.md +6 -290
  2. package/config.schema.json +6 -6
  3. package/docs/common-issues.md +93 -0
  4. package/package.json +1 -6
package/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
  [![semantic-release](https://img.shields.io/badge/semantic--release-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)
5
5
  ![NPM Version](https://badgen.net/npm/v/@o-lukas/homebridge-smartthings-tv?label=stable)
6
6
  ![NPM Node Version](https://badgen.net/npm/node/@o-lukas/homebridge-smartthings-tv)
7
- ![NPM Total Downloads](https://badgen.net/npm/dt/@o-lukas/homebridge-smartthings-tv)
7
+ ![NPM Weekly Downloads](https://badgen.net/npm/dw/@o-lukas/homebridge-smartthings-tv)
8
8
  ![GitHub issues](https://img.shields.io/github/issues/o-lukas/homebridge-smartthings-tv?label=Issues)
9
9
  [![Build and Lint](https://github.com/o-lukas/homebridge-smartthings-tv/actions/workflows/build.yml/badge.svg)](https://github.com/o-lukas/homebridge-smartthings-tv/actions/workflows/build.yml)
10
10
 
@@ -12,6 +12,8 @@ This is a plugin for [Homebridge](https://github.com/homebridge/homebridge). It
12
12
 
13
13
  Both device types will be registered as TVs because this is the only device type that is able to control input sources at the moment.
14
14
 
15
+ If you have any problems please make sure to check the [common issues pages](./docs/common-issues.md) before creating a new issue.
16
+
15
17
  ## Configuration
16
18
 
17
19
  The easiest way to configure the plugin is to use [Homebridge Config UI X](https://github.com/oznu/homebridge-config-ui-x) which should contain a description for every needed property. The only property needed to make the plugin work is the SmartThings API token. The other properties enable some additional functions but are not mandatory for the plugin to work.
@@ -33,294 +35,8 @@ The following snippet shows the most simple configuration you can use for the pl
33
35
  }
34
36
  ```
35
37
 
36
- The following snippets shows all available properties you can use for the plugin:
37
-
38
- ```json
39
- {
40
- "bridge": {
41
- },
42
- "accessories": [],
43
- "platforms": [
44
- {
45
- "name": "SmartThings TV",
46
- "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
47
- "capabilityLogging": true,
48
- "cyclicCallsLogging": true,
49
- "registerApplications": true,
50
- "registerPictureModes": true,
51
- "registerSoundModes": true,
52
- "registerVolumeSlider": true,
53
- "pollInterval": 5000,
54
- "deviceBlocklist": [
55
- "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
56
- "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
57
- ],
58
- "deviceMappings": [
59
- {
60
- "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
61
- "nameOverride": "xxxx",
62
- "wol": true,
63
- "macAddress": "xx:xx:xx:xx:xx:xx",
64
- "ping": true,
65
- "ipAddress": "xx:xx:xx:xx:xx:xx",
66
- "infoKey": "MENU",
67
- "inputSources": [
68
- {
69
- "name": "xxxx",
70
- "id": "xxxx"
71
- }
72
- ],
73
- "applications": [
74
- {
75
- "name": "xxxx",
76
- "ids": [
77
- "xxxx",
78
- "xxxx"
79
- ]
80
- }
81
- ],
82
- "validateApplications": false
83
- },
84
- {
85
- "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
86
- "wol": true,
87
- "macAddress": "xx:xx:xx:xx:xx:xx",
88
- "ping": false
89
- },
90
- {
91
- "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
92
- "wol": false,
93
- "ping": true,
94
- "ipAddress": "xx:xx:xx:xx:xx:xx"
95
- }
96
- ],
97
- "tvDeviceTypes": [
98
- "oic.d.tv",
99
- "x.com.st.d.monitor"
100
- ],
101
- "soundbarDeviceTypes": [
102
- "oic.d.networkaudio"
103
- ],
104
- "platform": "smartthings-tv"
105
- }
106
- ]
107
- }
108
- ```
109
-
110
- ### token
111
-
112
- The SmartThings API token is needed to authenticate the requests sent to the SmartThings API. To generate a token open [SmartThings website]( https://account.smartthings.com/tokens) and generate a new one (make sure at least devices is selected).
113
-
114
- ### capabilityLogging
115
-
116
- The SmartThings API returns the list of supported actions of a device as capabilities. For implementing new features it is neccessary to know the scheme the capability uses. Enable this property to log all capabilities of supported SmartThings devices.
117
-
118
- ### cyclicCallsLogging
119
-
120
- Enable debug logging for cyclic calls (e.g. polling).
121
-
122
- ### registerApplications
123
-
124
- To use installed application as input sources, a [predefined list of applications](./src/tvApps.ts) will be used.
125
-
126
- > [!NOTE]
127
- > Not implemented for SoundBars.
128
-
129
- ### registerPictureModes
130
-
131
- Registers all available picture modes as separate switches that can be toggled to enable/disable a picture mode. Uses the names as exposed from the SmartThings API.
132
-
133
- > [!NOTE]
134
- > Not implemented for SoundBars.
135
-
136
- ### registerSoundModes
137
-
138
- Registers all available sound modes as separate switches that can be toggled to enable/disable a sound mode. Uses the names as exposed from the SmartThings API.
139
-
140
- > [!NOTE]
141
- > Not implemented for SoundBars.
142
-
143
- ### registerVolumeSlider
144
-
145
- Registers a separate volume slider accessorry that will be exposed as a light bulb accessory (because there is currently no option to change a speaker volume directly using Home).
146
-
147
- ### pollInterval
148
-
149
- Some characteristics are not updated automatically (e.g. power state). To enable polling these characteristics automatically set this value to the desired polling interval in milliseconds. Leave empty to disable this functionality.
150
-
151
- ### deviceBlocklist
152
-
153
- Devices not to be registered.
154
-
155
- ### deviceMappings
156
-
157
- Use the device mappings when e.g. turning on the accessory does not work as expected. When a device mapping is available the wake-on-lan functionality is used to turn on the device instead of the SmartThings API. To make use of the functionality you must enter the mapping using the SmartThings device ID and the mac address of the device. If status does not show up properly you can use the ping functionality to determine the device status. To make use of it you must enter the SmartThings device ID and the ip address of the device.
158
-
159
- The following table gives an overview which properties do work for the device types:
160
-
161
- | Configuration property | TV | SoundBar |
162
- | ---------------------- | ------------------ | ------------------ |
163
- | deviceId | :white_check_mark: | :white_check_mark: |
164
- | nameOverride | :white_check_mark: | :white_check_mark: |
165
- | wol | :white_check_mark: | :white_check_mark: |
166
- | macAddress | :white_check_mark: | :white_check_mark: |
167
- | ping | :white_check_mark: | :white_check_mark: |
168
- | ipAddress | :white_check_mark: | :white_check_mark: |
169
- | infoKey | :white_check_mark: | :x: |
170
- | inputSources | :white_check_mark: | :white_check_mark: |
171
- | applications | :white_check_mark: | :x: |
172
- | category | :white_check_mark: | :white_check_mark: |
173
-
174
- #### deviceId
175
-
176
- The SmartThings device id. Check the log or go to <https://account.smartthings.com/> and get the device id.
177
-
178
- #### nameOverride
179
-
180
- Use this to override the default display name of the device. Must be configured here because name configured in HomeKit will get lost after restart.
181
-
182
- #### wol
183
-
184
- Enables usage of wake-on-lan functionality to turn the device on. Use only if using the SmartThings API does not work for your device.
185
-
186
- #### macAddress
187
-
188
- The mac address of the device to turn device on using wake-on-lan functionality.
189
-
190
- #### ping
191
-
192
- Enables usage of ping functionality to determine if device is turned on. Use only if using the SmartThings API does not work for your device.
193
-
194
- #### ipAddress
195
-
196
- The IP address of the device (assign a static IP address to make sure it does not change) to determine the status using ping.
197
-
198
- #### infoKey
199
-
200
- The key to be emulated when pressing info button in HomeKit remote. The list of valid values must be read from the log as it differs per device. To do so enable capabilityLogging and look for log entry containing the possible values.
201
-
202
- #### inputSources
203
-
204
- Overrides the device's default input sources map to add custom input sources. Check the log for information about the default input sources.
205
-
206
- ##### name
207
-
208
- The input source's name.
209
-
210
- ##### id
211
-
212
- The input source's id.
213
-
214
- #### applications
215
-
216
- Overrides the default application mapping list to add custom applications. See [registerApplications](#registerapplications) for more details about application registration.
217
-
218
- ##### name
219
-
220
- The application's name.
221
-
222
- ##### ids
223
-
224
- The application's possible ids. Since some applications have different ids for different versions of TVs you can provide a list here so the plugin will try every id and use the one that's working.
225
-
226
- #### validateApplications
227
-
228
- Validates the list of applications by trying to open them when starting the plugin. This list will be checked for availability at the TV(s) and eventually be registered as input sources. Make sure to have the TV(s) turned on when starting your instance as this functionality requires your TV(s) be turned on to determine whether an application is installed or not. On startup the applications will be opened to determine if they are available. Do not use your TV until the input source is being changed back to the first one (usually Live TV). Afterwards the list of working applications will be written to this device list of applications. Note that this flag will be set to off after validation the application list. So check will only run on first start or manual reset.
229
-
230
- #### category
231
-
232
- The icon to be used as a hint to iOS clients about what type of Accessory this represents. Can be used to override default values.
233
-
234
- ## tvDeviceTypes
235
-
236
- List of SmartThings device types that should be registered as TVs (leave empty to use default values).
237
-
238
- ## soundbarDeviceTypes
239
-
240
- List of SmartThings device types that should be registered as Soundbar (leave empty to use default values).
241
-
242
- ## Common issues
243
-
244
- ### TV does not show in HomeKit
245
-
246
- After starting you have to add the TV manually to HomeKit because they are published as external accessory to get over the limit of only one TV per bridge.
247
-
248
- If your TV is lost after an update/restart/etc. you might need to reset the connection. To do so reset the externally published accessories in Homebridge using: Unpair Bridges / Cameras / TVs / External Accessories in the Homebridge settings.
249
-
250
- ### TV does not turn on
251
-
252
- The command to turn the TV on using the SmartThings API does not work for some TVs. To solve this problem you can use the built-in wake-on-lan functionality. To activate this functionality add a device mapping containing the device id and the mac address of your TV.
253
-
254
- ```json
255
- {
256
- "bridge": {
257
- },
258
- "accessories": [],
259
- "platforms": [
260
- {
261
- "name": "SmartThings TV",
262
- "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
263
- "deviceMappings": [
264
- {
265
- "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
266
- "macAddress": "xx:xx:xx:xx:xx:xx"
267
- }
268
- ],
269
- "platform": "smartthings-tv"
270
- }
271
- ]
272
- }
273
- ```
274
-
275
- ### TV state does not match actual state
276
-
277
- Some TVs report a false active state using the SmartThings API. To get the actual state of the television you can use the build-in ping functionality. To activate this functionality add a device mapping containing the device id and the IP address of your TV.
278
-
279
- ```json
280
- {
281
- "bridge": {
282
- },
283
- "accessories": [],
284
- "platforms": [
285
- {
286
- "name": "SmartThings TV",
287
- "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
288
- "deviceMappings": [
289
- {
290
- "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
291
- "ipAddress": "xx:xx:xx:xx:xx:xx"
292
- }
293
- ],
294
- "platform": "smartthings-tv"
295
- }
296
- ]
297
- }
298
- ```
299
-
300
- ### Picture/sound mode switches do not match TV picture mode settings
301
-
302
- Some TVs always report the same picture & sound mode. This will cause the exposed switches to not match the actual picture/sound mode state. I have not found a proper solution for this problem yet. But toggling the buttons will still work.
303
-
304
- ### Error `invalid device state`
305
-
306
- Sometimes the SmartThings API seems to loose the contact to the device and does not update it's state so every request will end up with an error message like `invalid device state`. To fix this try to remove the device from your SmartThings account and add it again. This seems to fix the problem.
307
-
308
- ### DisplayPort input sources do not show up
309
-
310
- For some TVs display port sources do not show up. When having the same problem you might try to use [inputSources](#inputsources). `Id` might be something like `Display Port` but you will have to experiment a bit trying different ids until you find the the right one.
311
-
312
- ### Name of TV gets reset in HomeKit after HomeBridge restart
313
-
314
- The configured name can not be cached because TV is published as external accessory. To permanently change the name use [nameOverride](#nameoverride).
315
-
316
- ### Device does not get registered
317
-
318
- TVs do have different device types returned from SmartThings API. If your TV does not get registered, activate debug logging and look for a log entry like `Ignoring SmartThings device ... because device type ... is not in list of implemented/configured types [...]`. Use the device type stated here and add it to the matching configuration property [tvDeviceTypes](#tvdevicetypes) or [soundbarDeviceType](#soundbardevicetypes).
319
-
320
- Currently only the default values have been tested. So please create a ticket if you're running into any problems with your device type. If everything is working well please create a ticket as well so the device type can be added to the default configuration.
321
-
322
- ***
38
+ To get information about all supported properties please check the [config schema file](./config.schema.json).
323
39
 
324
- Since this is my first plugin it may contain some problems. Feel free to create an issue or pull request and I will try to help and fix the problems.
40
+ ## Disclaimer
325
41
 
326
- But since this plugin is developed in my spare time don't expect a quick fix.
42
+ This project is not affiliated with, endorsed by, or sponsored by any of the companies or products mentioned herein. All product names, trademarks, and registered trademarks are the property of their respective owners. The use of these names, logos, or brands is for identification purposes only and does not imply any association or endorsement.
package/config.schema.json CHANGED
@@ -79,19 +79,19 @@
79
79
  "title": "Register applications",
80
80
  "type": "boolean",
81
81
  "required": false,
82
- "description": "To use installed application as input sources, a predefined list of applications will be used."
82
+ "description": "To use installed application as input sources, a predefined list of applications will be used. Please note that this has no effect on SoundBars."
83
83
  },
84
84
  "registerPictureModes": {
85
85
  "title": "Register picture modes",
86
86
  "type": "boolean",
87
87
  "required": false,
88
- "description": "Registers all available picture modes as separate switches that can be toggled to enable/disable a picture mode. Uses the names as exposed from the SmartThings API."
88
+ "description": "Registers all available picture modes as separate switches that can be toggled to enable/disable a picture mode. Uses the names as exposed from the SmartThings API. Please not that this has no effect on SoundBars."
89
89
  },
90
90
  "registerSoundModes": {
91
91
  "title": "Register sound modes",
92
92
  "type": "boolean",
93
93
  "required": false,
94
- "description": "Registers all available sound modes as separate switches that can be toggled to enable/disable a sound mode. Uses the names as exposed from the SmartThings API."
94
+ "description": "Registers all available sound modes as separate switches that can be toggled to enable/disable a sound mode. Uses the names as exposed from the SmartThings API. Please not that this has no effect on SoundBars"
95
95
  },
96
96
  "registerVolumeSlider": {
97
97
  "title": "Register volume slider",
@@ -162,7 +162,7 @@
162
162
  "infoKey": {
163
163
  "title": "Info key",
164
164
  "type": "string",
165
- "description": "The key to be emulated when pressing info button in HomeKit remote. The list of valid values must be read from the log as it differs per device. To do so enable capabilityLogging and look for log entry containing the possible values."
165
+ "description": "The key to be emulated when pressing info button in HomeKit remote. The list of valid values must be read from the log as it differs per device. To do so enable capabilityLogging and look for log entry containing the possible values. Please note that this has no effect on SoundBars."
166
166
  },
167
167
  "inputSources": {
168
168
  "title": "Custom input sources list",
@@ -205,12 +205,12 @@
205
205
  }
206
206
  },
207
207
  "required": false,
208
- "description": "Overrides the default application mapping list to add custom applications."
208
+ "description": "Overrides the default application mapping list to add custom applications. Please note that this has no effect on SoundBars."
209
209
  },
210
210
  "validateApplications": {
211
211
  "title": "Validate application list",
212
212
  "type": "boolean",
213
- "description": "Validates the list of applications by trying to open them when starting the plugin. This list will be checked for availability at the TV(s) and eventually be registered as input sources. Make sure to have the TV(s) turned on when starting your instance as this functionality requires your TV(s) be turned on to determine whether an application is installed or not. On startup the applications will be opened to determine if they are available. Do not use your TV until the input source is being changed back to the first one (usually Live TV). Afterwards the list of working applications will be written to this device list of applications. Note that this flag will be set to off after validation the application list. So check will only run on first start or manual reset.",
213
+ "description": "Validates the list of applications by trying to open them when starting the plugin. This list will be checked for availability at the TV(s) and eventually be registered as input sources. Make sure to have the TV(s) turned on when starting your instance as this functionality requires your TV(s) be turned on to determine whether an application is installed or not. On startup the applications will be opened to determine if they are available. Do not use your TV until the input source is being changed back to the first one (usually Live TV). Afterwards the list of working applications will be written to this device list of applications. Note that this flag will be set to off after validation the application list. So check will only run on first start or manual reset. Please note that this has no effect on SoundBars.",
214
214
  "default": true
215
215
  },
216
216
  "category": {
package/docs/common-issues.md ADDED
@@ -0,0 +1,93 @@
1
+
2
+
3
+ # Common issues
4
+
5
+ ## TV does not show in HomeKit
6
+
7
+ After starting you have to add the TV manually to HomeKit because they are published as external accessory to get over the limit of only one TV per bridge.
8
+
9
+ If your TV is lost after an update/restart/etc. you might need to reset the connection. To do so reset the externally published accessories in Homebridge using: Unpair Bridges / Cameras / TVs / External Accessories in the Homebridge settings.
10
+
11
+ ## TV does not turn on
12
+
13
+ The command to turn the TV on using the SmartThings API does not work for some TVs. To solve this problem you can use the built-in wake-on-lan functionality. To activate this functionality add a device mapping containing the device id and the mac address of your TV.
14
+
15
+ ```json
16
+ {
17
+ "bridge": {
18
+ },
19
+ "accessories": [],
20
+ "platforms": [
21
+ {
22
+ "name": "SmartThings TV",
23
+ "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
24
+ "deviceMappings": [
25
+ {
26
+ "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
27
+ "macAddress": "xx:xx:xx:xx:xx:xx"
28
+ }
29
+ ],
30
+ "platform": "smartthings-tv"
31
+ }
32
+ ]
33
+ }
34
+ ```
35
+
36
+ ## TV state does not match actual state
37
+
38
+ Some TVs report a false active state using the SmartThings API. To get the actual state of the television you can use the build-in ping functionality. To activate this functionality add a device mapping containing the device id and the IP address of your TV.
39
+
40
+ ```json
41
+ {
42
+ "bridge": {
43
+ },
44
+ "accessories": [],
45
+ "platforms": [
46
+ {
47
+ "name": "SmartThings TV",
48
+ "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
49
+ "deviceMappings": [
50
+ {
51
+ "deviceId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
52
+ "ipAddress": "xx:xx:xx:xx:xx:xx"
53
+ }
54
+ ],
55
+ "platform": "smartthings-tv"
56
+ }
57
+ ]
58
+ }
59
+ ```
60
+
61
+ ## Picture/sound mode switches do not match TV picture mode settings
62
+
63
+ Some TVs always report the same picture & sound mode. This will cause the exposed switches to not match the actual picture/sound mode state. I have not found a proper solution for this problem yet. But toggling the buttons will still work.
64
+
65
+ ## Error `invalid device state`
66
+
67
+ Sometimes the SmartThings API seems to loose the contact to the device and does not update it's state so every request will end up with an error message like `invalid device state`. To fix this try to remove the device from your SmartThings account and add it again. This seems to fix the problem.
68
+
69
+ ## DisplayPort input sources do not show up
70
+
71
+ For some TVs display port sources do not show up. When having the same problem you might try to use `inputSource`. `Id` might be something like `Display Port` but you will have to experiment a bit trying different ids until you find the the right one.
72
+
73
+ ## Name of TV gets reset in HomeKit after HomeBridge restart
74
+
75
+ The configured name can not be cached because TV is published as external accessory. To permanently change the name use `nameOverride`.
76
+
77
+ ## Device does not get registered
78
+
79
+ TVs do have different device types returned from SmartThings API. If your TV does not get registered, activate debug logging and look for a log entry like `Ignoring SmartThings device ... because device type ... is not in list of implemented/configured types [...]`. Use the device type stated here and add it to the matching configuration property `tvDeviceTypes` or `soundbarDeviceType`.
80
+
81
+ Currently only the default values have been tested. So please create a ticket if you're running into any problems with your device type. If everything is working well please create a ticket as well so the device type can be added to the default configuration.
82
+
83
+ ## Personal access tokens expire after 24h
84
+
85
+ Since the end of 2024 all new SmartThings personal access tokens do expire after 24h. This is a change Samsung announced pretty unexpected in december 2024 in the [SmartThings forum](https://community.smartthings.com/t/changes-to-personal-access-tokens-pat/292019). If your token has been created before 30.12.2024 your token can still be used but all tokens created after that date will expire and will not be usable after 24h.
86
+
87
+ To fix this please change the `tokenType` to `OAuth` and use the setup wizard to enable OAuth integration.
88
+
89
+ ## Request failed with status code 429
90
+
91
+ Since the end of 2024 all new SmartThings persoanl access tokens have a rate limit. This is a change Samsung announced pretty unexpected in december 2024 in the [SmartThings forum](https://community.smartthings.com/t/changes-to-personal-access-tokens-pat/292019). If your token has been created before 30.12.2024 your token can still be used but all tokens created after that date will probably have problems with this plugin because the rate limit is pretty low.
92
+
93
+ To fix this please change the `tokenType` to `OAuth` and use the setup wizard to enable OAuth integration because it looks like there is no rate limit for this token type.
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "displayName": "Homebridge SmartThings TV",
3
3
  "name": "@o-lukas/homebridge-smartthings-tv",
4
4
  "type": "module",
5
- "version": "2.6.0-next.3",
5
+ "version": "2.6.0",
6
6
  "description": "This is a plugin for Homebridge. It offers some basic functions to control Samsung TVs using the SmartThings API.",
7
7
  "author": "o-lukas",
8
8
  "license": "MIT",
@@ -59,11 +59,6 @@
59
59
  "typescript": "^5.8.2",
60
60
  "typescript-eslint": "^8.26.0"
61
61
  },
62
- "overrides": {
63
- "@smartthings/core-sdk": {
64
- "axios": "~>1.7.3"
65
- }
66
- },
67
62
  "release": {
68
63
  "branches": [
69
64
  "main",