Skip to content

Commit bb80842

Browse files
Bre77Bre77
committed
Add docs
1 parent 6de115b commit bb80842

File tree

4 files changed

+949
-0
lines changed

4 files changed

+949
-0
lines changed

‎EXAMPLES_README.md‎

Lines changed: 273 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,273 @@
1+
# Teslemetry Stream Examples
2+
3+
This directory contains example scripts demonstrating how to use the `teslemetry-stream` library to connect to Tesla telemetry data and add custom fields for monitoring.
4+
5+
## Prerequisites
6+
7+
1. **Teslemetry Account**: Sign up at [teslemetry.com](https://teslemetry.com)
8+
2. **Access Token**: Get your access token from the [Teslemetry Console](https://teslemetry.com/console)
9+
3. **Vehicle VIN**: Your Tesla vehicle's VIN number
10+
4. **Python Dependencies**: Install the required packages:
11+
```bash
12+
pip install teslemetry-stream aiohttp
13+
```
14+
15+
## Example Scripts
16+
17+
### 1. `simple_field_example.py` - Basic Field Addition
18+
19+
**Purpose**: Demonstrates the fundamental pattern for adding telemetry fields and listening to data.
20+
21+
**What it shows**:
22+
- Connecting to the Teslemetry Stream service
23+
- Adding basic telemetry fields (battery level, speed, charge state)
24+
- Setting up a simple event handler
25+
- Adding custom fields to incoming data
26+
27+
**Usage**:
28+
```bash
29+
# Edit the file to add your ACCESS_TOKEN and VIN
30+
python simple_field_example.py
31+
```
32+
33+
**Key concepts**:
34+
- Using `vehicle.add_field()` to subscribe to specific telemetry signals
35+
- Setting custom intervals for different fields
36+
- Processing incoming telemetry events
37+
- Adding computed fields to the data stream
38+
39+
### 2. `example_add_field.py` - Comprehensive Field Management
40+
41+
**Purpose**: Shows a complete implementation with multiple field types, event handlers, and custom processing.
42+
43+
**What it shows**:
44+
- Adding multiple fields with different monitoring intervals
45+
- Using typed listener methods for specific signals
46+
- Creating custom event handlers for different data types
47+
- Implementing custom field derivation and alerts
48+
- Proper resource cleanup and error handling
49+
50+
**Features demonstrated**:
51+
- Battery level monitoring with low battery alerts
52+
- Vehicle speed tracking
53+
- Location monitoring
54+
- Charge state management
55+
- Custom field generation (data freshness, charging recommendations)
56+
57+
**Usage**:
58+
```bash
59+
# Update configuration section with your credentials
60+
python example_add_field.py
61+
```
62+
63+
### 3. `advanced_field_example.py` - Advanced Data Processing
64+
65+
**Purpose**: Demonstrates sophisticated telemetry processing with dynamic field management and data enrichment.
66+
67+
**What it shows**:
68+
- Dynamic field addition and interval updates during runtime
69+
- Advanced data processing with the `TelemetryProcessor` class
70+
- Historical data tracking and trend analysis
71+
- Alert generation based on multiple conditions
72+
- Event statistics and monitoring
73+
- Field configuration management
74+
75+
**Advanced features**:
76+
- Battery change rate calculation
77+
- Location zone determination
78+
- Climate efficiency assessment
79+
- Energy efficiency categorization
80+
- Multi-field derived metrics
81+
- Real-time alert system
82+
83+
**Usage**:
84+
```bash
85+
# Configure ACCESS_TOKEN and VIN in the script
86+
python advanced_field_example.py
87+
```
88+
89+
## Configuration
90+
91+
Before running any example, update these variables in the scripts:
92+
93+
```python
94+
ACCESS_TOKEN = "your_teslemetry_access_token_here"
95+
VIN = "your_vehicle_vin_here"
96+
SERVER = "api.teslemetry.com" # or your regional server
97+
```
98+
99+
### Regional Servers
100+
101+
Choose the appropriate server based on your location:
102+
- `api.teslemetry.com` - Global (recommended)
103+
- `na.teslemetry.com` - North America
104+
- `eu.teslemetry.com` - Europe
105+
106+
## Available Telemetry Fields
107+
108+
The library supports numerous telemetry fields defined in the `Signal` enum. Common fields include:
109+
110+
### Battery & Charging
111+
- `BATTERY_LEVEL` - Battery percentage
112+
- `CHARGE_STATE` - Charging status
113+
- `CHARGE_AMPS` - Charging current
114+
- `CHARGER_VOLTAGE` - Charger voltage
115+
- `TIME_TO_FULL_CHARGE` - Estimated time to full charge
116+
117+
### Vehicle Movement
118+
- `VEHICLE_SPEED` - Current speed
119+
- `LOCATION` - GPS coordinates
120+
- `ODOMETER` - Total distance traveled
121+
- `GEAR` - Current gear selection
122+
123+
### Climate Control
124+
- `INSIDE_TEMP` - Cabin temperature
125+
- `OUTSIDE_TEMP` - Ambient temperature
126+
- `HVAC_POWER` - Climate system status
127+
- `HVAC_FAN_SPEED` - Fan speed setting
128+
129+
### Vehicle State
130+
- `DOOR_STATE` - Door open/closed status
131+
- `LOCKED` - Vehicle lock state
132+
- `SENTRY_MODE` - Sentry mode status
133+
- `CENTER_DISPLAY` - Display state
134+
135+
### Complete Field List
136+
137+
For a complete list of available fields, see:
138+
- The `Signal` enum in `teslemetry_stream/const.py`
139+
- [Teslemetry Fields API](https://api.teslemetry.com/fields.json)
140+
141+
## Field Management Patterns
142+
143+
### Adding Fields with Intervals
144+
145+
```python
146+
# Add field with 30-second updates
147+
await vehicle.add_field(Signal.BATTERY_LEVEL, interval=30)
148+
149+
# Add field with default interval
150+
await vehicle.add_field(Signal.CHARGE_STATE)
151+
```
152+
153+
### Using Typed Listeners
154+
155+
```python
156+
# Set up typed listeners for specific fields
157+
def battery_handler(battery_level):
158+
print(f"Battery: {battery_level}%")
159+
160+
remove_listener = vehicle.listen_BatteryLevel(battery_handler)
161+
```
162+
163+
### Generic Event Handling
164+
165+
```python
166+
# Handle all telemetry events
167+
def handle_all_data(event):
168+
if "data" in event:
169+
data = event["data"]
170+
# Process any fields present in the data
171+
172+
remove_listener = stream.async_add_listener(handle_all_data)
173+
```
174+
175+
## Custom Field Addition
176+
177+
All examples demonstrate adding custom fields to the telemetry data:
178+
179+
### Simple Custom Fields
180+
```python
181+
# Add computed status field
182+
if "BatteryLevel" in data:
183+
if data["BatteryLevel"] > 80:
184+
data["battery_status"] = "high"
185+
elif data["BatteryLevel"] > 20:
186+
data["battery_status"] = "medium"
187+
else:
188+
data["battery_status"] = "low"
189+
```
190+
191+
### Advanced Custom Fields
192+
```python
193+
# Add time-based fields
194+
data["processed_at"] = datetime.now().isoformat()
195+
196+
# Add multi-field derivatives
197+
if "BatteryLevel" in data and "ChargeState" in data:
198+
data["needs_charging"] = (
199+
data["ChargeState"] != "Charging" and data["BatteryLevel"] < 30
200+
)
201+
```
202+
203+
## Error Handling
204+
205+
The examples include proper error handling patterns:
206+
207+
```python
208+
try:
209+
async with stream: # Auto-connect and cleanup
210+
# Your telemetry processing code
211+
await asyncio.sleep(duration)
212+
except Exception as e:
213+
logger.error(f"Telemetry error: {e}")
214+
finally:
215+
# Cleanup listeners
216+
remove_listener()
217+
```
218+
219+
## Best Practices
220+
221+
1. **Use appropriate intervals**: Don't request data more frequently than needed
222+
2. **Handle reconnections**: The library handles reconnections automatically
223+
3. **Clean up listeners**: Always remove listeners when done
224+
4. **Process data efficiently**: Avoid blocking operations in event handlers
225+
5. **Monitor rate limits**: Be aware of API rate limiting
226+
6. **Use typed listeners**: Prefer typed listeners for better error handling
227+
7. **Log appropriately**: Use structured logging for debugging and monitoring
228+
229+
## Troubleshooting
230+
231+
### Common Issues
232+
233+
1. **Authentication Error**: Verify your access token is correct and active
234+
2. **VIN Not Found**: Ensure the VIN is correct and associated with your account
235+
3. **Connection Timeout**: Check network connectivity and server selection
236+
4. **No Data Received**: Verify the vehicle is online and telemetry is enabled
237+
238+
### Debug Logging
239+
240+
Enable debug logging to see detailed connection information:
241+
242+
```python
243+
import logging
244+
logging.basicConfig(level=logging.DEBUG)
245+
```
246+
247+
### Rate Limiting
248+
249+
If you encounter rate limiting:
250+
- Increase field intervals
251+
- Reduce the number of concurrent fields
252+
- Contact Teslemetry support for higher limits
253+
254+
## Next Steps
255+
256+
After running these examples:
257+
258+
1. **Customize field selection**: Choose only the fields you need for your application
259+
2. **Implement data persistence**: Store telemetry data in a database
260+
3. **Create dashboards**: Visualize the telemetry data
261+
4. **Set up alerts**: Create automated alerts for important conditions
262+
5. **Integrate with other services**: Send data to cloud services or home automation systems
263+
264+
## Support
265+
266+
- **Library Documentation**: See the main README.md
267+
- **Teslemetry Documentation**: [docs.teslemetry.com](https://docs.teslemetry.com)
268+
- **API Reference**: [api.teslemetry.com](https://api.teslemetry.com)
269+
- **Community Support**: Join the Teslemetry community forums
270+
271+
## License
272+
273+
These examples are provided under the same license as the main library.

0 commit comments

Comments
 (0)