io-homecontrol documentation & implementation
See the codeREADME
iown-homecontrol
io-homecontrol® Documentation & Implementation in support of
Somfy's "So Open" commitment
:trollface:
Status
- Document Layer 1
- Document Layer 2
- Document Layer 3
- io-homecontrol Packet Definition
- Document Layer 4+
- Standard commands
- Advanced commands
- EMS2 Frame/CarrierSense: Infos needed!
- Documentation
- Cleanup: 60 %
- MkDocs version
- Better understanding of the device serial and QR/Barcode
- iohc Firmware
- Reverse official Somfy iohc Firmware
- Renode: Emulate Firmware
- Custom IDA Pro Loader
- Custom SVD file for use in Ghidra/IDA Pro
- Extract Si4461 config
- Reverse Actuator Firmware: STILL MISSING! Can you provide one?
- Hack the god damn ESP32 based Somfy Connectivity Box
- Reverse official Somfy iohc Firmware
- rtl_433: Corrections
- ReWrite of crypto test in Python
- Library
- 1W Library - Implementation Status: WIP
- 2W Library - Implementation Status: WIP
- Simple MicroPython implementation for rapid testing/prototyping
- Kaitai Struct implementation for easier portablity: 90%
- High Level Abstraction (KLF200 API and Overkiz Cloud JSON...)
- Bonus Points: Build a better/cheaper Somfy TaHoma with a LoRa32
- Support for RTS ^^
- Expose as ZigBee device for HomeAssistant integration other smart home systems
- Expose as HomeKit device (HomeSpan?) incl. QR code to ease installation
[!IMPORTANT] We need your help implementing the protocol! Please contact us!
Implementation
LoRa32 boards (HelTec/LilyGo) are the main target platform cause they work out of the box: Connect USB and flash via web interface (work in progress).
If you want to port the library to a non-ESP32 platform you should consider the following:
- Non-Volatile Storage needed
- Optional: AES engine (if you want to test your neighbors security)
[!TIP] Got a RTL-SDR? Use rtl_433 to decode io-homecontrol:
rtl_433 -R 189 -f 868.9M -s 1000k -g 42.1
Compatible Hardware
The recommended method is to use a LoRa32 board from HelTec or LilyGo. But there are many other boards, modules and combinations which work.
Be aware to use a device with support for FSK modulation in the 868 MHz band. That's it.
If not explicitly mentioned every board version is supported.
| HelTec | LilyGo | AdaFruit | Other |
|---|---|---|---|
| WiFi LoRa32 | LoRa32 | ESP32 Feather + FeatherWing RFM69HCW/RFM95W | FireBeetle ESP32 + LoRa 868MHz- Cover |
| Wireless Bridge | T-Beam | ||
| Wireless Tracker | T3-S3 | ||
| Wireless Stick | T-Watch S3 | ||
| Wireless Stick Lite |
Protocol
| Channel | Mode | CENTER | Start | End |
|---|---|---|---|---|
| 1 | 2W | 868,25 MHz | 868,0 MHz | 868,6 MHz |
| 2 | 1W/2W | 868,95 MHz | 868,7 MHz | 869,2 MHz |
| 3 | 2W | 869,85 MHz | 869,7 MHz | 870,0 MHz |
io-homecontrol (iohc) is a half-duplex protocol in the 868 MHz band with 2 modes.
- ↑ 1W (OneWay): Uni-Directional (1 Channel)
- ⇅ 2W (TwoWay): Bi-Directional (3 Channels)
- Modulation: FSK with 19,2 kHz deviation (Encoding: NRZ)
- Data/Baud Rate: 38400 bps (Encoding: UART 8N1)
- Frequency Hopping (FHSS): 2,7ms (Patent: 3ms) per Channel
Protocol Details
- Documentation
- Layer 1: Radio
- Layer 2: Link Layer
- Layer 3: Commands
Appendix
Appendix
iohc Alliance Background & History
Since this is not if interest for most people this is behind a collapsed section:
iohc Alliance Background & History
There is a low level software library thats accessible to members of the iohc alliance. Gateways ("Boxes") like the TaHoma/Cozytouch/etc. are just a "whiteware" product from Overkiz. The mobile apps are built by Modulotech. Overkiz, Somfy and Modulotech are owned by Atlantic.
The first manufacturer id was given to Velux. The initial alliance consisted of Velux, Somfy and Honeywell. From looking at the timeline my best guess would be that Somfy "invented" a new protocol but needed a stronger partner to get a bigger market share for their newly invented protocol.
The approached Velux and exchanged some patents. After their lawyers had a look at those patents they realized that Honeywell held some important patents without they would never make it to market. So they made them an offer to join the alliance in exchange for the patents as they predicted a big market share (Velux is the market leader in Europe). Honeywell only ever produced one gateway and seems to have implemented their own version of iohc named EvoHome (Protocol: Ramses II).
Fun Facts:
iohc is only really used in Europe. For the american market they use either RTS (433 MHz) or a 2.4GHz bastard implementation with a shitty range.
From the first 12 iohc alliance members only two use iohc to this day: Somfy and Velux. Everyone else quickly realizied that using such an obscure protocol is a dead end with no benefits which is costing them a lot of money.
-
Overkiz KizBox/MiniBox Whiteware Examples
- Cozytouch Branding: Atlantic, Thermor
- Cotherm I-Vista
- Hitachi HI-KUMO
- Nexity Eugénie
- Rexel Energeasy Connect
- Somfy Connexoon, TaHoma
-
iohc Alliance Members without any iohc products
- SecuYou
- Assa Abloy
- niko
- WindowMaster
- Renson
- Ciat
- Honeywell
- Hörmann
- Ehret (VOLETRONIC io)
- Alulux
- SIMU
- ExtremeLine (?)
iohc Quotes
Quotes
Taken from the FAQ on the io-homecontrol homepage (which is offline .. of course it is^^)
Encryption: the key to security - How does it work?
Each io-homecontrol installation has its own encryption key, which is present in all io products in the home. This key is automatically activated when the installation is first used. The emitter (remote control) issues its encryption key to the receiver (e.g. roller shutter) once and once only.
- For each command issued by the remote control, the receiver generates and sends back to the emitter a random number generated from a range of several billions.
- The emitter and receiver both perform automatic calculations based on this random number and the encryption key.
- If the results of these two calculations are identical, the emitter and receiver must have the same key, and the command (e.g. close the shutter) can therefore be carried out (e.g. close the shutter). The emitter is then informed that the command has been carried out.
The encryption key is "buried" among these exchanges between emitters and receivers, making it undetectable.
Bei der ersten Benutzung tauschen Fernbedienung (Sender) und Produkt (Empfänger) einen 128-Bit-Verschlüsselungscode aus und verbinden ihn bei jeder neuen Aktion mit einer zufällig gewählten Zahl. Daraus errechnet sich ein Code, den Sender und Empfänger miteinander abgleichen. Nur bei Übereinstimmung reagiert das Produkt auf die geforderte Aktion. Durch diesen Sicherheitsmechanismus wird die Reaktion auf einen fremden Sender ausgeschlossen. Die neue Anwendung sucht automatisch nach bereits bestehenden Produkten und berücksichtigt diese bei ihren Aktionen. Bevor Sender und Empfänger miteinander kommunizieren, wird die Verfügbarkeit des Kanals überprüft. Sollte eine Bandbreite überlagert oder besetzt sein, wartet die Anwendung vor der Kommunikation auf das Freiwerden der Frequenz (Listen before Talk) oder weicht auf einen der anderen Kanäle aus (Adaptive Frequency Agility).
iohc History
Quotes
- Initative was created in 2002
- Launched in July 2005 by Somfy, Velux and Honeywell
- First companies to adopt: Hörmann, Assa Abloy, Niko, Renson, Windowmaster
Trademark
The Trademark is held by VKR Holding A/S (Denmark) which also owns Velux. This explains why Velux has the first Manufacturer ID.
- Trademark History
- Trademark Priority: 2002-06-27 (France: 023171386)
- Filing: 2002-12-20
- Published for Opposition: 2004-05-04
- Registration: 2007-08-07
Links
Links
- Online Discussions
- rtl_433: Add new decoder for Velux shutter remote control - io-homecontrol protocoll
- RFHEM: Somfy Smoove io remote 868.25 MHz
- OpenHAB: Io-homecontrol / velux - something's in the bush
- Velux Blinds
- No KUX, just Loxone
- Velux SML Rolläden „ablernen" bzw. resetten
- snipsvelux
- VeluxIR - IR protocol for old Velux remotes
- Kizbox Rooting
- FCC: VELUX America Inc.
- FLOSS @ Overkiz
Contributors
Thanks to everyone who helped in gathering all the information that makes up this repo!
Since there are so many people who helped with the "opening" of the procotol i will try my best to name everyone involved. If you want your name on here or deleted then drop me a message.
Contributors
Languages
C++
69.0%
C
31.0%
io-homecontrol documentation & implementation
See the codeREADME
iown-homecontrol
io-homecontrol® Documentation & Implementation in support of
Somfy's "So Open" commitment
:trollface:
Status
- Document Layer 1
- Document Layer 2
- Document Layer 3
- io-homecontrol Packet Definition
- Document Layer 4+
- Standard commands
- Advanced commands
- EMS2 Frame/CarrierSense: Infos needed!
- Documentation
- Cleanup: 60 %
- MkDocs version
- Better understanding of the device serial and QR/Barcode
- iohc Firmware
- Reverse official Somfy iohc Firmware
- Renode: Emulate Firmware
- Custom IDA Pro Loader
- Custom SVD file for use in Ghidra/IDA Pro
- Extract Si4461 config
- Reverse Actuator Firmware: STILL MISSING! Can you provide one?
- Hack the god damn ESP32 based Somfy Connectivity Box
- Reverse official Somfy iohc Firmware
- rtl_433: Corrections
- ReWrite of crypto test in Python
- Library
- 1W Library - Implementation Status: WIP
- 2W Library - Implementation Status: WIP
- Simple MicroPython implementation for rapid testing/prototyping
- Kaitai Struct implementation for easier portablity: 90%
- High Level Abstraction (KLF200 API and Overkiz Cloud JSON...)
- Bonus Points: Build a better/cheaper Somfy TaHoma with a LoRa32
- Support for RTS ^^
- Expose as ZigBee device for HomeAssistant integration other smart home systems
- Expose as HomeKit device (HomeSpan?) incl. QR code to ease installation
[!IMPORTANT] We need your help implementing the protocol! Please contact us!
Implementation
LoRa32 boards (HelTec/LilyGo) are the main target platform cause they work out of the box: Connect USB and flash via web interface (work in progress).
If you want to port the library to a non-ESP32 platform you should consider the following:
- Non-Volatile Storage needed
- Optional: AES engine (if you want to test your neighbors security)
[!TIP] Got a RTL-SDR? Use rtl_433 to decode io-homecontrol:
rtl_433 -R 189 -f 868.9M -s 1000k -g 42.1
Compatible Hardware
The recommended method is to use a LoRa32 board from HelTec or LilyGo. But there are many other boards, modules and combinations which work.
Be aware to use a device with support for FSK modulation in the 868 MHz band. That's it.
If not explicitly mentioned every board version is supported.
| HelTec | LilyGo | AdaFruit | Other |
|---|---|---|---|
| WiFi LoRa32 | LoRa32 | ESP32 Feather + FeatherWing RFM69HCW/RFM95W | FireBeetle ESP32 + LoRa 868MHz- Cover |
| Wireless Bridge | T-Beam | ||
| Wireless Tracker | T3-S3 | ||
| Wireless Stick | T-Watch S3 | ||
| Wireless Stick Lite |
Protocol
| Channel | Mode | CENTER | Start | End |
|---|---|---|---|---|
| 1 | 2W | 868,25 MHz | 868,0 MHz | 868,6 MHz |
| 2 | 1W/2W | 868,95 MHz | 868,7 MHz | 869,2 MHz |
| 3 | 2W | 869,85 MHz | 869,7 MHz | 870,0 MHz |
io-homecontrol (iohc) is a half-duplex protocol in the 868 MHz band with 2 modes.
- ↑ 1W (OneWay): Uni-Directional (1 Channel)
- ⇅ 2W (TwoWay): Bi-Directional (3 Channels)
- Modulation: FSK with 19,2 kHz deviation (Encoding: NRZ)
- Data/Baud Rate: 38400 bps (Encoding: UART 8N1)
- Frequency Hopping (FHSS): 2,7ms (Patent: 3ms) per Channel
Protocol Details
- Documentation
- Layer 1: Radio
- Layer 2: Link Layer
- Layer 3: Commands
Appendix
Appendix
iohc Alliance Background & History
Since this is not if interest for most people this is behind a collapsed section:
iohc Alliance Background & History
There is a low level software library thats accessible to members of the iohc alliance. Gateways ("Boxes") like the TaHoma/Cozytouch/etc. are just a "whiteware" product from Overkiz. The mobile apps are built by Modulotech. Overkiz, Somfy and Modulotech are owned by Atlantic.
The first manufacturer id was given to Velux. The initial alliance consisted of Velux, Somfy and Honeywell. From looking at the timeline my best guess would be that Somfy "invented" a new protocol but needed a stronger partner to get a bigger market share for their newly invented protocol.
The approached Velux and exchanged some patents. After their lawyers had a look at those patents they realized that Honeywell held some important patents without they would never make it to market. So they made them an offer to join the alliance in exchange for the patents as they predicted a big market share (Velux is the market leader in Europe). Honeywell only ever produced one gateway and seems to have implemented their own version of iohc named EvoHome (Protocol: Ramses II).
Fun Facts:
iohc is only really used in Europe. For the american market they use either RTS (433 MHz) or a 2.4GHz bastard implementation with a shitty range.
From the first 12 iohc alliance members only two use iohc to this day: Somfy and Velux. Everyone else quickly realizied that using such an obscure protocol is a dead end with no benefits which is costing them a lot of money.
-
Overkiz KizBox/MiniBox Whiteware Examples
- Cozytouch Branding: Atlantic, Thermor
- Cotherm I-Vista
- Hitachi HI-KUMO
- Nexity Eugénie
- Rexel Energeasy Connect
- Somfy Connexoon, TaHoma
-
iohc Alliance Members without any iohc products
- SecuYou
- Assa Abloy
- niko
- WindowMaster
- Renson
- Ciat
- Honeywell
- Hörmann
- Ehret (VOLETRONIC io)
- Alulux
- SIMU
- ExtremeLine (?)
iohc Quotes
Quotes
Taken from the FAQ on the io-homecontrol homepage (which is offline .. of course it is^^)
Encryption: the key to security - How does it work?
Each io-homecontrol installation has its own encryption key, which is present in all io products in the home. This key is automatically activated when the installation is first used. The emitter (remote control) issues its encryption key to the receiver (e.g. roller shutter) once and once only.
- For each command issued by the remote control, the receiver generates and sends back to the emitter a random number generated from a range of several billions.
- The emitter and receiver both perform automatic calculations based on this random number and the encryption key.
- If the results of these two calculations are identical, the emitter and receiver must have the same key, and the command (e.g. close the shutter) can therefore be carried out (e.g. close the shutter). The emitter is then informed that the command has been carried out.
The encryption key is "buried" among these exchanges between emitters and receivers, making it undetectable.
Bei der ersten Benutzung tauschen Fernbedienung (Sender) und Produkt (Empfänger) einen 128-Bit-Verschlüsselungscode aus und verbinden ihn bei jeder neuen Aktion mit einer zufällig gewählten Zahl. Daraus errechnet sich ein Code, den Sender und Empfänger miteinander abgleichen. Nur bei Übereinstimmung reagiert das Produkt auf die geforderte Aktion. Durch diesen Sicherheitsmechanismus wird die Reaktion auf einen fremden Sender ausgeschlossen. Die neue Anwendung sucht automatisch nach bereits bestehenden Produkten und berücksichtigt diese bei ihren Aktionen. Bevor Sender und Empfänger miteinander kommunizieren, wird die Verfügbarkeit des Kanals überprüft. Sollte eine Bandbreite überlagert oder besetzt sein, wartet die Anwendung vor der Kommunikation auf das Freiwerden der Frequenz (Listen before Talk) oder weicht auf einen der anderen Kanäle aus (Adaptive Frequency Agility).
iohc History
Quotes
- Initative was created in 2002
- Launched in July 2005 by Somfy, Velux and Honeywell
- First companies to adopt: Hörmann, Assa Abloy, Niko, Renson, Windowmaster
Trademark
The Trademark is held by VKR Holding A/S (Denmark) which also owns Velux. This explains why Velux has the first Manufacturer ID.
- Trademark History
- Trademark Priority: 2002-06-27 (France: 023171386)
- Filing: 2002-12-20
- Published for Opposition: 2004-05-04
- Registration: 2007-08-07
Links
Links
- Online Discussions
- rtl_433: Add new decoder for Velux shutter remote control - io-homecontrol protocoll
- RFHEM: Somfy Smoove io remote 868.25 MHz
- OpenHAB: Io-homecontrol / velux - something's in the bush
- Velux Blinds
- No KUX, just Loxone
- Velux SML Rolläden „ablernen" bzw. resetten
- snipsvelux
- VeluxIR - IR protocol for old Velux remotes
- Kizbox Rooting
- FCC: VELUX America Inc.
- FLOSS @ Overkiz
Contributors
Thanks to everyone who helped in gathering all the information that makes up this repo!
Since there are so many people who helped with the "opening" of the procotol i will try my best to name everyone involved. If you want your name on here or deleted then drop me a message.
Contributors
Languages
C++
69.0%
C
31.0%