gdoor-org/gdoor

Wifi adapter and bus protocol documentation for the Gira TKS Door System

https://gdoor-org.github.io/

---

Gira is a german manufacturer of house appliances, including door systems. These systems are connected via a proprietary two wire bus system. GDOOR is a project to collect and document findings about the Gira Door System, all figured out by reverse engineering.

The GDOOR hardware adapter allows listening and controlling the bus and e.g. integrating a Gira door bell into a smart home. It might serve as an DIY alternative to the Gira TKS-IP-Gateway. It supports the following features:

• listening to the bus, e.g. to trigger notifications on mobile devices when a door bell button is pressed
• sending to the bus, e.g. to open the door

Receiving and sending audio/video is currently neither supported nor plannend.

Contributions are welcome!

Bus Adapter Hardware

Currently work is ongoing to release a ESP32-based adapter, which translates the bus messages to MQTT/serial and vice versa.

Hardware can be found in the hardware subfolder, corresponding firmware in the firmware subfolder.

Note

Work is not finished yet.

The adapter was successfully tested with

• Gira Türkommunikations-System Steuergerät Audio (1287 00)
• Gira Türkommunikations-System Steuergerät Video (1288 00)
• Gira Wohnungsstation AP (1250 015)
• Gira Wohnungsstation Video AP Plus (1239 03)
• Gira Türstation AP 1-fach (1266 65/66/67)
• Gira Türstation AP 3-fach (1267 65/66/67)

Integrations with Smart Home Platforms

• Home Assistant

Gira Bus Protocol

See detailed findings about the Gira bus protocol.

gdoor's Issues

Output is invalid JSON

e.g. validate the output with https://jsonlint.com/:

• trailing commas are not allowed
• hex values are not allowed

Merge debug output into single JSON

Not urgent but I think we should invest the effort to only send 1 JSON per event. Initially I thought only Home Assistant gets confused when sending multiple, but it seems that MQTT Explorer also doesn't recognize the JSON format if Gdoor debug mode is enabled:

How to build an Gira Bus <-> Smart Home adapter

Hello,
Thanks a lot for your efforts on documenting!

I’m looking for a (self-made) solution to open our house door via Home Assistant. I know there are commercial solutions like Gira TKS-IP-Gateway. But it’s too pricy.

I’m wondering if you could give me some guidance on how to build the hardware to connect to the bus? I’m a software guy, don’t know much about hardware. But e.g. I’m a bit familiar with ESPHome.

Thanks and have a nice day!

Build firmware via GitHub Actions & publish releases

To be able to download the firmware & upload it via Wifi web UI.

First action isn't received

As already mentioned by @DaSchaef, it seems like the very first action on the bus is always lost somehow.

Steps to reproduce:

1. connect adapter & monitor / upload & monitor
2. press e.g. "open door" on the indoor station
3. nothing is received
4. press "open door" again
5. action is received

Last action gets repeated?

I think there might be a bug in the firmware: apparently the last received action is repeated every now an then. In the screenshot there is a log of the actions received by Gdoor (note the increasing event_id). E.g. there are actions received during night time where there was clearly no user interaction. Maybe there are (yet unknown) things going on on the bus and due to a bug the last received action is detected again?
Unfortunately I don't have a debug mode log recorded yet - I'll try to record one asap.

Add high-level props to JSON output

To allow comfortable automations/triggers in Smart Home platforms like Home Assistant.

Suggestion for new fields:

• action: doorBell / floorBell / openDoor / ...
• param: which button was pressed
• deviceType: doorStation / indoorStation / controller
• source
• destination

Add video and other bus actions to docs

Collecting some more bus actions to add them to the docs, code + streamline wording. Work in progress.

Outdoor ring & accept audio call & open door & manual close call

{"action": "BUTTON_RING", "parameters": "0360", "source": "A286FD", "destination": "000000", "type": "OUTDOOR", "busdata": "011011A286FD0360A04A", "event_id": "12"}
{"busdata": "011011A286FD0360A04A", "data": ["0x1", "0x10", "0x11", "0xA2", "0x86", "0xFD", "0x3", "0x60", "0xA0", "0x4A"], "valid": true}

# indoor station automatically tells the outdoor station to start the video stream
{"action": "CALL_ACCEPT_VIDEO", "parameters": "0278", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "022028ED3F4B0278A1A286FD01", "event_id": "13"}
{"busdata": "022028ED3F4B0278A1A286FD01", "data": ["0x2", "0x20", "0x28", "0xED", "0x3F", "0x4B", "0x2", "0x78", "0xA1", "0xA2", "0x86", "0xFD", "0x1"], "valid": true}

# user activates 2-way audio by pressing the "phone" button on the indoor station
{"action": "CALL_ACCEPT", "parameters": "0000", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "020021ED3F4B0000A1A286FD60", "event_id": "14"}
{"busdata": "020021ED3F4B0000A1A286FD60", "data": ["0x2", "0x0", "0x21", "0xED", "0x3F", "0x4B", "0x0", "0x0", "0xA1", "0xA2", "0x86", "0xFD", "0x60"], "valid": true}

# user opens the door by pressing the "lock" button
{"action": "OPEN_DOOR", "parameters": "0060", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "020031ED3F4B0060A1A286FDD0", "event_id": "15"}
{"busdata": "020031ED3F4B0060A1A286FDD0", "data": ["0x2", "0x0", "0x31", "0xED", "0x3F", "0x4B", "0x0", "0x60", "0xA1", "0xA2", "0x86", "0xFD", "0xD0"], "valid": true}

# user closes the audio & video call by pressing the "phone" button again
{"action": "CALL_CLOSE", "parameters": "0000", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "020020ED3F4B0000A1A286FD5F", "event_id": "16"}
{"busdata": "020020ED3F4B0000A1A286FD5F", "data": ["0x2", "0x0", "0x20", "0xED", "0x3F", "0x4B", "0x0", "0x0", "0xA1", "0xA2", "0x86", "0xFD", "0x5F"], "valid": true}

# unclear what this is doing
{"action": "ACTION_UNKOWN", "parameters": "0000", "source": "000000", "destination": "000000", "type": "TYPE_UNKOWN", "busdata": "E20020ED3F4B0000A1A286FD5F", "event_id": "17"}
{"busdata": "E20020ED3F4B0000A1A286FD5F", "data": ["0xE2", "0x0", "0x20", "0xED", "0x3F", "0x4B", "0x0", "0x0", "0xA1", "0xA2", "0x86", "0xFD", "0x5F"], "valid": false}

Outdoor ring + open door (without accepting audio call)

{"action": "BUTTON_RING", "parameters": "0360", "source": "A286FD", "destination": "000000", "type": "OUTDOOR", "busdata": "011011A286FD0360A04A", "event_id": "29"}
{"busdata": "011011A286FD0360A04A", "data": ["0x1", "0x10", "0x11", "0xA2", "0x86", "0xFD", "0x3", "0x60", "0xA0", "0x4A"], "valid": true}
{"action": "CALL_ACCEPT_VIDEO", "parameters": "0278", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "022028ED3F4B0278A1A286FD01", "event_id": "30"}
{"busdata": "022028ED3F4B0278A1A286FD01", "data": ["0x2", "0x20", "0x28", "0xED", "0x3F", "0x4B", "0x2", "0x78", "0xA1", "0xA2", "0x86", "0xFD", "0x1"], "valid": true}
{"action": "OPEN_DOOR", "parameters": "0060", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "020031ED3F4B0060A1A286FDD0", "event_id": "31"}
{"busdata": "020031ED3F4B0060A1A286FDD0", "data": ["0x2", "0x0", "0x31", "0xED", "0x3F", "0x4B", "0x0", "0x60", "0xA1", "0xA2", "0x86", "0xFD", "0xD0"], "valid": true}

# the following are happening automatically after 30s
{"action": "CALL_CLOSE", "parameters": "0000", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "020020ED3F4B0000A1A286FD5F", "event_id": "32"}
{"busdata": "020020ED3F4B0000A1A286FD5F", "data": ["0x2", "0x0", "0x20", "0xED", "0x3F", "0x4B", "0x0", "0x0", "0xA1", "0xA2", "0x86", "0xFD", "0x5F"], "valid": true}
{"action": "CALL_CLOSE", "parameters": "0000", "source": "A286FD", "destination": "000000", "type": "OUTDOOR", "busdata": "013020A286FD0000A016", "event_id": "33"}
{"busdata": "013020A286FD0000A016", "data": ["0x1", "0x30", "0x20", "0xA2", "0x86", "0xFD", "0x0", "0x0", "0xA0", "0x16"], "valid": true}

Button ring + no user interaction

{"action": "BUTTON_RING", "parameters": "0360", "source": "A286FD", "destination": "000000", "type": "OUTDOOR", "busdata": "011011A286FD0360A04A", "event_id": "24"}
{"busdata": "011011A286FD0360A04A", "data": ["0x1", "0x10", "0x11", "0xA2", "0x86", "0xFD", "0x3", "0x60", "0xA0", "0x4A"], "valid": true}
{"action": "CALL_ACCEPT_VIDEO", "parameters": "0278", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "022028ED3F4B0278A1A286FD01", "event_id": "25"}
{"busdata": "022028ED3F4B0278A1A286FD01", "data": ["0x2", "0x20", "0x28", "0xED", "0x3F", "0x4B", "0x2", "0x78", "0xA1", "0xA2", "0x86", "0xFD", "0x1"], "valid": true}

# indoor station closes the call after ~30s (time seems to be configurable in the indoor station)
{"action": "CALL_CLOSE", "parameters": "0000", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "020020ED3F4B0000A1A286FD5F", "event_id": "26"}
{"busdata": "020020ED3F4B0000A1A286FD5F", "data": ["0x2", "0x0", "0x20", "0xED", "0x3F", "0x4B", "0x0", "0x0", "0xA1", "0xA2", "0x86", "0xFD", "0x5F"], "valid": true}

# also the outdoor station seems to close the call after a timeout
{"action": "CALL_CLOSE", "parameters": "0000", "source": "A286FD", "destination": "000000", "type": "OUTDOOR", "busdata": "013020A286FD0000A016", "event_id": "27"}
{"busdata": "013020A286FD0000A016", "data": ["0x1", "0x30", "0x20", "0xA2", "0x86", "0xFD", "0x0", "0x0", "0xA0", "0x16"], "valid": true}

View missed call / pressing the "menu" button on the indoor station

When viewing the missed call on the indoor station ("phone" button blinking + pressing it), the following command appears on the bus, although the video stream doesn't start or at least is not visible on the indoor station. It's just showing the picture which is saved on the SD card of the indoor station.
The same happens when pressing the "menu" button on the indoor station (there is no active call, no video showing, just the menu is visible).

{"action": "CALL_ACCEPT_VIDEO", "parameters": "0100", "source": "ED3F4B", "destination": "000000", "type": "INDOOR", "busdata": "013028ED3F4B0100A172", "event_id": "28"}
{"busdata": "013028ED3F4B0100A172", "data": ["0x1", "0x30", "0x28", "0xED", "0x3F", "0x4B", "0x1", "0x0", "0xA1", "0x72"], "valid": true}

Open door without open call

Similar to opening with an active call, but the destination is the controller instead of the outdoor station.

{"action": "OPEN_DOOR", "parameters": "0060", "source": "ED3F4B", "destination": "A25479", "type": "INDOOR", "busdata": "020031ED3F4B0060A1A254791A", "event_id": "11"}
{"busdata": "020031ED3F4B0060A1A254791A", "data": ["0x2", "0x0", "0x31", "0xED", "0x3F", "0x4B", "0x0", "0x60", "0xA1", "0xA2", "0x54", "0x79", "0x1A"], "valid": true}

Activate camera from indoor station (without audio call)

{"action": "CALL_ACCEPT_VIDEO", "parameters": "0278", "source": "ED3F4B", "destination": "A286FD", "type": "INDOOR", "busdata": "022028ED3F4B0278A1A286FD01", "event_id": "6"}
{"busdata": "022028ED3F4B0278A1A286FD01", "data": ["0x2", "0x20", "0x28", "0xED", "0x3F", "0x4B", "0x2", "0x78", "0xA1", "0xA2", "0x86", "0xFD", "0x1"], "valid": true}

Indoor station: "Schalthandlung"

see https://partner.gira.de/data3/12391110.pdf page 17

# Schalthandlung 1: on
{"action": "BUTTON_RING_UNKOWN", "parameters": "4140", "source": "ED3F4B", "destination": "000000", "type": "INDOOR", "busdata": "011042ED3F4B4140A1EC", "event_id": "35"}
{"busdata": "011042ED3F4B4140A1EC", "data": ["0x1", "0x10", "0x42", "0xED", "0x3F", "0x4B", "0x41", "0x40", "0xA1", "0xEC"], "valid": true}

# Schalthandlung 1: off
{"action": "BUTTON_RING_UNKOWN", "parameters": "4150", "source": "ED3F4B", "destination": "000000", "type": "INDOOR", "busdata": "011042ED3F4B4150A1FC", "event_id": "36"}
{"busdata": "011042ED3F4B4150A1FC", "data": ["0x1", "0x10", "0x42", "0xED", "0x3F", "0x4B", "0x41", "0x50", "0xA1", "0xFC"], "valid": true}

# Schalthandlung 2: on
{... "parameters": "4240" }

# Schalthandlung 2: off
{... "parameters": "4250" }

# Schalthandlung 3: on
{... "parameters": "4340" }

# Schalthandlung 3: off
{... "parameters": "4350" }

# Schalthandlung 4: on
{... "parameters": "4440" }

# Schalthandlung 4: off
{... "parameters": "4450" }

Internal calls from the indoor station

see https://partner.gira.de/data3/12391110.pdf page 17

# 1
{"action": "ACTION_UNKOWN", "parameters": "0160", "source": "ED3F4B", "destination": "000000", "type": "INDOOR", "busdata": "011012ED3F4B0160A19C", "event_id": "2"}
{"busdata": "011012ED3F4B0160A19C", "data": ["0x1", "0x10", "0x12", "0xED", "0x3F", "0x4B", "0x1", "0x60", "0xA1", "0x9C"], "valid": true}

# 2
{... "parameters": "0260" }

# 3
{... "parameters": "0360" }

# 4
{... "parameters": "0460" }

# 5
{... "parameters": "0560" }

# 6
{... "parameters": "0660" }

# 7
{... "parameters": "0760" }

# 8
{... "parameters": "0860" }

# 9
{... "parameters": "0960" }

# 10
{... "parameters": "0A60" }