This repository contains both the hardware (kicad & production files) for an ESP32 module as well as an ESPHome component to control Toshiba / Carrier RAS HVAC units independently from the Toshiba Cloud.
ESP8266 is also supported but requires custom wiring.
The device can be used as a local, low cost drop in replacement to control the AC from Home Assistant or others.
Features of the component:
- All operation modes & fan modes supported
- Does not depend on external vendor cloud services
- External temperature sensor support for accurate temperature regulation (external sensor entity configurable)
- Wired and IR remotes still work, even with external temperature sensor
- Supports most special modes / merit modes like silent, fireplace, extended heating temperature range
- Support for power modes on single split units and ionizer toggle
- Additional information like fan speeds, compressor load, refrigerant / pipe temperatures
- WiFi LED toggle (on/off via UART registers 0xDE/0xDF)
Missing functionality:
- Manual defrost (probably unsupported over UART WIFI interface)
- ODU error messages (not decoded yet)
- Timer / schedules (had no interest in this functionality)
- Capability detection (all fan & merit modes will be shown, but not all might have an effect depending on the IDU)
Requirements:
- Toshiba/Carrier RAS single- or multisplit unit with built-in WIFI interface or WIFI module support (others might work as well, but untested)
- ESP32 DevKit 38 Pins (others like NodeMCU 8266 work as well but might require modifications)
- Toshiba HVAC module (see
hardware/directory) - ESPhome installed to flash the ESP32 initially
The IDU communicates over 5V UART 9600E1.
Messages include a length and a distinct header. Initial synchronization is ensured with a 200ms message timeout.
The protocol is relatively simple and can be observed in the process_uart_rx and handle_message functions, where the message type is identified by its length.
I've decoded most of the protocol by reading the communication with stock WRE-T00BJ10 modules and analyzing the messages against known responses from the Toshiba Cloud.
We can request registers from the IDU, we can write certain registers and also the IDU will send registers if updated externally (IDU / ODU status and changes via IR remote).
Probably all Toshiba RAS units with wifi capabilities (built-in or with additional module) are supported.
The software has been tested with the following outdoor units:
- RAS-3M18U2AVG-E (Tripe-split)
- RAS-2M14U2AVG-E (Dual-split)
- RAS-25G2KVP-ND (Single-split) And these indoor units:
- RAS-B10N4KVRG-E (Haori)
- RAS-25G2AVP-ND (Super DAISEIKAI 8)
Other units (with any compatible outdoor unit) that are almost certainly supported:
- Toshiba Seiya
- Toshiba Shorai
- Rebranded models like Carrier X Inverter
The hardware needs three main components:
- Microcontroller. Any ESP32-DevKit with 38 Pins should work. ESP8266 is also supported, see "ESP8266" below.
- Bidirectional Voltage Level Translator. This is needed to connect to the UART interface and shift between 5V from the AC to 3.3V of the ESP32. I used a
Texas Instruments TXS0108EPWR. - Connector Toshiba uses as JST PASK connector for the WIFI modules cable,
JST S05B-PASK-2(LF)(SN)is the correct connector.
External voltage regulators are not required, as the UART inteface in the indoor units works at 5V and can be directly fed into the ESP32 DevKit.
The Kicad 7 project files and ready-to-use production files (for JLCPCB or PcbWay manufacturing) are available in hardware/ and hardware/production respectively.
Attention: The Haori units with built-in WIFI modules lack height for the 2x 19p 2.54mm pin sockets. I disabled placement for the pin sockets and soldered the ESP32 on the modules:
This depends on the indoor unit. The following photos from a Toshiba Haori show how the built-in module can be replaced in a few minutes:
The toshiba_controller/ directory contains an external_components-based component compatible with ESPHome 2024.x and later. The legacy platform: custom approach no longer compiles on current ESPHome versions.
To use the component:
- Clone this repository and navigate to the
esphomedirectory. - Install ESPHome: https://esphome.io/guides/installing_esphome.html
- Copy
template_v3.yamlto (for example)toshiba-livingroom.yamland fill in your WiFi credentials, API key, and temperature sensor entity ID. - Connect the ESP32 module via USB (first flash only; subsequent updates use OTA).
- Run
esphome run toshiba-livingroom.yaml. - Add the device in Home Assistant (Settings → Devices & Services).
If you are upgrading from the old base.yaml include with platform: custom, the main changes are:
- Remove the
<<: !include base.yamlline and theincludes: [toshiba-controller.h]reference. - Add
external_componentspointing to thetoshiba_controller/directory (seetemplate_v3.yaml). - Replace the
climate: platform: customblock with a top-leveltoshiba_controller:block. - Replace
sensor: platform: customwithsensor: platform: toshiba_controller(sensor names are preserved). - Replace
switch: platform: customwithswitch: platform: toshiba_controllerfor Internal Thermistor and Ionizer. - Split the Special Mode select into three separate selects: Special Mode, Silent Mode, and Fireplace (the old config had all modes in a single flat list).
- Optionally add the new WiFi LED template switch.
See template_v3.yaml for a complete example of the new configuration format.
If you are still on an older ESPHome version, use template.yaml with the single-file toshiba-controller.h from an older release. Note that platform: custom has been removed in ESPHome 2024.
esphome logs toshiba-livingroom.yamlESP8266 is supported but requires custom wiring. Use template_v3.yaml as a starting point and adjust the board, UART pins (GPIO1 TX / GPIO3 RX), and framework accordingly.
A bidirectional logic level converter must be connected to the UART pins.
The NodeMCU can be powered directly from the indoor unit's UART connector 5V Pin 3 through VIN.
If the binary switch Internal Thermistor is disabled in Home Assistant, the external temperature sensor supplied in the yaml configuration will be used for the room temperature.
Most ACs suffer from poor thermistor placement (high position, heat draft) and Toshiba does not support external thermistors over UART.
This requires a more complex regulation in the smart_thermostat_control function which can be fine tuned with the smart_thermostat_multiplier config parameter.
A recommended value is 4, which results in a regulation accuracy of around +/- 0.25°K.
Higher values increase the accuracy at the cost of more compressor cycles.
The parameters cduIac and cduLoad seem off at first however, the values are identical to Toshiba's own parameters.
The cduLoad is internally called cduCompHz by Toshiba and has a range from 0-170.
Since the value has an identical range regardless of the compressor, does not match the actual compressor frequency and is independant for each indoor unit, I converted the number to a percentage which correlates well with the requested power for the IDU.
The same is true for cduIac which is closely following cduLoad.
My best guess is that cduLoad is the heat request for the IDU and cduIac is related to the IDU's EEV.
- Inspiration & initial protocol description from ToshibaCarrierHvac
- ESPhome component structure from esphome-lg-controller
This project is released under the MIT License.