diff --git a/docs/.vitepress/config/de.mts b/docs/.vitepress/config/de.mts index b3344c5..156c4c0 100644 --- a/docs/.vitepress/config/de.mts +++ b/docs/.vitepress/config/de.mts @@ -78,6 +78,7 @@ function nav(): DefaultTheme.NavItem[] { text: pkg.version, items: [ { text: 'Issues', link: 'https://github.com/AzonInc/Doorman/issues' }, + { text: 'Changelog', link: 'changelog' }, { text: 'Docs', items: [ diff --git a/docs/.vitepress/config/en.mts b/docs/.vitepress/config/en.mts index 5aa1df1..0806c90 100644 --- a/docs/.vitepress/config/en.mts +++ b/docs/.vitepress/config/en.mts @@ -51,6 +51,7 @@ function nav(): DefaultTheme.NavItem[] { text: pkg.version, items: [ { text: 'Issues', link: 'https://github.com/AzonInc/Doorman/issues' }, + { text: 'Changelog', link: 'changelog' }, { text: 'Docs', items: [ diff --git a/docs/en/changelog.md b/docs/en/changelog.md new file mode 100644 index 0000000..9d352bd --- /dev/null +++ b/docs/en/changelog.md @@ -0,0 +1,81 @@ +# Changelog + +## 2024.10.0 +### πŸš€ What's new? +- **TC:BUS Protocol Support**: Take a look at the [supported commands](reference/esphome-component#command-types). + - Introducing intuitive command types with parameters like `address`, `payload`, and `serial_number`. +- **Interactive Setup Enhancements**: During initial setup, the system now saves the serial number of the indoor station, while also automatically detecting the address of a second outdoor station. +- **Expanded Functionality**: The doorbell and phone pickup patterns now work for a second entrance. +- **New Memory Management Tools**: + - You can now modify ringtones and adjust volumes on indoor stations. + - Currently supports TCS ISH/ISW3030 models. For other models, memory must be analyzed and implemented. +- **Programming Mode Actions**: Simply toggle the control units programming mode via ESPHome. + +### ✨ Improvements +- **Entity Grouping**: On the webserver, entities are now better grouped for easier navigation and control. +- **Simplified ESPHome Configuration**: The configuration is now divided into separate add-ons, making it more modular and easier to manage. + +### πŸ“ Other Updates +- The `tcs_intercom` component is now called `tc_bus`, with all documentation now centralized in this repository. + +### ⛑️ BREAKING CHANGES +- **Re-setup Required**: Due to the new protocol implementation based on serial numbers, existing stored commands will no longer work. You'll need to reconfigure by pressing the apartment or entrance doorbell. [See detailed setup guide](guide/getting-started#step-3-interactive-setup). +- **Simplified Service Names**: We’ve made changes to the Home Assistant service names to make them easier to understand and use: + + - **Old Format**: + ```yaml + service: esphome.doorman_s3_send_tcs_command + data: + command: 0x1C30BA41 + ``` + + - **New Format**: + ```yaml + service: esphome.doorman_s3_send_tc_command_raw + data: + command: 0x1C30BA41 + ``` + This keeps the original command format but uses a more consistent name (`tc_command_raw`). + + - **New Simplified Option**: For most cases, you can now use the easier, more descriptive command structure: + ```yaml + service: esphome.doorman_s3_send_tc_command + data: + type: floor_call # Command type (e.g., 'floor_call', 'door_open') + address: 0 # Address, for example the Outdoor Station + payload: 0 # Data payload + serial_number: 0 # Indoor Station serial number + ``` + This format is more readable and helps you specify the type of command directly, making it much easier to manage. + +## 2024.8.5 +### πŸš€ What's new? +- The Interactive Setup process now allows for seamless capture and storage of bus commands. It will start automatically the first time you use the firmware, provided you haven't configured commands previously. + +### ✨ Improvements +- Resolved issue with dashboard import file names. +- Status colors have been enhanced for better visibility and clarity. + +### πŸ“ Other Updates +- Use the [tcs_intercom]() development branch for development builds. + +## 2024.8.3 +### πŸš€ What's new? +- Simplified initial setup via Access Point, Improv Serial, or Improv BLE +- [Runtime configuration]() for bus commands and various settings +- [Pattern Event]() entites (e.g., entrance/apartment doorbell, lift handset) +- Enhanced [Ring To Open]() (Party Mode 2.0) with customizable timeout settings +- Introduced a Door Opener Button for your secondary door (if applicable) +- Added a button to activate the hallway light (if applicable) +- New HTTP OTA Update Option for seamless upgrades to the latest stable Doorman release via Home Assistant (without ESPHome Dashboard) + +### ✨ Improvements +- Install or Update the [Stock Firmware]() directly from the documentation page. You no longer need to compile the firmware using the ESPHome Dashboard if you’re just setting up commands. +- Several additional minor improvements + +### πŸ“ Other Updates +- Enable Webserver +- Set the minimum required ESPHome version to `2024.8.0` + +### ⛑️ BREAKING CHANGES +This version will reset your existing saved commands. You will need to reconfigure them using the new configuration input entities. \ No newline at end of file diff --git a/docs/en/reference/esphome-component.md b/docs/en/reference/esphome-component.md index d723478..dd1951a 100644 --- a/docs/en/reference/esphome-component.md +++ b/docs/en/reference/esphome-component.md @@ -8,6 +8,7 @@ It also supports sending commands to the intercom and receiving various status u This component requires hardware like the Doorman-S3 or a [DIY solution](https://github.com/peteh/doorman) in order to communicate on the bus. ::: + ## Configuration Options ### TC:BUS Hub @@ -53,7 +54,9 @@ You can use **either** `command`/`command_lambda` **or** a combination of `type` This ensures the binary sensor triggers either through a specific command or a combination of parameters, preventing conflicts. ::: -## Callback + +## Callbacks +### Received Command The `on_command` callback of the `tc_bus` hub allows you to utilize the [CommandData](#command-data) structure, accessible as the `x` variable. ```yaml @@ -66,7 +69,58 @@ on_command: } ``` -## Sending Commands +### Read Memory Complete +The `on_read_memory_complete` callback of the `tc_bus` hub allows you to work with the memory buffer, accessible as the `x` variable. + +```yaml +on_read_memory_complete: + - logger.log: "Completed memory reading!" + - lambda: |- + std::string hexString = str_upper_case(format_hex(x)); + ESP_LOGI("tcs_bus", "Memory Dump: %s", hexString.c_str()); +``` + +### Read Memory Timeout +The `on_read_memory_timeout` callback of the `tc_bus` hub allows you to detect a failed memory reading. Most probably when a model doesn't support the related commands. + +```yaml +on_read_memory_timeout: + - logger.log: "Failed to read Memory" +``` + + +## Actions +### Read Memory +The `tc_bus.read_memory` action allows you to read the memory of any indoor station using the serial number. + +```yaml +on_...: + - tc_bus.read_memory: + serial_number: 123456 +``` + +### Set Programming Mode +The `tc_bus.set_programming_mode` action allows you to enable or disable the programming mode of the control unit. + +```yaml +on_...: + - tc_bus.set_programming_mode: + programming_mode: true +``` + +### Update Setting +The `tc_bus.update_setting` action allows you to change the supported settings of any indoor station. +Take a look at the [supported models and settings](#model-setting-availability). + +```yaml +on_...: + - tc_bus.update_setting: + type: volume_ringtone + value: 7 + serial_number: 123456 +``` + +### Sending Commands You can send commands on the bus using the `tc_bus.send` action. @@ -106,6 +160,7 @@ on_...: command: 0x2100 ``` + ## Event Handling If the `event` parameter is set (and not `none`), an event is generated each time a command is received. You can monitor these events in Home Assistant on the [developer tools](https://my.home-assistant.io/redirect/developer_events/) page. @@ -148,6 +203,7 @@ event_data: Be sure to modify the command and event name as needed based on your configuration. + ## Example YAML Configuration Here is an example configuration for the TCS Intercom component in ESPHome: @@ -220,6 +276,7 @@ button: address: 0 ``` + ## Advanced Configuration ### Using Lambda for Serial Number @@ -231,6 +288,28 @@ tc_bus: return 123456; ``` +### Accessing intercom settings +If you need to access the supported settings in the memory buffer you can use the `get_setting` method of the `tc_bus` hub. + +Example (read and write setting): +```yaml +number: + - platform: template + id: intercom_volume_handset + name: "Volume: Handset" + icon: "mdi:volume-high" + min_value: 0 + max_value: 7 + step: 1 + mode: slider + lambda: !lambda "return id(tc_bus_intercom)->get_setting(SETTING_VOLUME_HANDSET);" + update_interval: 1s + set_action: + - tc_bus.update_setting: + type: volume_handset + value: !lambda "return x;" +``` + ## Command Data The `CommandData` structure is used internally and can also be used in the `on_command`. @@ -246,6 +325,7 @@ struct CommandData { }; ``` + ## Command Types You can use command types in binary sensors and also when [sending commands](#sending-commands): @@ -276,6 +356,7 @@ You can use command types in binary sensors and also when [sending commands](#se - write_memory - request_version + ## Setting Types Here are the available setting types you can use to update the settings of your intercom phone: @@ -285,6 +366,7 @@ Here are the available setting types you can use to update the settings of your - volume_ringtone - volume_handset + ## Model Setting availability Here are the available settings for specific intercom phone models: