Skip to content

README.md

Latest commit

 

History

History
297 lines (224 loc) · 9.58 KB

README.md

File metadata and controls

297 lines (224 loc) · 9.58 KB
Raw
Sharp Toyota Client logo

SharpToyotaClient

NuGet License .NET C#

A modern .NET 10 client library for interacting with Toyota's MyToyota Connected Services API. This project provides a fluent, async-first interface to access comprehensive vehicle data including location, status, climate control, remote commands, and more.

📋 Table of Contents

✨ Features

  • Async-First: All operations are fully asynchronous with cancellation token support
  • Fluent Configuration: Easy, chainable builder pattern for client setup
  • Dependency Injection: First-class IServiceCollection integration via AddToyotaClient()
  • Type-Safe: Strong typing for all API contracts and responses
  • Comprehensive API: Access to vehicles, location, climate control, remote commands, trip history, and more
  • Token Caching: Automatic token caching to minimize login overhead
  • Error Handling: Precise exceptions for different failure scenarios
  • Performance: Built with .NET 10 and C# 14 for optimal performance

📦 Installation

Install the NuGet package:

dotnet add package SharpToyotaClient

Or via Package Manager:

Install-Package SharpToyotaClient

🚀 Quick Start

Security note: The client works out of the box with Toyota's public OneApp client identifier (Constants.PUBLIC_API_KEY). It is not a credential — it ships with the official Toyota app and is present in all public open-source Toyota clients; the SonarCloud S6418 finding is explicitly suppressed with justification in the source. If Toyota ever rotates the key, override it via the TOYOTA_API_KEY environment variable or the ToyotaApi:ApiKey configuration section:

export TOYOTA_API_KEY=your-api-key
# PowerShell: $env:TOYOTA_API_KEY = "your-api-key"
using SharpToyotaClient;

// Create and configure the client
var client = new MyToyotaClient()
    .UseCredentials("your-username", "your-password")
    .UseTimeout(30)
    .UseTokenCaching(true);

// Authenticate
var loginSuccess = await client.LoginAsync();
if (!loginSuccess)
    throw new InvalidOperationException("Login failed");

// Get your vehicles
var vehicles = await client.GetVehiclesAsync();
foreach (var vehicle in vehicles?.Data ?? [])
{
    Console.WriteLine($"VIN: {vehicle.Vin}, Name: {vehicle.Nickname}");
}

// Get vehicle status
var location = await client.GetLocationAsync("JTHJP5C27D5012345");
Console.WriteLine($"Location: {location?.Data?.Latitude}, {location?.Data?.Longitude}");

// Control your vehicle
var result = await client.StartClimateControlAsync("JTHJP5C27D5012345");
if (result?.IsSuccess == true)
    Console.WriteLine("Climate control started");

💉 Dependency Injection

SharpToyotaClient ships with built-in support for the .NET Options pattern and Microsoft.Extensions.DependencyInjection.

Option A — Inline lambda (recommended for simple setups)

// Program.cs
using SharpToyotaClient.Extensions;

builder.Services.AddToyotaClient(options =>
{
    options.Username       = builder.Configuration["Toyota:Username"]!;
    options.Password       = builder.Configuration["Toyota:Password"]!;
    options.TimeoutSeconds = 30;
    options.Logger         = msg => Console.WriteLine(msg); // optional
});

Option B — Bind from appsettings.json

Add a section to your appsettings.json:

{
  "ToyotaClient": {
    "Username": "your@email.com",
    "Password": "your-password",
    "TimeoutSeconds": 30,
    "UseTokenCaching": true
  },
  "ToyotaApi": {
    "ApiKey": "your-api-key"
  }
}

Then register:

// Program.cs
using SharpToyotaClient;
using SharpToyotaClient.Extensions;

builder.Services.AddToyotaClient(
    builder.Configuration.GetSection(ToyotaClientOptions.SectionName));

Consuming IMyToyotaClient

Once registered, inject IMyToyotaClient anywhere in your application:

public class VehicleService(IMyToyotaClient client)
{
    public async Task<string?> GetFirstVinAsync(CancellationToken ct = default)
    {
        await client.LoginAsync(ct);
        var vehicles = await client.GetVehiclesAsync(ct);
        return vehicles?.Data?.FirstOrDefault()?.Vin;
    }
}

Security tip: Never store credentials in appsettings.json for production.
Use Secret Manager in development
and Azure Key Vault or environment variables in production.

For a full walkthrough see docs/GETTING_STARTED.md.

📚 Documentation

📁 Project Structure

SharpToyotaClient/
├── src/
│   └── SharpToyotaClient/          # Main client library
│       ├── Extensions/                 # DI extension methods
│       ├── Interfaces/                 # Public API contracts
│       ├── Models/                     # API response/request models
│       ├── Services/                   # Core business logic
│       ├── Exceptions/                 # Custom exception types
│       └── ToyotaClientOptions.cs      # DI / Options-pattern configuration
├── samples/
│   └── SharpToyotaClient.Demo.ConsoleApp/ # Example usage
├── tests/
│   └── SharpToyotaClient.Tests/    # Unit and integration tests
├── assets/
│   └── logo.svg                        # Project logo
└── docs/                               # Documentation

🛠️ Requirements

  • .NET 10+ or later
  • C# 14 (or later)
  • Toyota Connected Services Account

🧪 Testing

To run the test suite:

# Unit tests
dotnet test

# With coverage (requires dotnet-coverage)
dotnet-coverage collect -f cobertura -o coverage.cobertura.xml dotnet test

Environment Variables for Tests

Integration tests require valid Toyota credentials:

export TOYOTA_USERNAME=your-username
export TOYOTA_PASSWORD=your-password
export TOYOTA_API_KEY=your-api-key
dotnet test

🎯 Supported Features

Vehicle Information

  • Get all associated vehicles

Electric/EV Status

  • Battery level and charging status
  • Real-time EV status data
  • Charging commands (charge now / scheduled charging)

Climate Control

  • Get climate settings and status
  • Start/stop climate control (incl. full v2 settings presets)
  • Refresh climate status

Remote Commands

  • Lock/unlock vehicle
  • Start/stop engine
  • Control lights
  • Open trunk
  • Hazard lights

Vehicle Telemetry

  • Current location
  • Lock status (doors, trunk, windows)
  • Health diagnostics
  • Telemetry data
  • Service history

Battery & Location Monitor

  • MonitorDrivingTelemetryAsync() — polls battery SOC/range + geo location with an adaptive cadence:
    • Driving (odometer changes): every 30s, optional wake
    • Charging: every 2 min, no wake
    • Parked: every 10 min, reads cached data without ever waking the vehicle → no 12V-battery drain when the car isn't on a charger

Trip Management

  • Trip history with optional route data
  • Trip summaries
  • Trip statistics

Notifications

  • Recent vehicle notifications

🔒 Security

  • Never hardcode credentials - Use environment variables or configuration files
  • Token caching is enabled by default but can be disabled if needed
  • Secure storage - Consider using Azure Key Vault or similar for sensitive data in production
  • See SECURITY.md for more details

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright © 2026 MPCoreDeveloper

Attribution

This project is based on Abraham.MyToyotaClient, which is licensed under the Apache License 2.0. We acknowledge and thank the original author for their work.

⚠️ Disclaimer

This is an unofficial client library and is not affiliated with, endorsed by, or associated with Toyota Motor Corporation or any of its subsidiaries.

Use at your own risk. The authors assume no responsibility for any misuse, damage, or issues arising from the use of this library. Ensure you comply with Toyota's Terms of Service and respect their API usage policies.

📞 Support