TC:BUS Component tc_bus

The TC:BUS Component for ESPHome allows you to interface with TCS:Bus or Koch TC:Bus intercom systems, providing automation, monitoring, and interaction capabilities within the ESPHome ecosystem.

This component can trigger automations based on specific telegrams received from the intercom system, send telegrams to the intercom, and receive various status updates (e.g., bus telegrams and door readiness). Actions can also be configured to respond to particular telegrams from the intercom.

NOTE

This is the only component required for communication on the bus. However, it can be extended with additional components, such as TC:BUS Device and TC:BUS Serial.

Note: This component requires hardware like the Doorman-S3 or a DIY solution to communicate on the bus.

Configuration

The tc_bus hub serves as the central component enabling bus communication. It provides the following configuration options:

Option	Description	Required	Default
id	Unique ID for the component.	Yes
receiver_id	ID of remote_receiver for receiving data from the TC:BUS.	No	The configured remote_receiver
transmitter_id	ID of remote_transmitter for transmitting data to the TC:BUS. Should be connected to the transistor.	No	The configured remote_receiver
on_telegram	Defines actions to be triggered when a telegram is received from the TC:BUS. Returns a TelegramData struct as the x variable.	No

Text Sensors

The tc_bus Text Sensor component offers the following configuration options:

Option	Description	Required	Default
bus_telegram	Displays the most recently received bus telegram, showing the full communication traffic from all connected devices.	No

Binary Sensors

The tc_bus Binary Sensor detects binary states such as doorbell presses. It can be configured to trigger based on a predefined telegram.

Option	Description	Required	Default
id	Unique ID for the binary sensor component.	Yes
icon	Icon to represent the sensor in the UI.	No	mdi:doorbell
name	Name of the binary sensor.	No	Doorbell
auto_off	Time period after which the sensor automatically turns off, useful for momentary signals like doorbell presses.	No	3s
telegram	A specific 32-bit hexadecimal telegram that triggers the binary sensor when received from the TC:BUS.	Yes	0
type	Telegram type that will trigger the binary sensor, used alongside address, payload and serial_number. Cannot be used with telegram.	Yes	unknown
address	8-bit address that serves as a condition to trigger the binary sensor. If you set it to 255, it will catch all addresses.	No	0
payload	32-bit payload that serves as a condition to trigger the binary sensor.	No	0
serial_number	Specific device serial number that serves as a condition to trigger the binary sensor. If you set it to 255, it will catch all serial numbers.	No	unknown

INFO

You can use either telegram or a combination of type, address, payload, and serial_number, but not both simultaneously.
This ensures the binary sensor triggers either through a specific telegram or a combination of parameters, preventing conflicts.

Locks

The tc_bus Lock platform can be configured to trigger based on a predefined outdoor station.

Option	Description	Required	Default
id	Unique ID for the lock component.	Yes
icon	Icon to represent the lock in the UI.	No	mdi:door
name	Name of the lock.	No	Entrance Door
auto_lock	Time period after which the lock resets the virtual state to locked.	No	5s
address	8-bit address that serves as a condition to trigger the lock. If you set it to 255, it will catch all addresses.	No	0
before_unlock_action	Defines actions to be triggered before the open_door telegram is sent.	No
after_unlock_action	Defines actions to be triggered after the open_door telegram is sent.	No
lock_action	Defines actions to be triggered when the lock state is changed back to locked.	No

Callbacks

Received Telegram on_telegram

This callback allows you to utilize the TelegramData struct, accessible as the x variable.

on_telegram:
  - lambda: |-
      ESP_LOGD("TAG", "Received Telegram Type: %s", telegram_type_to_string(x.type));

      if (x.type == TELEGRAM_TYPE_OPEN_DOOR) {
        ESP_LOGD("TAG", "Opened Door of outdoor station %i", x.address);
      }

Actions

Set Programming Mode tc_bus.set_programming_mode

This action allows you to enable or disable the programming mode of the control unit.

on_...:
  - tc_bus.set_programming_mode:
      programming_mode: true

Sending Telegrams tc_bus.send

You can send telegrams on the bus using this action.

Note

You can either use the telegram field to send a specific telegram or use the type, address, payload, and serial_number fields to create a more complex message. Both cannot be used at the same time.

You can explicitly send a 32-bit telegram by using the optional is_long property, which is useful when the telegram begins with leading zeros.

Telegram Builder

on_...:
  - tc_bus.send:
      type: open_door
      address: 0
      payload: 0
      serial_number: 123456

Raw Telegram

on_...:
  - tc_bus.send:
      telegram: 0x1A2B3C4D

Raw Telegram (fixed size)

on_...:
  - tc_bus.send:
      telegram: 0x00000280
      is_long: True

Example YAML Configuration

This is an example configuration for the component in ESPHome:

external_components:
  - source: github://azoninc/doorman@dev
    components: [ tc_bus ]

## RMT configuration
remote_receiver:
  pin:
    number: GPIO9
    mode: INPUT
  filter: 1500us
  idle: 7000us

remote_transmitter:
  pin:
    number: GPIO8
    mode: OUTPUT
  carrier_duty_percent: 100%

# TC:BUS configuration
tc_bus:
  id: my_tc_bus
  on_telegram:
    - logger.log: "Received telegram from bus!"

# Outdoor Stations - Doors
lock:
  - platform: tc_bus
    id: entrance_door_lock
    name: "Entrance Door"
    auto_lock: 5s
    address: 0
    before_unlock_action:
      - logger.log: "Before Unlock Action Triggered"
    after_unlock_action:
      - logger.log: "After Unlock Action Triggered"
    lock_action:
      - logger.log: "Lock Action Triggered"

text_sensor:
  - platform: tc_bus
    tc_bus_id: my_tc_bus
    bus_telegram:
      name: "Last Bus Telegram"

# Binary sensor for doorbell press
binary_sensor:
  - platform: tc_bus
    id: doorbell_sensor_raw
    name: "Outdoor Station Doorbell (raw)"
    icon: "mdi:doorbell"
    telegram: 0x0C30BA80
    auto_off: 2s

  - platform: tc_bus
    id: doorbell_sensor_parser
    name: "Outdoor Station Doorbell (parser)"
    icon: "mdi:doorbell"
    type: door_call
    auto_off: 2s

  - platform: tc_bus
    id: doorbell_sensor_new_other
    name: "Outdoor Station Doorbell of other serial number (parser)"
    icon: "mdi:doorbell"
    type: door_call
    serial_number: 123456

  - platform: tc_bus
    id: door_opener_sensor
    name: "Someone opened the door of outdoor station 0"
    icon: "mdi:door"
    type: open_door
    address: 0
    serial_number: 255 # 255 is used to catch all

# Sending telegrams
button:
  - platform: template
    name: "Open Door (raw)"
    on_press:
      - tc_bus.send:
          telegram: 0x1100

  - platform: template
    name: "Open Door (builder)"
    on_press:
      - tc_bus.send:
          type: open_door
          address: 0

Telegram Data

The TelegramData struct is used internally and can also be used in the on_telegram.

struct TelegramData {
    uint32_t raw;
    char hex[9];

    TelegramType type;
    uint8_t address;
    uint32_t serial_number;
    uint32_t payload;
    
    bool is_long;
    bool is_response;
    bool is_data;
};

Telegram Types

You can use telegram types in binary sensors and also when sending telegrams:

• door_call TELEGRAM_TYPE_DOOR_CALL
• floor_call TELEGRAM_TYPE_FLOOR_CALL
• internal_call TELEGRAM_TYPE_INTERNAL_CALL
• control_function TELEGRAM_TYPE_CONTROL_FUNCTION
• start_talking_door_call TELEGRAM_TYPE_START_TALKING_DOOR_CALL
• start_talking TELEGRAM_TYPE_START_TALKING
• stop_talking_door_call TELEGRAM_TYPE_STOP_TALKING_DOOR_CALL
• stop_talking TELEGRAM_TYPE_STOP_TALKING
• open_door TELEGRAM_TYPE_OPEN_DOOR
• open_door_long TELEGRAM_TYPE_OPEN_DOOR_LONG
• light TELEGRAM_TYPE_LIGHT
• door_opened TELEGRAM_TYPE_DOOR_OPENED
• door_closed TELEGRAM_TYPE_DOOR_CLOSED
• end_of_ringtone TELEGRAM_TYPE_END_OF_RINGTONE
• end_of_door_readiness TELEGRAM_TYPE_END_OF_DOOR_READINESS
• initialize_door_station TELEGRAM_TYPE_INITIALIZE_DOOR_STATION
• reset TELEGRAM_TYPE_RESET
• select_device_group TELEGRAM_TYPE_SELECT_DEVICE_GROUP
• select_device_group_reset TELEGRAM_TYPE_SELECT_DEVICE_GROUP_RESET
• search_devices TELEGRAM_TYPE_SEARCH_DEVICES
• found_device TELEGRAM_TYPE_FOUND_DEVICE
• found_device_subsystem TELEGRAM_TYPE_FOUND_DEVICE_SUBSYSTEM
• programming_mode TELEGRAM_TYPE_PROGRAMMING_MODE
• read_memory_block TELEGRAM_TYPE_READ_MEMORY_BLOCK
• select_memory_page TELEGRAM_TYPE_SELECT_MEMORY_PAGE
• write_memory TELEGRAM_TYPE_WRITE_MEMORY
• request_version TELEGRAM_TYPE_REQUEST_VERSION