https://github.com/erriez/erriezoregonthn128
Oregon THN128 transmit and receive C library for Arduino
https://github.com/erriez/erriezoregonthn128
433mhz arduino avr diy documentation esp32 esp8266 examples homeassistant library mqtt oregon protocol receive rf temperature thn128 transmit wireless
Last synced: 5 months ago
JSON representation
Oregon THN128 transmit and receive C library for Arduino
- Host: GitHub
- URL: https://github.com/erriez/erriezoregonthn128
- Owner: Erriez
- License: mit
- Created: 2019-10-17T18:48:10.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-01-01T00:56:48.000Z (over 3 years ago)
- Last Synced: 2025-04-06T20:36:12.027Z (about 1 year ago)
- Topics: 433mhz, arduino, avr, diy, documentation, esp32, esp8266, examples, homeassistant, library, mqtt, oregon, protocol, receive, rf, temperature, thn128, transmit, wireless
- Language: C
- Homepage: https://github.com/Erriez/ErriezArduinoLibraries
- Size: 3.42 MB
- Stars: 11
- Watchers: 2
- Forks: 2
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# Oregon THN128 433MHz temperature transmit/receive library for Arduino
This is a 433MHz wireless 3-channel Oregon THN128 temperature transmit/receive Arduino library for ATMega328,
ESP8266 and ESP32 using the (reverse-engineered) Oregon THN128 v1 protocol:
[](https://github.com/Erriez/ErriezOregonTHN128/blob/master/LICENSE)
[](https://github.com/Erriez/ErriezOregonTHN128)
[](https://github.com/Erriez/ErriezOregonTHN128/releases)
[](https://github.com/Erriez/ErriezOregonTHN128/issues)
[](https://github.com/Erriez/ErriezOregonTHN128/actions/workflows/actions.yml)
## Transmit / receive hardware
This Arduino library can be used with low-power ATMega328 microcontroller (AVR architectures like `Arduino UNO` and
`Pro Mini 3.3V 8MHz` boards).
**Temperature transmitter on the left breadboard:**
* Pro-Mini 3V3 8MHz.
* Genuine DS18B20 temperature sensor.
* STX802 low-power 433MHz transmitter.
**Receiver on the right breadboard:**
* SRX882 low-power 433MHz receiver.
* SSD1306 I2C 128x64 OLED display.
* Pro-Mini 3V3 8MHz.
### Supported microcontrollers
* ATMega328 AVR designed for low-power
* ESP8266
* ESP32
* Other microcontrollers are not tested and may or may not work
## Arduino Examples
* [Oregon THN128 Receive](https://github.com/Erriez/ErriezOregonTHN128/blob/master/examples/ErriezOregonTHN128Receive/ErriezOregonTHN128Receive.ino)
* [Oregon THN128 Receive SSD1306 OLED](https://github.com/Erriez/ErriezOregonTHN128/blob/master/examples/ErriezOregonTHN128ReceiveSSD1306/ErriezOregonTHN128ReceiveSSD1306.ino)
* [Oregon THN128 Transmit random temperature](https://github.com/Erriez/ErriezOregonTHN128/blob/master/examples/ErriezOregonTHN128Transmit/ErriezOregonTHN128Transmit.ino)
* [Oregon THN128 Transmit DS1820 1-wire temperature sensor](https://github.com/Erriez/ErriezOregonTHN128/blob/master/examples/ErriezOregonTHN128TransmitDS1820/ErriezOregonTHN128TransmitDS1820.ino)
* [Oregon THN128 ESP32 MQTT Homeassistant](https://github.com/Erriez/ErriezOregonTHN128/blob/master/examples/ESP32/Erriez_Oregon_THN128_ESP32_MQTT_Homeassistant/Erriez_Oregon_THN128_ESP32_MQTT_Homeassistant.ino)
### ESP32 with MQTT and Homeassistant
The [Erriez_Oregon_THN128_ESP32_MQTT_Homeassistant.ino](https://github.com/Erriez/ErriezOregonTHN128/blob/master/examples/ESP32/Erriez_Oregon_THN128_ESP32_MQTT_Homeassistant/Erriez_Oregon_THN128_ESP32_MQTT_Homeassistant.ino) sketch can be used with Homeassistant integration.
Example screenshot Homeassistant dasboard:
Follow the steps below:
1. Configure [Homeassistant MQTT](https://www.home-assistant.io/integrations/mqtt/) in `configuration.yaml`:
```yaml
mqtt:
discovery_prefix: ha
# Enable when using SSL:
# certificate: /ssl/ca.crt
# client_cert: /ssl/client.crt
# client_key: /ssl/client.key
```
2. MQTT broker hostname, username and password should be configured in `Homeassistant | Settings | Devices | MQTT`.
3. Configure the listed macro's in the example, build and run from the Arduino IDE. The following Oregon THN128 entities are automatically registered after a succesful MQTT connection:
- sensor.oregon_thn128_ch1
- sensor.oregon_thn128_ch2
- sensor.oregon_thn128_ch3
- sensor.oregon_thn128_battery
4. Configure Homeassistant dashboard configuration file:
- [Homeassistant Dashboard YAML](extras/HomeassistantDashboard.yaml)
## Hardware Design Notes
Supported hardware:
* AVR designed for low-power
* ESP8266
* ESP32
* For low-power transmitters, a `Pro Mini 3V3 8MHz` bare board with ATMega328 microcontroller is highly recommended. The
board has no serial interface chip which reduces continuous power consumption. An external FTDI232 - USB serial
interface should be connected for serial console / programming. (See red PCB on the picture)
The SMD power LED should be desoldered from the Pro Mini to reduce continuous power consumption.
* A transmitter with (protected) 1500mA 18650 battery can operate for at least 6 months with `LowPower.h` functionality
implemented. (By sending the temperature every 30 seconds)
* Changing the BOD (Brown Out Detection) fuse to 1.8V allows operation between 1.8 and 4.2V 18650 battery. (Explanation
beyond the scope of this project)
* 1 to 3 temperature transmitters are supported, similar to the original Oregon THN128 temperature transmitters.
* Check [list of counterfeit DS18B20 chips](https://github.com/cpetrich/counterfeit_DS18B20) , because this makes a huge
difference in accuracy and read errors at 3.3V. Many DS18B20 chips from Aliexpress are counterfeit and won't work
reliable at voltages below 3.3V.
* [NiceRF Wireless Technology Co., Ltd.](https://nl.aliexpress.com/store/934254) sells high quality 433MHz transmit
(STX802) and receiver modules (STX882) with a good range.
* A 18650 battery (with protection circuit) should be connected directly to the VCC pin (not VIN).
* The voltage regulator can be desoldered from the pro-micro board when not used for more power reduction.
## Oregon Protocol
A packet is sent twice:
Data (see header file [ErriezOregonTHN128Receive.h](https://github.com/Erriez/ErriezOregonTHN128/blob/master/src/ErriezOregonTHN128Receive.h)):
* Byte 0:
* Bit 0..3: Rolling address (Random value after power cycle)
* Bit 6..7: Channel: (0 = channel 1 .. 2 = channel 3)
* Byte 1:
* Bit 0..3: TH3
* Bit 4..7: TH2
* Byte 2:
* Bit 0..3: TH1
* Bit 5: Sign
* Bit 7: Low battery
* Byte 3:
* Bit 0..7: CRC
## Library Changes
### v1.1.0
The callback function `void delay100ms()` has been removed as this was not compatible with ESP32. The application should
change the code to:
```c++
// Send temperature twice with 100ms delay between packets
OregonTHN128_Transmit(&data);
delay(100);
OregonTHN128_Transmit(&data);
```
AVR targets can replace `delay(100)` with LowPower usage:
```c++
LowPower.powerDown(SLEEP_15MS, ADC_OFF, BOD_OFF);
LowPower.powerDown(SLEEP_60MS, ADC_OFF, BOD_OFF);
LowPower.powerDown(SLEEP_15MS, ADC_OFF, BOD_OFF);
```
## Saleae Logic Analyzer
[capture](extras/SaleaeLogicAnalyzer/RX_rol7_channel1_temp20.7_lowbat0.sal) from the Oregon THN128 can be opened with
https://www.saleae.com/downloads/.
## Generated Arduino Library Doxygen Documentation
* [Online Doxygen HTML](https://erriez.github.io/ErriezOregonTHN128/index.html)
* [Doxygen PDF](https://github.com/Erriez/ErriezOregonTHN128/blob/gh-pages/ErriezOregonTHN128.pdf)
## MIT License
This project is published under [MIT license](https://github.com/Erriez/ErriezOregonTHN128/blob/master/LICENSE)
with an additional end user agreement (next section).
## End User Agreement :ukraine:
End users shall accept the [End User Agreement](https://github.com/Erriez/ErriezOregonTHN128/blob/master/END_USER_AGREEMENT.md)
holding export restrictions to Russia to stop the WAR before using this project.