mirror of
https://github.com/jdillenburg/esphome.git
synced 2026-02-18 15:15:55 -07:00
136 lines
3.6 KiB
Markdown
136 lines
3.6 KiB
Markdown
# TFMini-S Time of Flight Distance Sensor for ESPHome
|
|
|
|
This is an external component for ESPHome that supports the TFMini-S time of flight distance sensor. It provides distance measurements along with signal strength and temperature readings from the sensor.
|
|
|
|
## Features
|
|
|
|
- Distance measurement in centimeters or meters (configurable)
|
|
- Signal strength monitoring for reliability assessment
|
|
- Internal temperature monitoring
|
|
- Automatic configuration of the TFMini-S sensor
|
|
- Configurable at 100Hz refresh rate
|
|
|
|
## Installation
|
|
|
|
You can install this component in two ways:
|
|
|
|
### 1. Using ESPHome external components
|
|
|
|
```yaml
|
|
external_components:
|
|
- source: github://jdillenburg/esphome@master
|
|
components: [ tfmini ]
|
|
```
|
|
|
|
### 2. Manual installation
|
|
|
|
Clone this repository into your ESPHome external components directory:
|
|
|
|
```bash
|
|
cd <your config directory>/esphome/external_components
|
|
git clone https://github.com/jdillenburg/esphome.git
|
|
```
|
|
|
|
Or copy the component files directly:
|
|
|
|
```bash
|
|
mkdir -p <your config directory>/esphome/components/tfmini
|
|
cd <your config directory>/esphome/components/tfmini
|
|
wget https://raw.githubusercontent.com/jdillenburg/esphome/main/components/tfmini/__init__.py
|
|
wget https://raw.githubusercontent.com/jdillenburg/esphome/main/components/tfmini/sensor.py
|
|
wget https://raw.githubusercontent.com/jdillenburg/esphome/main/components/tfmini/tfmini.cpp
|
|
wget https://raw.githubusercontent.com/jdillenburg/esphome/main/components/tfmini/tfmini.h
|
|
```
|
|
|
|
Then reference it in your configuration:
|
|
|
|
```yaml
|
|
external_components:
|
|
- source: <your config directory>/esphome/components
|
|
components: [ tfmini ]
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Add the following to your ESPHome configuration file:
|
|
|
|
### Basic Configuration
|
|
|
|
```yaml
|
|
# UART configuration for the TFMini-S
|
|
uart:
|
|
tx_pin: GPIO17
|
|
rx_pin: GPIO16
|
|
baud_rate: 115200
|
|
|
|
# TFMini-S sensor configuration
|
|
sensor:
|
|
- platform: tfmini
|
|
name: "Distance"
|
|
id: tfmini_distance
|
|
```
|
|
|
|
### Full Configuration with All Options
|
|
|
|
```yaml
|
|
# UART configuration for the TFMini-S
|
|
uart:
|
|
tx_pin: GPIO17
|
|
rx_pin: GPIO16
|
|
baud_rate: 115200
|
|
|
|
# TFMini-S sensor configuration with all sensors
|
|
sensor:
|
|
- platform: tfmini
|
|
name: "Distance"
|
|
id: tfmini_distance
|
|
distance_unit: cm # Options: cm (default) or m
|
|
strength:
|
|
name: "TFMini Signal Strength"
|
|
id: tfmini_strength
|
|
temperature:
|
|
name: "TFMini Temperature"
|
|
id: tfmini_temperature
|
|
```
|
|
|
|
## Configuration Options
|
|
|
|
| Option | Default | Description |
|
|
|--------|---------|-------------|
|
|
| `name` | Required | Name of the distance sensor |
|
|
| `distance_unit` | `cm` | Unit for distance measurement. Options: `cm` or `m` |
|
|
| `strength` | Optional | Configuration for signal strength sensor |
|
|
| `temperature` | Optional | Configuration for temperature sensor |
|
|
|
|
## Technical Notes
|
|
|
|
- The sensor is configured to use the standard 9-byte output format
|
|
- Refresh rate is set to 100Hz
|
|
- The component validates signal strength to ensure reliable readings (minimum 100)
|
|
- Default unit is centimeters as that's the native output of the TFMini-S
|
|
|
|
## Wiring
|
|
|
|
Connect your TFMini-S to your ESP device as follows:
|
|
|
|
| TFMini-S | ESP |
|
|
|----------|-----|
|
|
| 5V | 5V |
|
|
| GND | GND |
|
|
| TX | RX (GPIO16 in example) |
|
|
| RX | TX (GPIO17 in example) |
|
|
|
|
## Troubleshooting
|
|
|
|
If you're having issues:
|
|
|
|
1. Check the wiring connections
|
|
2. Ensure the UART pins are correctly defined
|
|
3. Set the logger to DEBUG level to see detailed messages
|
|
4. Verify the sensor has a clear line of sight to the target
|
|
5. Check signal strength values to ensure reliable readings
|
|
|
|
## License
|
|
|
|
This component is licensed under the MIT License.
|