node-red-contrib-toyota 0.3.3

Unofficial Node-RED nodes for Toyota Connected Services.

npm install node-red-contrib-toyota

node-red-contrib-toyota

Unofficial Node-RED nodes for Toyota Connected Services.

Connect a Toyota/MyToyota account, discover its vehicles, read vehicle information and current status, retrieve trips from the Toyota service, and synchronize trips into a local SQLite database for later queries.

Disclaimer

This is an independent, unofficial open-source project and is not affiliated with, endorsed by, sponsored by, or otherwise associated with Toyota Motor Corporation, Toyota Motor Europe, Lexus, or any of their subsidiaries or affiliates.

Toyota, Lexus, MyToyota and related names, logos and trademarks are the property of their respective owners.

This project interacts with undocumented/private Toyota Connected Services interfaces. Those interfaces may change, become unavailable, or stop working at any time without notice.

Use this software at your own risk. The maintainers make no guarantee regarding availability, compatibility, accuracy, or continued operation of Toyota Connected Services.

Features

• Toyota account authentication through the Node-RED credential store.
• Multi-vehicle discovery and vehicle selection.
• Vehicle information, connected services, subscription expiration, and Toyota-reported capabilities.
• Current telemetry and physical vehicle state when supplied by Toyota.
• Live trip retrieval from Toyota Connected Services.
• Date-range trip synchronization into local SQLite storage.
• Queries for synchronized trip collections and individual persisted trips.
• Per-resource cache with explicit refresh support where applicable.

Remote lock/unlock, climate commands, wake-up, push events, and other remote actions are not implemented.

Requirements

• Node.js >=22.9.0.
• Node-RED >=5.0.2.
• A Toyota/MyToyota account and a vehicle visible to that account.
• Network access to Toyota Connected Services.
• A Node.js environment able to install the native better-sqlite3 dependency.

Toyota data availability depends on the vehicle, region, subscription, and the availability of the Toyota service.

Toyota vehicles are the currently validated target. Lexus has not been tested with node-red-contrib-toyota. The integration contains protocol handling intended for Lexus where supported by the underlying Toyota Connected Services interfaces, but Lexus compatibility is currently experimental and unverified.

Installation

Node-RED Palette Manager

After this package is published, use Menu → Manage palette → Install. Search for node-red-contrib-toyota and select Install. Restart Node-RED if requested.

npm

From the Node-RED user directory:

cd ~/.node-red
npm install node-red-contrib-toyota

Restart Node-RED after installation.

Normal use does not require TOYOTA_* variables, settings.js, a systemd drop-in, Docker environment variables, or an external protocol profile.

Development install

For a local checkout only:

cd ~/.node-red
npm install /path/to/node-red-contrib-toyota

First setup

1. Add any Toyota node to a flow.
2. Create or select a Toyota Account configuration node.
3. Enter your Toyota/MyToyota email or username.
4. Enter your password.
5. Select the brand when prompted.
6. Deploy the flow.

No Toyota developer account and no API key are required from the user. No external protocol configuration is required for normal use.

Users provide their own Toyota/MyToyota credentials. This project is not a Toyota authentication provider. Access and refresh tokens are runtime user secrets; protect the Node-RED credential store, its credentialSecret, and the Node-RED userDir.

Toyota Account

Toyota Account is a configuration node shared by the other nodes. Configure:

• username/email;
• password;
• Toyota brand (validated target); Lexus brand handling is experimental and unverified;
• optional local SQLite path and sync policy settings.

One account can be reused by multiple nodes and can own multiple vehicles. Credentials are managed by Node-RED. Tokens are not placed in messages or status text.

Nodes

Toyota Vehicles

Discovers the vehicles associated with the account and emits a canonical array. Vehicles are also stored locally so vehicle-aware nodes can select them later.

Example shape:

[
  {
    "vehicleId": "SYNTHETIC_VEHICLE_ID",
    "providerVehicleId": null,
    "vin": "SYNTHETICVIN000000",
    "model": "Example Model",
    "brand": "T",
    "alias": "My Toyota"
  }
]

The result may come from the account cache. Set msg.toyota.refresh to true to request a fresh result.

Toyota Vehicle Info

Reads metadata for the selected vehicle, including connected services, expiration dates, and Toyota-reported capability data. Capabilities are values reported by Toyota; a reported capability does not guarantee that this package implements the corresponding action.

Conceptual output:

{
  "vehicle": { "vehicleId": "SYNTHETIC_VEHICLE_ID", "model": "Example Model", "brand": "T" },
  "connectedServices": [
    { "name": "Example Service", "status": "ACTIVE", "type": "subscription", "expiresAt": "2030-01-01", "remainingDays": 100 }
  ],
  "capabilities": {
    "extended": { "vehicleStatus": true },
    "features": { "remoteService": false },
    "remoteServices": {},
    "reported": [{ "id": "SYNTHETIC_CAPABILITY", "supported": null }],
    "vehicle": []
  }
}

Toyota Status

Reads current telemetry and physical state for one selected vehicle.

{
  "telemetry": {
    "odometerKm": 12345,
    "fuelLevelPercent": 60,
    "rangeKm": 400,
    "timestamp": "2030-01-01T12:00:00Z"
  },
  "vehicleState": {
    "doors": { "driver": { "openStatus": {}, "lockStatus": {} } },
    "windows": { "driver": {} },
    "lights": { "head": {}, "tail": {}, "hazard": {} }
  }
}

The full contract includes the reported door, window, and light keys. A state such as open or closed is data from Toyota, not automatically an application warning or safety error.

Toyota Trips

Returns a trip collection for a selected vehicle and date range. The source setting makes the distinction explicit:

• live: query Toyota Connected Services;
• sqlite: query trips previously persisted by Toyota Sync.

The editor provides a Date range source selector. With Configured dates, use the browser-local From and To date/time pickers; values are stored and sent internally as ISO UTC timestamps. With msg.toyota.from / msg.toyota.to, the range is supplied by the incoming message and the configured pickers are not required. Both sources require valid dates with From not later than To. The message source works with both live and sqlite.

For example, an Inject, Change, Function, Dashboard, Home Assistant, or any other upstream node can provide a dynamic range:

msg.toyota = {
  ...(msg.toyota || {}),
  from: "2026-08-01T00:00:00.000Z",
  to: new Date().toISOString()
};
return msg;

In the legacy/default configured mode, msg.toyota.from and msg.toyota.to continue to override the corresponding configured values. In explicit message mode both fields are required; missing, invalid, or inverted ranges produce INVALID_RANGE.

Toyota Trip

Returns one persisted SQLite trip. Select the vehicle and configure its external trip identifier, or provide msg.toyota.externalTripId. This node is SQLite-only and does not request a live trip from Toyota.

SQLite preserves the canonical Toyota score fields (score, grade, global, acceleration, braking, advice, and constantSpeed) and all HDC metrics. Existing databases are migrated forward; newly added fields are null for historical rows until the corresponding range is synchronized again.

Toyota Sync

Downloads Toyota trips and persists them into the account's local SQLite database. latest automatically synchronizes from the previous complete checkpoint, with overlap, up to the current time. Configured From/To values and dynamic message ranges are not used in latest. range uses the selected configured or message From/To range.

For latest, from is the previous complete checkpoint minus the configured overlap and to is the runtime current time; the resulting to becomes the new checkpoint only after a complete sync. With no checkpoint, the existing first-sync policy requires an explicit starting point.

The date range source is available in range mode: choose configured From/To dates or msg.toyota.from / msg.toyota.to. latest mode uses the stored checkpoint and does not require a range. Configured picker values use browser- local values and are stored as ISO UTC. Dynamic ranges require both valid fields with From not later than To and produce INVALID_RANGE when invalid.

A sync result includes its run ID, range, status, checkpoint values, counters, and warnings. Complete runs advance the checkpoint. Partial or failed runs do not advance it. Existing trips are compared by identity and content, making repeat synchronization idempotent.

Live data and local SQLite data

Toyota Connected Services → live Vehicles / Vehicle Info / Status / Trips
Toyota Sync                → local SQLite
Toyota Trips source=sqlite → local trip collection
Toyota Trip                → one persisted local trip

Live trip retrieval does not automatically persist trips. Run Toyota Sync when local history is required.

Runtime message overrides

Nodes read overrides from msg.toyota. An override takes precedence over the corresponding editor setting.

Field	Nodes	Type	Meaning
vehicleId	vehicle-aware nodes	string	Local or provider vehicle identifier.
refresh	Vehicles, Vehicle Info, Status	boolean	Bypass the applicable cache.
from, to	Trips, Sync	ISO/date string accepted by the node	Requested date range; explicit message range mode requires both.
source	Trips	live or sqlite	Select live Toyota data or local SQLite data.
includeRoute	Trips	boolean	Include route data in live trip retrieval.
includeBehaviours	Trips	boolean	Request trip summary/behaviour data.
externalTripId	Trip	string	Select one persisted trip.
mode	Sync	latest or range	Select checkpoint sync or explicit-range sync.
overlap	Sync	integer, 0–31	Override sync overlap days.

Output convention

Successful nodes set msg.payload to the operation result and add safe operation metadata to msg.toyota:

{
  "toyota": {
    "accountId": "local-account-id",
    "vehicleId": "local-vehicle-id",
    "vinLast4": "0000",
    "operation": "status",
    "source": "live",
    "fetchedAt": "2030-01-01T12:00:00.000Z",
    "schemaVersion": 1
  }
}

Identifiers in this example are synthetic. Full VINs and credentials are not added to normal node metadata.

Errors

Errors are delivered through the normal Node-RED error path: the node status becomes error, node.error(error, msg) is used, and a Catch node can handle the message. The safe error preserves error.code, an integer HTTP status when available, and a recognized operation stage when available.

Examples of stable codes include CONFIGURATION, AUTHENTICATION_FAILED, AUTHORIZATION_FAILED, API_ERROR, TIMEOUT, INVALID_RESPONSE, INVALID_RANGE, INVALID_SOURCE, INVALID_MODE, INCOMPLETE_RESULT, VEHICLE_REQUIRED, VEHICLE_NOT_FOUND, TRIP_REQUIRED, TRIP_NOT_FOUND, and SYNC_BUSY.

Example safe error metadata:

Toyota operation failed (API_ERROR, HTTP 400, stage=vehicles)

Response bodies, tokens, cookies, authorization values, API keys, and full endpoints are not included in these messages.

Date and time ranges

The Sync and Trips editors use browser-local date/time controls. The value is converted internally to ISO UTC when saved and sent. Both From and To are required where the node requires a range, and From must be earlier than or equal to To.

Credentials and security

Toyota credentials are user secrets and belong to the user. Store them only in Node-RED's credential system. Protect the Node-RED userDir and credentialSecret, do not export flows with credentials in clear text, and do not send passwords or tokens through Debug nodes or message properties.

Static protocol metadata is internal package configuration and is not a user setup step. Advanced protocol overrides are documented below without exposing their values.

Advanced protocol overrides

RED.settings.toyota.protocol and TOYOTA_* variables exist for development, diagnostics, and interoperability testing. They are not required for normal installation or account setup. Do not add protocol credentials or user secrets to flows.

Limitations

• Toyota Connected Services interfaces are undocumented/private and may change.
• Lexus has not been tested. All current live validation has been performed with Toyota; Lexus users should consider compatibility experimental.
• Data depends on vehicle, region, subscription, and Toyota service availability.
• Connected services and reported capabilities differ between vehicles.
• Reported capabilities do not imply implemented remote actions.
• This package does not guarantee availability or accuracy of Toyota data.
• No remote lock/unlock, climate, wake-up, push/event stream, or internal scheduler is provided.

Troubleshooting

Authentication fails

Verify the Toyota/MyToyota credentials, brand, account access, and service availability. Do not start by adding protocol environment variables; they are advanced diagnostics only.

Vehicle list is empty

Check that the vehicle is visible in MyToyota, then retry with msg.toyota.refresh = true.

Live trips are empty

Check the selected vehicle and date range. The Toyota account must contain trip history for that range.

SQLite trips are empty

Run Toyota Sync first, then query Toyota Trips with source set to sqlite, or use Toyota Trip with a persisted external trip ID.

INVALID_RANGE

Provide valid From and To values and ensure From is not after To.

API errors

Toyota's private interfaces may change or be temporarily unavailable. Inspect the Node-RED status and logs, and use a Catch node to inspect the safe error code, stage, and HTTP status.

Example flow

The simplest flow is:

Inject → Toyota Vehicles → Debug

For current vehicle data:

Inject → Toyota Status → Debug

For semi-static vehicle information:

Inject → Toyota Vehicle Info → Debug

Create and configure Toyota Account after importing a flow. No credentials, account IDs, VINs, or protocol overrides are included in the examples.

License

This project is licensed under the MIT License. The MIT License applies to this repository's code and does not grant rights to Toyota or Lexus services, APIs, names, logos, trademarks, or protocol identifiers.

Development

npm ci
npm test
npm run test:smoke
npm pack --dry-run

Technical provenance and protocol distribution notes are maintained separately in docs/PROVENANCE.md, docs/TOYOTA_PROTOCOL_DISTRIBUTION.md, and docs/RELEASE_READINESS.md.