Skip to content

Commit dced223

Browse files
monty68monty68
committed
Update documentation
1 parent 8e22f2a commit dced223

5 files changed

+278
-8
lines changed

‎README.md

+15-8
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,23 @@
1-
[![GitHub Release][releases-shield]][releases]
2-
[![GitHub Activity][commits-shield]][commits]
3-
[![License][license-shield]][license]
41
[![BuyMeCoffee][buymecoffeebadge]][buymecoffee]
52

3+
# ![HA][ha-logo] UniLED - The Universal Light Controller
64

7-
# Important Notice
5+
6+
UniLED Currently supports the following range of cheap BLE addressable LED controllers:
7+
8+
- SP107E
9+
- SP601E
10+
- [SP611E][SP61xE]
11+
- [SP617E][SP61xE]
12+
13+
## Important Notice
814

915
The Home Assistant component and platforms in this repository are an "Alpha" release meaning this component is in the early stages of development,
1016
will be subject to regular change, may cause issues with Home Assistant, contain bugs or unwanted "features". Use at your own risk!
1117

12-
HAVE FUN! 😎
18+
This is also my very first Python and Home Assistant component development.
1319

14-
# UniLED - The Universal Light Controller
15-
16-
Currently supports the SP107E, SP601E, SP611E and SP617E range of cheap BLE addressable LED controllers.
20+
HAVE FUN! 😎
1721

1822
---
1923

@@ -34,6 +38,9 @@ If you want to contribute to this please read the [Contribution guidelines](CONT
3438
***
3539

3640
[uniled]: https://github.com/monty68/uniled
41+
[SP61xE]: docs/sp61Xe.md
42+
[ha-logo]: docs/ha-logo-32x32.png
43+
3744
[buymecoffee]: https://www.buymeacoffee.com/monty68
3845
[buymecoffeebadge]: https://img.shields.io/badge/buy%20me%20a%20coffee-donate-yellow.svg?style=for-the-badge
3946
[commits-shield]: https://img.shields.io/github/commit-activity/y/custom-components/uniled.svg?style=for-the-badge

‎docs/ha-logo-32x32.png

907 Bytes
Loading

‎docs/sp61Xe.md

+261
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,261 @@
1+
# SP61xE LED Controllers
2+
3+
The **SP61xE** are a range of small and cheap BLE controllers for addressable LEDs (pixels)
4+
5+
*Note, this entire guide is for Bluetooth LE libraries, and uses hexidecimal notation unless otherwise stated.*
6+
7+
## BLE configuration
8+
9+
The service can be found with UUID `ffe0`. Under this is (at least) the , `0000ffe1-0000-1000-8000-00805f9b34fb`
10+
characteristic used to send commands and receive any responses.
11+
12+
# Command Message Format
13+
14+
All command messages begin with three bytes:
15+
16+
1. `HB` - Header Byte, always `0xA0`, indicating start of a command message.
17+
2. `C#` - One of the valid command numbers.
18+
3. `D#` - Number of Data Bytes that follows.
19+
20+
---
21+
## Informational Commands
22+
<details><summary>Request Status</summary>
23+
<p>
24+
25+
| Command | `0x70` |
26+
| ----------- | ----------- |
27+
| Action | Returns State Packet(s) |
28+
| Length | 3 |
29+
| Format | `HB C# D#` |
30+
| Example | `A0 70 00` |
31+
**Fields**
32+
1. `HB` - Header Byte, always `A0`
33+
2. `C#` - Command Number, always `70`
34+
3. `D#` - Data Bytes to follow, always `00`
35+
</p>
36+
</details>
37+
38+
<details><summary>State Packets</summary>
39+
<p>
40+
41+
| State Packet |#1 |
42+
| ----------- | ----------- |
43+
| Length | 20 |
44+
| Format | `H1 H2 P# ?? ?? PS SN EN ?? ?? ?? EL RR GG BB IN IG ?? ?? ??` |
45+
| Example | `53 43 01 17 0f 00 00 cd 02 ff 0a 96 ff 00 00 00 10 09 04 0b` |
46+
**Fields**
47+
1. `H1` - Header Byte 1, always `53` (Ascii `S`)
48+
2. `H2` - Header Byte 2, always `43` (Ascii `P`)
49+
3. `P#` - Packet Number, always `01`
50+
4. `??`
51+
5. `??`
52+
6. `PS` - **Power State** (0x00 = Off, 0x01 = On)
53+
7. `SN` - **Scene Number** (Note Used, always 0x00)
54+
8. `EN` - **Effect Number** (See Effects List below)
55+
9. `??`
56+
10. `LV` - **Brightness Level** (0x00 - 0xFF)
57+
11. `ES` - **Effect Speed** (0x00 - 0x0A)
58+
12. `EL` - **Effect Length** (0x00 - 0x96)
59+
13. `RR` - **Red Level** (0x00 - 0xFF)
60+
14. `GG` - **Green Level** (0x00 - 0xFF)
61+
15. `BB` - **Blue Level** (0x00 - 0xFF)
62+
16. `IN` - **Input** for sound actvated effects (0x00 = Int. Mic, 0x01 = Player, 0x02 = Ext. Mic)
63+
17. `IG` - **Input Gain/Sensitivity** (0x00 - 0x0F)
64+
18. `??`
65+
19. `??`
66+
20. `??`
67+
68+
| State Packet | #2 |
69+
| ----------- | ----------- |
70+
| Length | 14 |
71+
| Format | `H1 H2 P# ?? ?? ?? ?? ?? RR GG BB ?? ?? ??` |
72+
| Example | `53 43 02 18 09 0a 1e 00 00 ff 00 10 00 00` |
73+
**Fields**
74+
1. `H1` - Header Byte 1, always `53` (Ascii `S`)
75+
2. `H2` - Header Byte 2, always `43` (Ascii `P`)
76+
3. `P#` - Packet Number, always `02`
77+
4. `??`
78+
5. `??`
79+
6. `??`
80+
7. `??`
81+
8. `??`
82+
9. `RR` - **Red Level** (0x00 - 0xFF) for Channel 2?
83+
10. `GG` - **Green Level** (0x00 - 0xFF) for Channel 2?
84+
11. `BB` - **Blue Level** (0x00 - 0xFF) for Channel 2?
85+
12. `??`
86+
13. `??`
87+
14. `??`
88+
</p>
89+
</details>
90+
91+
## Configuration Commands
92+
<details><summary>Set Device Name</summary>
93+
<p>
94+
95+
| Command | `0x61` |
96+
| ----------- | ----------- |
97+
| Action | Change device name|
98+
| Length | Max 13 (3 for command followed by up to 10 characters) |
99+
| Format | `HB C# D# N0 N1 N2 N3 N4 N5 N6 N7 N8 N9` |
100+
| Example | `a0 61 06 6f 66 66 69 63 65` - Sets name to "office" |
101+
102+
**Fields**
103+
1. `HB` - Header Byte, always `A0`
104+
2. `C#` - Command Number, always `61`
105+
3. `D#` - Data Bytes to follow, (0x00 - 0x0A)
106+
4. `N0-N9` - **Characters**
107+
</p>
108+
</details>
109+
110+
111+
## Control Commands
112+
<details><summary>Set Power State</summary>
113+
<p>
114+
115+
| Command | `0x62` |
116+
| ----------- | ----------- |
117+
| Action | Turns power on or off|
118+
| Length | 4 |
119+
| Format | `HB C# D# VV` |
120+
| Example | `A0 62 01 00` |
121+
122+
**Fields**
123+
1. `HB` - Header Byte, always `A0`
124+
2. `C#` - Command Number, always `62`
125+
3. `D#` - Data Bytes to follow, always `01`
126+
4. `VV` - **Power State** (0x00 = Off, 0x01 = On)
127+
</p>
128+
</details>
129+
130+
<details><summary>Set Effect</summary>
131+
<p>
132+
133+
| Command | `0x63` |
134+
| ----------- | ----------- |
135+
| Action | Changes the effect/pattern|
136+
| Length | 4 |
137+
| Format | `HB C# D# VV` |
138+
| Example | `A0 63 01 BE` |
139+
**Fields**
140+
1. `HB` - Header Byte, always `A0`
141+
2. `C#` - Command Number, always `63`
142+
3. `D#` - Data Bytes to follow, always `01`
143+
4. `VV` - **Effect Number** (See Effects List below)
144+
</p>
145+
</details>
146+
147+
<details><summary>Set Brightness Level</summary>
148+
<p>
149+
150+
| Command | `0x66` |
151+
| ----------- | ----------- |
152+
| Action | Changes the overall level of brightness|
153+
| Length | 4 |
154+
| Format | `HB C# D# VV` |
155+
| Example | `A0 66 01 FF` |
156+
**Fields**
157+
1. `HB` - Header Byte, always `A0`
158+
2. `C#` - Command Number, always `66`
159+
3. `D#` - Data Bytes to follow, always `01`
160+
4. `VV` - **Brightness Level** (0x00 - 0xFF)
161+
</p>
162+
</details>
163+
164+
<details><summary>Set Effect Speed</summary>
165+
<p>
166+
167+
| Command | `0x67` |
168+
| ----------- | ----------- |
169+
| Action | Changes the effect speed|
170+
| Length | 4 |
171+
| Format | `HB C# D# VV` |
172+
| Example | `A0 67 01 0A` |
173+
**Fields**
174+
1. `HB` - Header Byte, always `A0`
175+
2. `C#` - Command Number, always `67`
176+
3. `D#` - Data Bytes to follow, always `01`
177+
4. `VV` - **Effect Speed** (0x00 - 0x0A)
178+
</p>
179+
</details>
180+
181+
<details><summary>Set Effect Length</summary>
182+
<p>
183+
184+
| Command | `0x68` |
185+
| ----------- | ----------- |
186+
| Action | Changes the effect length|
187+
| Length | 4 |
188+
| Format | `HB C# D# VV` |
189+
| Example | `A0 68 01 FF` |
190+
**Fields**
191+
1. `HB` - Header Byte, always `A0`
192+
2. `C#` - Command Number, always `68`
193+
3. `D#` - Data Bytes to follow, always `01`
194+
4. `VV` - **Effect Length** (0x00 - 0x96)
195+
</p>
196+
</details>
197+
198+
<details><summary>Set Color Levels</summary>
199+
<p>
200+
201+
| Command | `0x69` |
202+
| ----------- | ----------- |
203+
| Action | Changes the color levels|
204+
| Length | 7 |
205+
| Format | `HB C# D# RR GG BB WW` |
206+
| Example | `A0 69 04 00 FF 00 FF` |
207+
**Fields**
208+
1. `HB` - Header Byte, always `A0`
209+
2. `C#` - Command Number, always `69`
210+
3. `D#` - Data Bytes to follow, always `04`
211+
4. `RR` - **Red Level** (0x00 - 0xFF)
212+
5. `GG` - **Green Level** (0x00 - 0xFF)
213+
6. `BB` - **Blue Level** (0x00 - 0xFF)
214+
7. `WW` - **White Level** (0x00 - 0xFF) - *Note: Ignored on SP611E as it does not support RGBW LEDs*
215+
</p>
216+
</details>
217+
218+
<details><summary>Set Input Gain/Sensitivity</summary>
219+
<p>
220+
221+
| Command | `0x6B` |
222+
| ----------- | ----------- |
223+
| Action | Changes the input sensitivity|
224+
| Length | 4 |
225+
| Format | `HB C# D# VV` |
226+
| Example | `A0 6B 01 0F` |
227+
**Fields**
228+
1. `HB` - Header Byte, always `A0`
229+
2. `C#` - Command Number, always `6B`
230+
3. `D#` - Data Bytes to follow, always `01`
231+
4. `VV` - **Gain/Sensitivity** (0x01 - 0x0F)
232+
</p>
233+
</details>
234+
235+
<details><summary>Set Input</summary>
236+
<p>
237+
238+
| Command | `0x6C` |
239+
| ----------- | ----------- |
240+
| Action | Changes the input for sound based effects|
241+
| Length | 4 |
242+
| Format | `HB C# D# VV` |
243+
| Example | `A0 6C 01 01` |
244+
**Fields**
245+
1. `HB` - Header Byte, always `A0`
246+
2. `C#` - Command Number, always `6C`
247+
3. `D#` - Data Bytes to follow, always `01`
248+
4. `VV` - **Input** (0x00 = Int. Mic, 0x01 = Player, 0x02 = Ext. Mic)
249+
</p>
250+
</details>
251+
252+
---
253+
<details><summary>Effects List</summary>
254+
<p>
255+
256+
- `01 - 8F` - Dynamic Effects
257+
- `BE` - Static (Solid Color)
258+
- `C9 - DA` - Music Effects
259+
260+
</p>
261+
</details>

‎requirements_dev.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
homeassistant

‎requirements_test.txt

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
pytest-homeassistant-custom-component==0.4.0

0 commit comments

Comments
 (0)