Skip to content

Commit 294f1b0

Browse files
pasthevpasthev
committedMar 13, 2025·
Added User guide in Readme
1 parent 971caf4 commit 294f1b0

File tree

3 files changed

+228
-4
lines changed

3 files changed

+228
-4
lines changed
 

‎README.md

+224-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@
22

33

44
### ☞ [View & Use Sensus Online](https://pasthev.github.io/sensus/)
5+
### ☞ [User Guide](#user_guide)
56

67

78
<div style="text-align: center;">
@@ -99,4 +100,226 @@ Bugs or Feature request? Us the [Issues](https://github.com/pasthev/sensus/issue
99100
<img src="screenshots/sensus_screenshot_02.jpg" width="600">
100101
</div>
101102

102-
[Guide d'utilisation en français](README_FR.md)
103+
104+
105+
106+
107+
## <a id="user_guide">User Guide
108+
109+
*Guide d'utilisation en français [ici](README_FR.md)*
110+
111+
Topics covered in this guide:
112+
* [Analyzing a captured IR frame with Sample Data](#sample)
113+
* [Removing repetitions in an IR or RF sequence](#remove)
114+
* [Bits stories: Explanation of the NEC protocol](#bits)
115+
* [Converting LIRC, or Short Codes, to Broadlink, Tuya, Pronto, and other codes](#lirc)
116+
* [Reminders about Sensus functions](#tips)
117+
---
118+
119+
# Sensus - User Guide
120+
121+
Well, I'm going to start this documentation in the worst possible way, with a series of eye-straining numbers, so I'll add an image to brighten things up...
122+
123+
![image](screenshots/remote.png)
124+
125+
## Sample data<a id="sample"></a>
126+
127+
Here's an example of an awful Raw, in which the signal was recorded as received multiple times (as long as the user pressed the button during learning), and interrupted midway:
128+
```
129+
9041, 4524, 550, 550, 550, 1722, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 602, 550, 550, 550, 550, 550, 1722, 550, 550, 550, 550, 550, 1722, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 550, 550, 550, 550, 550, 550, 550, 550, 550, 550, 550, 550, 1722, 550, 550, 550, 1722, 550, 1722, 550, 1722, 550, 1722, 550, 40362, 9028, 4532, 548, 548, 548, 1725, 548, 1725, 548, 1725, 548, 602, 548, 1725, 548, 1725, 548, 548, 548, 1725, 548, 548, 548, 548, 548, 602, 548, 1725, 548, 548, 548, 602, 548, 1725, 548, 1725, 548, 1725, 548, 548, 548, 1725, 548, 602, 548, 548, 548, 548, 548, 548, 548, 602, 548, 548, 548, 1725, 548, 548, 548, 1725, 548, 1725, 548, 1725, 548, 1725, 548, 40332, 9033, 4545, 552, 552, 552, 1719, 552, 1719, 552, 1719, 552, 607, 552, 1719, 552, 1719, 552, 552, 552, 1719, 552, 552, 552, 552, 552, 552, 552, 1719, 552, 552, 552, 607, 552, 1719, 552, 1719, 552, 1719, 552, 552, 552, 1719, 552, 552, 552, 552, 552, 552, 552, 552, 552, 552, 552, 552, 552, 1719, 552, 552, 552, 1719, 552, 1719, 552, 1719, 552, 1719, 552, 40345, 9034, 4528, 542, 542, 542, 1731, 542, 1731, 542, 1731, 542, 608, 542, 1731, 542, 1731, 542, 542, 542, 1731, 542, 608, 542, 542, 542, 542, 542, 1731, 542, 542, 542, 542, 542, 1731, 542, 1731, 542, 1731, 542, 542, 542, 1731, 542, 608, 542, 542, 542, 542, 542, 542, 542, 608, 542, 542, 542, 1731, 542, 542, 542, 1731, 542, 1731, 542, 1731, 542, 1731, 542, 40384, 9030, 4528, 548, 548, 548, 1727, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 548, 548, 548, 548, 606, 548, 1727, 548, 548, 548, 548, 548, 1727, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 548, 548, 548, 548, 548, 548, 548, 548, 548, 548, 548, 548, 1727, 548, 548, 548, 1727, 548, 1727, 548, 1727, 548, 1727, 548, 40323, 9030, 4528, 548, 548, 548, 1727, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 548, 548, 548, 548, 548, 548, 1727, 548, 548, 548, 548, 548, 1727, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 606, 548, 548, 548, 606, 548, 548, 548, 548, 548, 548, 548, 1727, 548, 606, 548, 1727, 548, 1727, 548, 1727, 548, 1727, 548, 40362, 9028, 4532, 548, 548, 548, 1725, 548, 1725, 548, 1725, 548, 602, 548, 1725, 548, 1725, 548, 548, 548, 1725, 548, 548, 548, 548, 548, 602, 548, 1725, 548, 548, 548, 602, 548, 1725, 548, 1725, 548, 1725, 548, 548, 548, 1725, 548, 602, 548, 548, 548, 548, 548, 548, 548, 602, 548, 548, 548, 1725, 548, 548, 548, 1725, 548, 1725, 548, 1725, 548, 1725, 548, 40345, 9034, 4528, 542, 542, 542, 1731, 542, 1731, 542, 1731, 542, 608, 542, 1731, 542, 1731, 542, 542, 542, 1731, 542, 608, 542, 542, 542, 542, 542, 1731, 542, 542, 542, 542, 542, 1731, 542, 1731, 542, 1731, 542, 542, 542, 1731, 542, 608, 542, 542, 542, 542, 542, 542, 542, 608, 542, 542, 542, 1731, 542, 542, 542, 1731, 542, 1731, 542, 1731, 542, 1731, 542, 40384, 9030, 4528, 548, 548, 548, 1727, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 548, 548, 548, 548, 606, 548, 1727, 548, 548, 548, 548, 548, 1727, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 548, 548, 548, 548, 548, 548, 548, 548, 548, 548, 548, 548, 1727, 548, 548, 548, 1727, 548, 1727, 548, 1727, 548, 1727, 548, 40345, 9034, 4528, 542, 542, 542, 1731, 542, 1731, 542, 1731, 542, 608, 542, 1731, 542, 1731, 542, 542, 542, 1731, 542, 608, 542, 542, 542, 542, 542, 1731, 542, 542, 542, 542, 542, 1731, 542, 1731, 542, 1731, 542, 542, 542, 1731, 542, 608, 542, 542, 542, 542, 542, 542, 542, 608, 542, 542, 542, 1731, 542, 542, 542, 1731, 542, 1731, 542, 1731, 542, 1731, 542, 40323, 9030, 4528, 548, 548, 548, 1727, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 1727, 548, 548, 548, 1727, 548, 548, 548, 548, 548, 548, 548, 1727, 548, 548
130+
```
131+
Copy it, then paste these values into Sensus's *Raw* field.
132+
* Close the interface panels to keep only the ones you need - you can always reopen them using the purple toolbar at the top right.
133+
* Don't click convert yet, but in the "Raw Analysis" panel, click "Read Raw":
134+
* The signal is drawn, with its multiple repetitions. We can see that it is repeated ten times, with a tail of an unfinished signal.
135+
136+
137+
![image](screenshots/sensusManual01.jpg)
138+
139+
The command is displayed, highlighted here in yellow: `7689 d02f`.
140+
141+
* Obviously, it is encoded following the NEC protocol, since the program was able to deduce the "*short*": `6e0b`. This is NEC Standard, with the address on a single byte, it should be read: "*Send to device #6e command 0b*", or, in decimal: "*Send to device #110 command 11*".
142+
** Note that the initial intent of the first byte being the device address is long gone: except for the first 256 devices that have been registered with this standard, we should now rather consider the whole "*Short*" as a command.
143+
144+
* The header ("**Header**", here in red), has been identified: `9041, 4524`. A long high, followed by a low half its length - standard too.
145+
146+
* The **Zero** (in white) and the **One** (dark blue) have been calculated at their average values, respectively `550, 550`, and `550, 1727` (the second value for encoding the *One* is triple the first, this is again a common standard).
147+
148+
* As long as a remote control button is held down, it sends the signal, but each time marking a pause between two: the "**Repeat Signal**", which is generally the same as the end-of-sequence signal, the "**Gap**". This one is often the sum value of the entire signal. I have indicated the first *Repeat* in green, the second in light blue: `40362`, and `40332`. The value should rather be around 54004 here, but it doesn't matter: the essential is to send a long white, and the durations are expressed in μs - so we are talking here about a pause of 0.04 or 0.05 seconds.
149+
* Sensus did not record this value as "**Gap**" in the top field: it is wary, because the *Gap* is expected at the end of the signal, but perhaps I should make it less wary, because we will later use this repeat value as *Gap*.
150+
151+
* The "**Ptrail**" is a short "*half Zero*" sent after the command, just before the *Repeat* or *Gap*. It is used to indicate the unit length, and to make the value sequence even, to ensure that the Gap is interpreted as a silence. The Ptrail was not spotted here by Sensus, I don't know why - maybe because of the unfinished tail - but it will be in due time.
152+
153+
154+
## Removing repetitions<a id="remove"></a>
155+
156+
We have everything we need to either clean the sequence, or re-generate it from the values identified in the "**Commands**" panel - the missing values being `Ptrail: 550` (a half Zero), and `Gap: 40350` (or `54554`, which is the sum of the command values, excluding the *Ptrail*, if you want perfect balancing)
157+
158+
### Cleaning:
159+
160+
The method is simple. We start by removing from the Raw all the values after the first Repeat (which will conveniently become our end-of-sequence *Gap*). This leaves only the following sequence in the Raw field:
161+
162+
```
163+
9041, 4524, 550, 550, 550, 1722, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 602, 550, 550, 550, 550, 550, 1722, 550, 550, 550, 550, 550, 1722, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 550, 550, 550, 550, 550, 550, 550, 550, 550, 550, 550, 550, 1722, 550, 550, 550, 1722, 550, 1722, 550, 1722, 550, 1722, 550, 40362
164+
```
165+
* Do it, then click again in the "**Raw Analysis**" panel on "**Read Raw**".
166+
* In the "**Raw**" panel, click on "**Draw**".
167+
* You now have a clean signal, a unique command and short, which have the same values as those initially repeated:
168+
169+
![image](screenshots/sensusManual02.jpg)
170+
171+
* Note that this time, the **Ptrail** and the **Gap** are identified: `550` and `40362`.
172+
* As is, the signal has every chance of working, but note that in some standards requiring balancing, `40362` should be replaced by `54004`, which is the sum of the signal values. But since the value `40350` was recorded, it's best to keep it.
173+
174+
Add this number manually in Raw, then click on "**Draw**": the signal is displayed, with its Gap, ready to be converted into the desired format.
175+
176+
177+
178+
179+
180+
## Interlude: bit stories<a id="bits"></a>
181+
Before seeing the other cleaning method, let's have a look at Raw Analysis. By scrolling to the bottom of the analysis, you can see these values:
182+
183+
```
184+
Binary: *00010101000101000100000001000001010100010000000000000100010101010*
185+
> Nec encoding detected with shift value: 0/1 *01110110 10001001 + 11010000 00101111* - hex: *** 7689 d02f *** - short: < 6e0b >
186+
```
187+
188+
Explanation:
189+
190+
* The "*Binary*" line displays the Raw values converted plainly into 0 and 1.
191+
* The "*with shift value*" line reads these bits (the "**bibits**") in pairs, here encoded 00=0 & 01=1, which is not always the case.
192+
* The "*hex*" line displays these values in hexadecimal: 01110110 in binary is written 76 in hexadecimal, or 110 in decimal.
193+
194+
195+
```
196+
550, 550, 550, 1722, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 602...
197+
0 0 0 1 0 1 0 1 0 0 0 1 0 1 0 0 0 1 0 0...
198+
| 0 | 1 | 1 | 1 | 0 | 1 | 1 | 0 | 1 | 0 |...
199+
| HEX 76 | HEX 89...
200+
```
201+
202+
Reading the "**Short**" command in the NEC sequence `7689 d02f`:
203+
204+
`550` and `1722` are pulse and silence durations to be emitted. This means that sending a `0` here requires `550+550=1100 μs` and a `1`, `550+1722=2272μs`, which is more than double.
205+
206+
In fact, sending `11111111` would take, on this tiny scale, much more time than sending `00000000`, and the interpretation of signals with variable durations would be less precise, and prone to misinterpretation errors.
207+
208+
The solution? Always send a value and its binary inverse. Thus, the signal length becomes constant, and you have a reread value to check for proper reception.
209+
210+
Thus, if we consider the emitted sequence:
211+
```
212+
01110110 10001001 + 11010000 00101111
213+
```
214+
215+
Placed one above the other, the values are indeed inverses:
216+
```
217+
01110110 - 11010000
218+
10001001 - 00101111
219+
```
220+
221+
The check being conclusive, we remove the second line, to take only the first:
222+
```
223+
01110110 - 11010000
224+
```
225+
226+
These two bytes are encoded in LSB First, meaning the least significant value first, as if we were writing `1234` > `4321`. So we flip each one horizontally:
227+
```
228+
01110110 - 11010000
229+
01101110 - 00001011
230+
```
231+
which is `6e - 0b`
232+
233+
This command is in the only format generally communicated by manufacturers - when they're kind enough to communicate their IR codes. It is also the format used by **LIRC**, and there are many online databases, such as the [LIRC Remotes Databases](https://lirc-remotes.sourceforge.net/remotes-table.html).
234+
235+
Thus, if we browse this [LIRC table](https://lirc-remotes.sourceforge.net/remotes-table.html) and click for example [samsung/0070-63.lircd.conf](https://sourceforge.net/p/lirc-remotes/code/ci/master/tree/remotes/samsung/0070-63.lircd.conf), we rediscover all the values that have been discussed here.
236+
237+
The "**Shorts**" are in the begin codes category:
238+
239+
```
240+
begin codes :
241+
KEY_POWER 0x00000000000040BF # Was: Power
242+
D.Trk 0x000000000000847B
243+
Input 0x00000000000024DB
244+
KEY_KPPLUS 0x000000000000649B # Was: +
245+
KEY_KPMINUS 0x00000000000014EB # Was: -
246+
```
247+
`0x` indicates a hexadecimal notation, and all the 00s on the left are as useful as saying "*I'm cold, it's 000000015° in my living room!*: we remove them, and we discover that to turn on this Samsung TV, you have to send it the short code `40bf`.
248+
* If necessary, Sensus allows you to quickly convert a *Short* to a command, and vice versa: it's not useful here, but enter the *Short* at the top left, click the arrow that goes to the right, you will get the result of the inversion and LSB conversion at the top right: `02fd fd02` for `40bf`.
249+
250+
The LIRC page contains the info to enter in the "Commands" panel of Sensus:
251+
252+
```
253+
header 4635 4332
254+
one 656 1562
255+
zero 656 445
256+
ptrail 656
257+
pre_data_bits 16
258+
pre_data 0xA0A0
259+
gap 47917
260+
toggle_bit 0
261+
```
262+
Where all this becomes really interesting for home automation is that by searching, you can find on the Web the famous secret codes, the "**Discrete Codes**", which contain sequences that the TV for example can recognize, while there is no equivalent button on its remote control.
263+
264+
For example, for my TV (*yes, I have an old TV, I'm a bit technophobic*):
265+
266+
```
267+
begin remote
268+
269+
name Samsung_BN59-00937A
270+
bits 16
271+
flags SPACE_ENC|CONST_LENGTH
272+
eps 30
273+
aeps 100
274+
header 4605 4344
275+
one 678 1551
276+
zero 678 436
277+
ptrail 679
278+
pre_data_bits 16
279+
pre_data 0xE0E0
280+
gap 107626
281+
toggle_bit_mask 0x0
282+
283+
begin codes
284+
TV1_Power 0x40BF # Was: Power
285+
TV1_PowerOff 0x19E6 # Was: Power Off
286+
TV1_PowerOn 0x9966 # Was: Power On
287+
TV1_VolumeUp 0xE01F # Was: Vol+
288+
```
289+
`40BF` is the button that works as an On/Off toggle on my remote. But if I want to program Jeedom or Home-Assistant for remote shutdown or automated power-on via my Tuya, Broadlink or other IR transmitter, I send `19E6`, I'm sure to turn it off, and with `9966`, I can send the code twice by mistake, the TV will remain on.
290+
291+
Armed with all this, let's get back to our initial signal. We have seen how to "clean" it, but since we have extracted everything we wanted to know - the equivalent of the LIRC info - as an alternative we can also generate it from scratch, using the info that we have recovered in the *Commands* panel:
292+
293+
```
294+
header 9041, 4524
295+
one 551, 1722
296+
zero 551, 551
297+
ptrail 550
298+
gap 45000
299+
300+
Code "Short" 6e0b
301+
```
302+
303+
## Generating a sequence from LIRC info<a id="lirc"></a>
304+
All that remains is to enter the appropriate values in the *Sensus* Commands panel, and click "**Convert**" in the Commands panel.
305+
306+
![image](screenshots/sensusManual03.jpg)
307+
308+
## A few points to know:<a id="tips"></a>
309+
* When you enter a Raw in Sensus and click on **Convert**, the Raw values are adjusted for maximum compatibility with other protocols. These changes of a few microseconds will not affect your signal, whether it is IR or RF.
310+
311+
* As soon as a frequency is entered, it is displayed encoded in the Raw sequence, in the form of a four-value header: the first two contain the frequency, the next ones the number of command values in the sequence. These are not of much use in a Raw, but they do not affect the emitted signal. Note that I have chosen by default to exclude these useless values from the graphical display when you click on "**Convert**". But I have programmed the "**Draw**" button to display it, if you want to see the exact signal.
312+
313+
314+
* To indicate the frequency in Hertz, you can either:
315+
* Click the desired frequency button in the *Commands* panel.
316+
* Enter it directly in the corresponding field.
317+
* A white arrow appears in the field when it is empty, giving access to a drop-down menu with the common frequencies.
318+
319+
![image](screenshots/sensusManual04.jpg)
320+
321+
322+
**[Pasthev 2025](https://pasthev.github.io/)**
323+
324+
---
325+
_Feedback / Questions / Small thank you: Use the [Discussions](https://github.com/pasthev/sensus/discussions) link above, or contact me via my [anonymous contact form](https://docs.google.com/forms/d/e/1FAIpQLSckf2f04hYhTN3T6GvchbxhjhKcYHLMRDXnrRfqlM_eRW_NiA/viewform?usp=sf_link)_

‎README_FR.md

+4-3
Original file line numberDiff line numberDiff line change
@@ -69,9 +69,10 @@ Binary: *00010101000101000100000001000001010100010000000000000100010101010*
6969

7070
Explication :
7171

72-
La ligne "*Binary*" affiche les valeurs Raw converties bêtement en 0 et en 1
73-
La ligne "*with shift value*" lit ces bits (les "**bibits**") deux par deux, ici encodés 00=0 & 01=1, ce qui n'est pas toujours le cas.
74-
La ligne "*hex*" affiche ces valeurs en hexadécimal: 01110110 en binaire s'écrit 76 en héxadécimal, ou 110 en décimal.
72+
* La ligne "*Binary*" affiche les valeurs Raw converties bêtement en 0 et en 1
73+
* La ligne "*with shift value*" lit ces bits (les "**bibits**") deux par deux, ici encodés 00=0 & 01=1, ce qui n'est pas toujours le cas.
74+
* La ligne "*hex*" affiche ces valeurs en hexadécimal: 01110110 en binaire s'écrit 76 en héxadécimal, ou 110 en décimal.
75+
7576
```
7677
550, 550, 550, 1722, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 1722, 550, 550, 550, 1722, 550, 602...
7778
0 0 0 1 0 1 0 1 0 0 0 1 0 1 0 0 0 1 0 0...

‎screenshots/sensus_screenshot_03.jpg

-107 KB
Loading

0 commit comments

Comments
 (0)
Please sign in to comment.