Truck Schedule Calendar¶

Last Updated: March 2026

The Truck Schedule Calendar is a visual dispatch tool that displays every scheduled pickup as a color-coded event on a monthly calendar. Dispatchers use it to see at a glance which trucks are running on which days, how much weight each route carries, and whether any route is under-loaded or over-capacity. Clicking any event opens a detail dialog with an optimized stop order, estimated arrival/departure times, mileage, and an interactive map of the entire route. Under the hood, the module runs a TSP (Traveling Salesman Problem) route optimizer and pushes finalized routes to Samsara for GPS-guided turn-by-turn navigation.

Scott Recycling (main menu)
  +-- Operations
        +-- Calendars
              +-- Truck Schedule      <-- you are here
              +-- Tractor Trailer Calendar
              +-- LTL Calendar

The calendar opens as a full-screen client action. There is no list or form view for this page — it is a custom JavaScript component built on FullCalendar.

What You See on the Calendar¶

When the page loads, the system queries every customer.pickups record that is not cancelled, groups them by truck and date, and renders one event block per truck per day.

Event Tile Anatomy¶

Each colored block on the calendar represents a single truck's pickups for one day.

Element	What It Means	Example
Tile color	Matches the truck's assigned color from the Fleet record. Gray means no color is set.	Blue, red, green, etc.
Title text	Region short code followed by the total estimated weight for that route.	"SBT-1450" means the Sunbright region route with 1,450 lbs estimated
Warning icon	A yellow warning triangle appears when the route's total weight is below the configured minimum pickup weight threshold. This means the truck may be under-loaded.	Appears automatically
Skull icon	A skull icon appears when the route's total estimated box count exceeds the configured maximum number of boxes. This means the truck is over-capacity.	Appears automatically

Warning Icons

The warning icon (under-loaded) and skull icon (over-capacity) are driven by system parameters. If you see a warning, the route may need additional pickups added. If you see a skull, pickups need to be moved to another truck or rescheduled.

Calendar Views¶

The calendar toolbar provides four view modes:

View	Button	Best For
Month	`Month`	Default view. Best for weekly planning and seeing overall fleet utilization.
Week	`Week`	Zoomed-in view of a single week. Shows time-based layout.
Day	Click any date number	Single day detail. Useful when many trucks are running.
List	`List`	Flat list of all events over the selected time range.

Use the Today button to jump back to the current date, and the Previous/Next arrows to navigate between periods.

The Schedule Detail Dialog¶

Click any event tile on the calendar to open the Schedule Detail Dialog. This is where you see the full breakdown of a route.

The dialog title shows: {Truck Dispatch Name} Orders for : {Date} ({Route Name})

At the top of the dialog, the Open Truck Schedule button links directly to the truck schedule form record, where you can manage pickups, push to Samsara, or change the driver.

Pickup Details Tab¶

The Pickup Details tab shows a table of every stop on the route, in optimized order:

Column	What It Shows	Notes
Step	Stop number in the optimized route sequence.	1 is the first stop after leaving the warehouse.
Order ID	The pickup record ID. Clickable link that opens the pickup form.	Links directly to the pickup record.
Customer	Customer name. Clickable link that opens the customer contact record.	Links directly to the partner form.
City	Customer's city.	From the contact record.
State	Customer's state.	From the contact record.
No. Of box	Number of boxes to pick up at this stop.	Drives the capacity warning.
Weight	Estimated weight in pounds.	From the pickup record.
Special	Checkbox indicating if this is a special pickup.	Read-only in this view.
Miles	Distance in miles from the previous stop (or from the warehouse for the first stop).	Calculated by the ORS routing engine.
Time	Drive time from the previous stop. Displayed as HH:MM.	Calculated by the ORS routing engine.
Dx/WH	Distance to the warehouse from this stop.	Helps dispatchers understand return-trip impact.
Time/WH	Drive time to the warehouse from this stop.	Helps dispatchers estimate return time if the route were cut short.
Start Time	The time the driver departs the previous stop (or the warehouse).	Based on the configured trip start time.
Arrival Time	Estimated time of arrival at this stop.	Start time + drive time.
Dept. Time	Estimated departure time from this stop.	Arrival time + time at pickup location + any additional time.
From	The location the driver is coming from.	Address or "Warehouse" for the first stop.
To	The destination for this leg.	Customer name and city/state.

The last row in the table is always Warehouse — the return leg back to the truck's home warehouse.

Summary Row¶

Below the pickup rows, a summary row shows:

Total boxes across all stops
Total estimated weight in pounds
Total miles for the entire route
Total drive time in HH:MM format

Clickable Links

Both the Order ID and Customer name columns are clickable. They open in new tabs, so you will not lose your place in the calendar dialog.

Map Tab¶

The Map tab displays an interactive Leaflet map showing:

Warehouse marker — blue circle labeled "W" at the truck's home warehouse location
Numbered stop markers — each pickup shown as a colored numbered circle (1, 2, 3, etc.) in the optimized route order
Routing lines — the actual road-network route drawn between all stops, calculated by the OpenRouteService (ORS) engine
Turn-by-turn directions — a collapsible routing panel with step-by-step driving directions

The map automatically fits all markers into view. You can zoom, pan, and click any marker to see a popup with the customer name or "Warehouse."

Map Data Sources

Customer coordinates come from the partner record (latitude/longitude). If a customer's coordinates are missing or zero, the system attempts to geocode the address automatically. The routing lines follow actual road networks using the ORS truck routing profile, which accounts for truck-specific restrictions (bridge heights, weight limits, etc.).

How Route Optimization Works¶

When you click a calendar event, the system does not simply list the pickups in the order they were created. It runs a full route optimization to determine the most efficient stop sequence.

The Optimization Process¶

Gather locations — the warehouse address (start/end point) and all customer addresses on the route
Geocode if needed — any customer missing latitude/longitude gets geocoded via Google Maps
Build distance matrix — the system calculates driving distances between every pair of locations using the ORS truck routing API, producing an N-by-N matrix
Solve TSP (nearest neighbor) — starting from the warehouse, the algorithm greedily visits the nearest unvisited stop, building an initial route
2-opt improvement — the algorithm then iteratively checks whether reversing any segment of the route would reduce total distance, eliminating inefficient crossings
Generate itinerary — with the optimized stop order determined, the system calculates arrival times, departure times, and distances for each leg based on the configured trip start time and stop duration

What Affects the Optimization¶

Factor	Where It Comes From	Impact
Trip start time	Settings > Scheduling > Trip Start Time	Determines when the driver leaves the warehouse. All arrival/departure times cascade from this.
Time at pickup location	Settings > Scheduling > Default Time at a Pickup	How long the driver spends at each stop. Default is 30 minutes.
Additional time	Set per-pickup on the pickup record	Extra time for difficult sites (upper floors, no forklift, etc.). Added on top of the default stop time.
Customer coordinates	Partner record (partner_latitude, partner_longitude)	Must be accurate for routing to work. Missing coordinates fall back to geocoding.
Warehouse location	The truck's region > warehouse > partner address	The start and end point for every route.

Why Routes May Differ From Expectations

The optimizer uses actual road distances, not straight-line distances. Two stops that look close on a map may be far apart by road (e.g., separated by a river with no nearby bridge). The ORS truck routing profile also avoids roads restricted for commercial vehicles.

Samsara Integration¶

The Truck Schedule Calendar is tightly integrated with Samsara, the GPS fleet management platform used by Scott Recycling. Routes optimized in Odoo can be pushed to Samsara so drivers see turn-by-turn navigation on their Samsara devices.

How Route Creation Works¶

When a route is created (via the truck schedule form, not directly from the calendar), the system:

Builds the optimized stop sequence using the TSP solver
Converts all times from Eastern Time to UTC/Zulu format for the Samsara API
Sends a POST request to https://api.samsara.com/fleet/routes with:
- Driver ID (from the Samsara Driver Code on the employee record)
- Warehouse as the first stop (using the Samsara Address ID from the warehouse)
- Each customer stop with GPS coordinates, scheduled arrival, and scheduled departure
- Warehouse as the final stop with an estimated return time
Stores the Samsara Route ID and full response data on the truck schedule record
Assigns Samsara Stop IDs to each pickup for tracking

How Route Updates Work¶

When pickups are added, removed, or resequenced on an existing route that already has a Samsara Route ID:

The system fetches the current route details from Samsara
Rebuilds the stop list with updated pickups and recalculated times
Sends a PATCH request to update the route in place
Updates the route name with a new unique key (format: UPD-RT-{region}-{date}-{random})
Refreshes the Samsara Stop IDs on all pickups

Route Naming Convention¶

Type	Format	Example
New route	`RT-{region}-{date}_{time}-{random}`	`RT-SBT-2026-03-03_08-00-00-a1b2c3`
Updated route	`UPD-RT-{region}-{date}-{random}`	`UPD-RT-SBT-2026-03-03-d4e5f6`

Manual Route Mode¶

Some routes use Force Manual Pickups Order (a flag on the truck schedule record). In manual mode:

The TSP optimizer is bypassed
Pickups are sent to Samsara in their manually set sequence order
Times are calculated sequentially starting from the driver start time
Distances show as 0 (no routing calculations are performed)

This is useful when a dispatcher needs to override the optimizer, for example when a customer has a strict time window or a specific stop order is required for other reasons.

Samsara API Key

The Samsara API Key is stored in the system settings. If routes fail to push, verify the key is valid and has not expired. The error message from Samsara will appear as a validation error in Odoo.

Fleet Vehicle — Samsara Vehicle Code¶

This module adds a Set Samsara Vehicle Code button to the fleet vehicle form (visible to Dispatchers and above). When clicked:

The system calls the Samsara API to fetch all vehicles (/fleet/vehicles)
Matches the Odoo vehicle's license plate against Samsara's licensePlate field
Stores the Samsara vehicle ID as the samsara_vehicle_code on the fleet record

Requirement	Detail
License plate must be set	The button will raise an error if the vehicle has no license plate in Odoo.
Must exist in Samsara	If no Samsara vehicle matches the license plate, an error is displayed.
Samsara API key required	The API key from Settings must be valid.

When to Use This Button

Use this button when adding a new vehicle to the fleet or if the Samsara Vehicle Code field is blank. You only need to do it once per vehicle — the code does not change unless the vehicle is replaced in Samsara.

Configuration Settings¶

Settings are managed at Scott Recycling > Configuration > Settings, under the Scheduling section.

Setting	Field Type	What It Controls	Default
Trip Start Time	Time (float)	The time drivers depart the warehouse each morning. Used to calculate all arrival/departure times in the route itinerary.	8:00 AM
Default Time at a Pickup	Time (float)	How long a driver spends at each stop. Added to arrival time to calculate departure time.	0:30 (30 minutes)
Samsara API Token	Text	The Bearer token for authenticating with the Samsara API. Required for all Samsara operations.	(must be configured)

Changing Trip Start Time

Changing the trip start time affects all future route calculations. Existing Samsara routes that have already been pushed will not be retroactively updated. If you change the start time, you should re-push any routes for the current or next day.

Common Tasks¶

View a Day's Routes for All Trucks¶

Open Scott Recycling > Operations > Calendars > Truck Schedule
The calendar loads in Month view by default
Click the date number to switch to Day view, or simply look at the event tiles on that date
Each colored tile represents one truck's route — the color matches the truck's assigned color in the Fleet app
Read the tile text to see the region code and total weight

Inspect a Specific Route¶

Click any event tile on the calendar
The Schedule Detail Dialog opens with the optimized route
Review the Pickup Details tab for the full stop-by-stop breakdown
Check arrival and departure times to confirm the route fits within the day
Switch to the Map tab to visualize the route geographically
Click Open Truck Schedule to go to the full truck schedule form if you need to make changes

Check if a Route is Under-loaded or Over-capacity¶

Look for warning icons on calendar event tiles:
- Warning triangle = route weight is below the minimum threshold (under-loaded)
- Skull = route box count exceeds the maximum (over-capacity)
Click the tile to open details and see exactly how much weight and how many boxes are on the route
If under-loaded, consider adding more pickups from nearby customers
If over-capacity, move pickups to another truck or reschedule to a different date

Link a Vehicle to Samsara¶

Open Fleet from the main Odoo dashboard
Open the vehicle record you want to link
Confirm the License Plate field is filled in and matches the plate in Samsara
Click the Set Samsara Vehicle Code button in the header
The system will query Samsara and populate the Samsara Vehicle Code field automatically
If an error appears, verify the license plate matches exactly (case-sensitive) and that the Samsara API key is valid

Update the Trip Start Time or Stop Duration¶

Navigate to Scott Recycling > Configuration > Settings
Scroll to the Scheduling section
Adjust Trip Start Time (e.g., change from 8:00 to 7:30 for an earlier start)
Adjust Default Time at a Pickup if drivers need more or less time at stops
Click Save
New route calculations will use the updated values immediately

Technical Details¶

Module Dependencies¶

The sr_truck_schedule module depends on:

Module	What It Provides
website	Web controller infrastructure
sr_management	Core models: `customer.pickups`, `fleet.vehicle`, `res.partner`, customer regions, warehouses
sr_scheduling	The `truck.schedule` model, ORS routing engine (`ors.routing`), map helper utilities, Calendars menu structure

Models Extended¶

Model	What This Module Adds
fleet.vehicle	`set_samsara_vehicle_code()` method and button — matches Odoo vehicles to Samsara by license plate
customer.pickups	Calendar data preparation, TSP route optimization, Samsara route creation/update, itinerary generation, distance/time calculations
res.config.settings	Three new settings fields: trip start time, time at pickup location, Samsara API key

Key Python Methods¶

Method	Model	Purpose
`prepare_truck_schedule_data()`	customer.pickups	Queries all non-cancelled pickups, groups by truck and date, returns FullCalendar-formatted event data
`get_sorted_pickups()`	customer.pickups	Runs TSP optimization on a set of pickups for a given truck and date, returns optimized stop order with distances and times
`_build_distance_matrix()`	customer.pickups	Creates an N-by-N distance matrix using ORS routing for all locations on a route
`_solve_tsp_nearest_neighbor_improved()`	customer.pickups	Nearest-neighbor TSP with 2-opt improvement. Returns optimized stop indices.
`generate_itinerary()`	customer.pickups	Takes optimized pickups and calculates arrival, departure, start times for each stop
`generate_manual_itinerary()`	customer.pickups	Same as above but for manual mode — skips routing, uses sequential timing
`_create_samsara_route()`	customer.pickups	POSTs a new route to the Samsara API
`_update_samsara_route()`	customer.pickups	PATCHes an existing Samsara route with updated stops
`set_samsara_vehicle_code()`	fleet.vehicle	Fetches all Samsara vehicles and matches by license plate

JavaScript Components¶

Component	File	Purpose
CustomCalendarMenu	`fullCalendarMenu.js`	Main calendar page. Loads FullCalendar, fetches pickup data from the server, renders events, handles event clicks.
scheduleDialog	`scheduleDialog.js`	Popup dialog with two tabs (Pickup Details table and Leaflet Map). Draws route markers and routing lines using ORS.

Security¶

Access Control¶

The Truck Schedule Calendar does not define its own security groups or access rules. Access is controlled through the parent modules:

Group	Calendar Access	Set Samsara Code	Change Settings
Dispatcher (`sr_management.group_dispatcher`)	Full access — can view calendar, open routes, and click through to pickup/customer records	Yes — the button is restricted to this group	No
Manager (`sr_management.group_manager`)	Full access	Yes (implied from Dispatcher)	Yes — Settings page requires Manager or System Admin
System Administrator (`base.group_system`)	Full access	Yes	Yes
CSR (`sr_management.group_customer_service_rep`)	Can view the calendar but cannot modify truck schedule records	No	No
Driver (`sr_management.group_driver`)	Cannot access the calendar menu (no menu visibility)	No	No

The Calendar Is Read-Only

The calendar itself is a read-only visualization. You cannot drag, drop, resize, or edit events on the calendar. All changes to pickups, truck assignments, and routes are made through the pickup form or truck schedule form. The calendar simply reflects the current state of all scheduled pickups.

Troubleshooting¶

"No Matching truck found with this license plate in Samsara"¶

This error appears when clicking Set Samsara Vehicle Code on a fleet vehicle. It means the license plate in Odoo does not match any vehicle in Samsara.

Verify the license plate field on the Odoo vehicle record
Check Samsara's vehicle list to confirm the plate is entered there
License plate matching is exact — "C896HR" is different from "c896hr" or "C896 HR"

Calendar shows no events¶

Verify that pickups exist with a truck assigned and a pickup date set
Cancelled pickups are excluded — check that the pickup stage is not "cancelled"
Confirm the current user has permission to view customer.pickups records

Route optimization returns unexpected results¶

Check that all customers on the route have valid latitude/longitude coordinates
If coordinates are missing, open the customer record and trigger geocoding (the system attempts this automatically, but manual intervention may be needed)
The ORS routing engine uses real road networks — routes that look strange on a map may follow truck-legal roads that avoid restricted bridges or tunnels

Samsara route push fails¶

Verify the Samsara API Token in Settings is valid and not expired
Ensure the Samsara Driver Code is set on the driver's employee record
Ensure the warehouse has a valid Samsara Address Code
Check the error message — the Samsara API response is displayed in the validation error
Common issues: expired token, driver not active in Samsara, warehouse address not registered in Samsara

Map tab shows no route lines¶

The Leaflet map requires customer coordinates. If markers appear but no route lines are drawn, the ORS routing service may be unavailable or rate-limited.
Check the browser developer console for network errors to the ORS API.