# FleetLume Telematics Integrations FleetLume can connect truck and trailer equipment from Motive, Samsara, Geotab, or a generic GPS/ELD webhook. Provider equipment is discovered first, then mapped to the matching truck or trailer already stored in FleetLume. ## Roles and visibility ### Drivers Drivers can open **My Equipment** from the driver portal and: - Connect their own Motive, Samsara, Geotab, or generic GPS/ELD account. - View connections they created or connections assigned to their driver profile. - Discover provider vehicles and equipment. - Map provider assets only to trucks or trailers assigned to them or linked to their carrier. - Manually refresh a supported provider connection. - Disconnect only a connection they personally created. A driver portal account must be linked to a FleetLume driver profile before the driver can connect equipment. ### Owners, administrators, and dispatchers Owners, administrators, and dispatchers can open **Dispatch → Telematics Providers** and: - View all provider connections created by the company or its drivers. - See who created each connection and its driver/carrier scope. - View every discovered provider asset and its latest telemetry. - Map or unmap any provider asset to an internal truck or trailer. - Sync one connection or all connections. - View provider errors, last sync, last successful sync, online count, and mapping status. - Open the unified live tracking map for all mapped trucks. - Disconnect any provider connection when access must be revoked. ## Supported connection types ### Motive Enter either a Motive company API key or a Motive OAuth access token. Company API keys are sent with the `X-API-Key` header; OAuth credentials are sent as bearer tokens. FleetLume reads all pages of the company vehicle-location endpoint and imports vehicle ID, number, VIN, latest coordinates, heading, speed, location time, and available status details. ### Samsara Enter a Samsara API token with permission to read vehicle statistics. FleetLume reads every page of the vehicle-location snapshot endpoint and imports the latest known locations for visible vehicles. ### Geotab Enter the MyGeotab server, database, service-user email, and password. FleetLume authenticates through the MyGeotab API and reads Device and DeviceStatusInfo records. Geotab speed is converted from kilometres per hour to miles per hour before it is shown in FleetLume. ### Generic GPS / ELD webhook FleetLume generates a private bearer token. The raw token is shown once and only its SHA-256 hash is stored. Any GPS, ELD, IoT gateway, or custom integration can send one asset or an `assets` array to: ```text POST /telematics/webhook Authorization: Bearer YOUR_PRIVATE_TOKEN Content-Type: application/json ``` Example truck update: ```json { "device_id": "TRUCK-101", "asset_type": "truck", "name": "Truck 101", "vin": "1ABC2345678901234", "latitude": 41.8781, "longitude": -87.6298, "speed": 58, "heading": 270, "ignition": true, "odometer": 421530, "location_address": "Chicago, IL", "recorded_at": "2026-07-13T01:02:03Z" } ``` Example trailer update: ```json { "device_id": "TRAILER-204", "asset_type": "trailer", "name": "Reefer 204", "latitude": 40.7128, "longitude": -74.0060, "temperature_f": 35.5, "fuel_percent": 72, "recorded_at": "2026-07-13T01:02:03Z" } ``` Recognized aliases include `id`, `vehicle_id`, `asset_id`, `lat`, `lon`, `lng`, `speed_mph`, `speedMilesPerHour`, `bearing`, `located_at`, `timestamp`, `temperature`, and `fuel_level`. ## Equipment mapping A provider asset does not affect dispatch tracking until it is mapped to an internal FleetLume truck or trailer. When a truck asset is mapped, each new location can update: - Truck location history. - The dispatcher live map. - The active load's current location and last location time. - The active route plan. - Truck odometer, when supplied. - Moving, stopped, stale, and offline tracking indicators. When a trailer asset is mapped, each new update can refresh: - Reefer temperature. - Temperature timestamp. - Reefer fuel level. - Latest provider location stored on the asset record. ## Automatic synchronization Provider polling is performed by `telematics_sync.php`. Run it once per minute with cron; each connection still respects its own configured interval. ```cron * * * * * /usr/bin/php /absolute/path/to/fleetlume/telematics_sync.php >> /absolute/path/to/fleetlume/storage/telematics.log 2>&1 ``` Generic webhook updates are processed immediately and do not require polling. Motive, Samsara, and Geotab freshness depends on the provider API, installed hardware, network availability, and the configured FleetLume polling interval. The included integrations use server-side API credentials rather than marketplace OAuth onboarding. ## Security requirements - Serve FleetLume over HTTPS. - Use read-only provider credentials whenever possible. - Restrict tokens to the minimum required fleet/vehicle permissions. - Do not place provider tokens in browser JavaScript or public files. - Keep `TELEMATICS_ENCRYPTION_KEY` stable after connections are created. Changing it prevents existing credentials from being decrypted. - The installer generates a random telematics encryption key for new or upgraded installations when one is not already configured. - Provider credentials are encrypted before database storage using Sodium secretbox when available, otherwise OpenSSL AES-256-GCM. - Generic webhook tokens are not stored in recoverable form. - Restrict access to `install.php` after setup. ## Installation and upgrade 1. Back up the database, application files, and `storage/uploads`. 2. Upload the new project files. 3. Open `/install.php?unlock=1`. 4. Use the existing database credentials and complete the update. 5. Confirm that PHP cURL is enabled and outbound HTTPS requests are allowed. 6. Confirm that Sodium or OpenSSL is enabled. 7. Add the cron command shown above. 8. Connect a staging provider account and verify asset discovery. 9. Map a test vehicle to a FleetLume truck. 10. Confirm its location appears under **Live Truck Tracking** before production rollout. The updater creates `telematics_connections` and `telematics_assets` without intentionally deleting existing records. ## Troubleshooting ### Connection saved but first sync failed The connection remains stored with an error message. Check the token, provider permissions, outbound HTTPS access, PHP cURL, and provider account availability, then use **Sync Now**. ### No equipment is discovered Confirm that the provider account can see vehicles and that those vehicles have active gateways/devices. For Samsara, ensure the API token includes permission to read vehicle statistics. ### A truck does not appear on the live map Confirm that: 1. The provider connection has synchronized successfully. 2. The provider asset contains latitude and longitude. 3. The asset is mapped to a FleetLume truck. 4. The provider timestamp is recent. 5. The truck is active. ### Driver cannot map an asset The driver can only map equipment from their current/historical load assignments or equipment belonging to the same carrier. An administrator can correct truck, trailer, driver, or carrier assignments. ### Existing credentials stopped working after migration Restore the original `TELEMATICS_ENCRYPTION_KEY` from the previous configuration. The encryption key must remain unchanged for existing encrypted credentials.