Insteon Linking Notes.md

devices configured in insteon-terminal

listDevices()
test_modem                     18.b8.8d
torch                          31.57.c9
dining                         31.50.35

Test adding the torch switch as a controller of dining switch in group 1, with on level 255, ramp rate 31 & button 1

I think this action performs the following steps:

1. Get the link database of the dining switch
2. Find the row number of the first unused record in the link database. If no unused record found, make a new record at the end.
3. Calculate the link db row number we want to update/insert
4. Put the dining switch device into all-link edit mode
5. Write the new link
6. Write the empty record at end (high water mark)

insteon-terminal command used:

                     torch     group ONLVL,RMPRT,button#
dining.addController("31.57.c9",01,   [255, 31,   1])

Creates this message which apparently puts the target device into linking mode

sent msg: OUT:`02623150351F2F0000020FB708000000000000000001`: Cmd:0x62|toAddress:31.50.35|messageFlags:0x1F=DIRECT:3:3|command1:0x2F|command2:0x00|userData1:0x00|userData2:0x02|userData3:0x0F|userData4:0xB7|userData5:0x08|userData6:0x00|userData7:0x00|userData8:0x00|userData9:0x00|userData10:0x00|userData11:0x00|userData12:0x00|userData13:0x00|userData14:0x01|

0262   : Insteon direct message
315035 : To Device (dining)
1F     : Flags: ??
2F     : Command1: Read/Write all-link database
00     : Command2: Empty
00     : user data 1: Empty
02     : user data 2: ??
0F     : user data 3: D3 address high byte??
B7     : user data 4: D4 address low byte??
08     : user data 5: Get one record??
00     : user data 6 - 13: Empty
01     : user data 14: ??

Then it modifies the device's link database

sent msg: OUT:`02623150351F2F0000020FBF08E2013157C9FF1F01A6`: Cmd:0x62|toAddress:31.50.35|messageFlags:0x1F=DIRECT:3:3|command1:0x2F|command2:0x00|userData1:0x00|userData2:0x02|userData3:0x0F|userData4:0xBF|userData5:0x08|userData6:0xE2|userData7:0x01|userData8:0x31|userData9:0x57|userData10:0xC9|userData11:0xFF|userData12:0x1F|userData13:0x01|userData14:0xA6|

0262   : Insteon direct message
315035 : To Device (dining)
1F     : Flags: ??
2F     : Command1: Read/Write all-link database
00     : Command2: Empty
00     : user data 1: Empty
02     : user data 2:
0FBF   : user data 3&4: database row number to write to
08     : user data 5: ??
E2     : user data 6: ??
01     : user data 7: ??
3157C9 : user data 8,9,10: Device to Link (torch)
FF     : user data 11: On level of link, FF = 100%
1F     : user data 12: ??
01     : user data 13: ??
A6     : user data 14: ??

This library might also write all zeros at the last link record - it didn't output to the CLI, but I see it in the source code. I think this is the so called "high water mark". https://github.com/pfrommerd/insteon-terminal/blob/05453f04975e09a887d477193cb233938790fb7e/python/device.py#L154