Speed Limit Zone Configuration

Speed limit zones allow you to automatically restrict vehicle speed in designated areas. When a vehicle enters a speed zone during an active ride, the system sends IoT commands to the vehicle to limit its maximum speed. When the vehicle exits the zone, speed is restored to normal.

Key Features

Common Use Cases

Speed Limit Hierarchy

Understanding how speed limits are determined is crucial for proper configuration. Levy Fleets uses a hierarchy of settings.

The Speed Limit Formula

Effective Speed = min(
  Zone Speed Limit,           // From the speed_limit zone
  Slow Speed Zone Threshold,  // From subaccount settings
  Vehicle Model Max Speed     // From vehicle_models table
)

The system always applies the lowest applicable limit to ensure safety.

Priority Order

1. Zone-specific speed limit - The speed_limit_kph value set on the zone
2. Subaccount slow-speed threshold - The slow_speed_zone_limit_kph setting (default: 10 km/h)
3. Vehicle model maximum - The max_speed_kmh from the vehicle's model

Example Scenarios

Creating Speed Limit Zones

Speed Limit Guidelines

Valid Speed Range

• Minimum: 1 km/h
• Maximum: 80 km/h (database constraint)
• Recommended: 5-20 km/h for most safety zones

Subaccount Speed Settings

Each subaccount has a global slow-speed zone threshold that acts as a ceiling for all speed zones.

Accessing the Setting

1. Go to Dashboard -> Settings
2. Navigate to the Vehicles section
3. Find Slow Speed Zone Limit

Behavior

This setting defines:

• The maximum speed that any speed zone can enforce
• The default speed when a zone doesn't have a specific limit set
• A global safety cap for your entire fleet in that location

Recommendations

Vehicle Model Speed Settings

Each vehicle model can have a maximum speed configured, which is used when restoring speed after exiting zones.

Configuration

Vehicle model speed is set in the Vehicle Models section:

1. Navigate to Dashboard -> Vehicle Models
2. Select a model
3. Set the Maximum Speed (km/h) field

Fallback Behavior

If a vehicle doesn't have a model assigned or the model has no max speed:

1. Check the vehicle's own max_speed_kmh field
2. Fall back to the system default: 25 km/h

Why This Matters

When a vehicle exits a speed zone, the system needs to know what speed to restore. The restoration command uses:

Restored Speed = vehicle_model.max_speed_kmh OR vehicle.max_speed_kmh OR 25 km/h

How Speed Enforcement Works

Enforcement Trigger

Speed enforcement runs on every GPS telemetry update when:

1. The vehicle is in an active ride (ride_status = 'in_progress')
2. The vehicle has a valid IoT IMEI
3. Valid GPS coordinates are received

Enforcement Steps

1. Load all speed_limit zones for vehicle's subaccount
2. Check if vehicle location is inside any zone polygon
3. If in any speed zone(s):
   • Calculate effective limit (lowest of zone + threshold)
   • If limit differs from current, send IoT speed command
   • Update vehicle state
   • Log zone entry event
   • Send customer notification
4. If was in speed zone but no longer:
   • Send restore speed command
   • Clear vehicle state
   • Log zone exit event
   • Send customer notification

Command Deduplication

To prevent unnecessary IoT traffic:

• Commands are only sent when the limit actually changes
• The vehicle's current zone state is tracked in the database
• Repeated updates for the same zone/limit are skipped

Vehicle tracking fields:

• current_speed_limit_zone_id - ID of the active speed zone
• current_speed_limit_kph - Currently enforced speed limit
• speed_limit_enforced_at - Timestamp of last enforcement

Latency

Typical enforcement latency:

• Telemetry arrival: 1-5 seconds (depends on device reporting interval)
• Zone evaluation: < 100ms
• IoT command dispatch: 200-500ms
• Vehicle response: 1-3 seconds (depends on device/network)

Total: 3-10 seconds from zone entry to speed change

IoT Protocol Commands

Different IoT devices require different command formats. Levy Fleets automatically detects the protocol and formats commands appropriately.

Supported Protocols

Protocol Detection

The system determines the protocol by querying the IoT device type. Protocol is determined from iot_type or iot_model fields (case-insensitive matching).

Speed Restoration

When a vehicle exits all speed zones, the system restores normal operating speed.

Restoration Process

1. Detect zone exit - Vehicle no longer in any speed zone
2. Calculate target speed from vehicle model or default (25 km/h)
3. Send restore command - Same format as limit command, with higher value
4. Clear vehicle state - Remove zone tracking fields
5. Log exit event
6. Send notification:

   Title: "Slow zone cleared"
   Body: "You have exited {zone_name}. Your top speed is restored."
   

Restoration Timing

Speed is restored:

• Immediately after the first GPS reading outside all speed zones
• No hysteresis delay (unlike no-go zones)
• Command sent regardless of zone entry duration

Overlapping Speed Zones

When a vehicle is inside multiple speed zones simultaneously, special rules apply.

Behavior

1. Find all applicable zones that contain the vehicle
2. Calculate effective limit for each zone (zone limit or threshold, whichever is lower)
3. Apply the lowest limit among all overlapping zones

Example

Vehicle enters an area with:

• Zone A: 15 km/h limit
• Zone B: 8 km/h limit
• Subaccount threshold: 10 km/h

Evaluation:

• Zone A effective: min(15, 10) = 10 km/h
• Zone B effective: min(8, 10) = 8 km/h
• Applied limit: 8 km/h (lowest)

Zone Tracking

Only the "active" zone (the one with the lowest limit) is tracked in the vehicle state.

Transition Behavior

When moving between overlapping zones:

• New limit command only sent if the effective limit changes
• Same-limit transitions are deduplicated (no IoT traffic)
• Exit event logged for the previous zone, entry event for the new zone

Best Practices

Zone Design

1. Size appropriately

   • Minimum: 20-30 meters diameter (GPS accuracy buffer)
   • Maximum: Practical for the area (city block, not city-wide)

2. Simple polygons

   • Use fewer vertices (5-8 typically sufficient)
   • Avoid complex shapes with many concave sections
   • Simpler shapes = faster evaluation

3. Clear boundaries

   • Align with physical features (streets, buildings)
   • Use satellite view for accuracy
   • Add 5-10m buffer for GPS variance

4. Strategic placement

   • Focus on high-pedestrian areas
   • Cover entire zones, not just hotspots
   • Consider entry/exit points

Speed Selection

1. Match the environment

   • Pedestrian-only: 5-8 km/h
   • Mixed pedestrian/vehicle: 10-12 km/h
   • Light traffic: 12-15 km/h

2. Consider customer experience

   • Too slow = frustrated customers
   • Too fast = safety concerns
   • Test limits in real conditions

3. Regulatory compliance

   • Check local regulations for e-scooter speeds
   • Many cities mandate specific limits in certain zones
   • Document zone purposes for audits

Naming Conventions

Use descriptive names that include:

• Location identifier
• Purpose/type
• Speed limit (optional)

Examples:

• "Downtown Core - 10 kph"
• "Lincoln Elementary School Zone"
• "Central Park Shared Path"
• "City Hall Plaza Pedestrian"

Testing

Before deploying critical zones:

1. Create zone with test vehicle
2. Ride through zone boundary multiple times
3. Verify speed reduction on the vehicle
4. Check zone events in ride history
5. Test exit and speed restoration
6. Confirm customer notifications work

Monitoring and Debugging

Dashboard Visibility

Ride Detail View:

• Navigate to Dashboard -> Rides -> [select ride]
• Click the "Zones" tab
• View zone entry/exit events with:
  • Zone name and type
  • Entry/exit times
  • Speed limits applied
  • IoT command success/failure

Finding Active Speed Restrictions

In the dashboard, you can view which vehicles currently have speed restrictions applied by checking the vehicle details page.

Server Logs

Enable detailed zone logging by checking server logs for entries with:

• Zone enforcement started/completed
• Point-in-polygon checks
• IoT command dispatch
• Success/error status

Log prefixes:

• [Zones] - All zone enforcement logs
• Speed zone detection indicators
• IoT command dispatch
• Success/Error markers

Troubleshooting

Speed Not Limiting

Symptoms: Vehicle doesn't slow down in speed zone

Checks:

1. Zone configuration:

   • Is the zone type "speed_limit"?
   • Is the zone polygon correctly drawn?
   • Is speed_limit_kph set?
   • Is the zone not deleted?

2. Vehicle setup:

   • Does the vehicle have an IoT IMEI?
   • Is the IoT device online?
   • Is the protocol supported (Segway, OKAI, etc.)?

3. Ride state:

   • Is there an active ride on this vehicle?
   • Is the ride status "in_progress"?

4. Environment variables:

   • Is IoT API configuration correct?
   • Is the IoT proxy URL correct?

5. Logs:

   • Check server logs for zone entries
   • Look for command dispatch errors

Speed Not Restoring

Symptoms: Vehicle stays at low speed after exiting zone

Checks:

1. GPS accuracy:

   • Is the vehicle truly outside the zone?
   • Check vehicle's last known coordinates
   • Compare to zone boundary

2. Database state:

   • Check current_speed_limit_zone_id - should be NULL
   • If not NULL, enforcement may still think vehicle is in zone

3. IoT command:

   • Was restore command sent?
   • Did it succeed?
   • Check ride zone events for exit event

4. Vehicle hardware:

   • Some devices require manual restart after command
   • Check device documentation for quirks

Wrong Speed Applied

Symptoms: Speed limit is different than configured

Checks:

1. Slow-speed threshold:

   • Check Settings -> Vehicles -> Slow Speed Zone Limit
   • This caps all zone limits

2. Overlapping zones:

   • Is vehicle in multiple speed zones?
   • Lowest limit is applied

3. Unit confusion:

   • Speeds are in km/h, not mph
   • 10 km/h is approximately 6 mph

Commands Not Sending

Symptoms: Zone events logged but no IoT commands

Checks:

1. Protocol detection:

   • Check IoT devices table for the IMEI
   • Verify IoT type is recognized

2. API connectivity:

   • Test IoT proxy manually
   • Check for firewall issues

3. IMEI validity:

   • 15-digit format required
   • Must match device registration

Frequently Asked Questions

How quickly does speed limiting take effect?

Typically 3-10 seconds after entering a zone, depending on:

• Vehicle's GPS reporting interval (1-10 seconds)
• Network latency
• IoT device response time

Can I set different speeds for different times of day?

Not directly through zone configuration. Current options:

• Create multiple zones and enable/disable via API
• Adjust the subaccount slow-speed threshold (affects all zones)
• Future: Time-based zone rules are on the roadmap

What happens if IoT communication fails?

• The zone event is still logged with iot_command_success = false
• The error is recorded
• The vehicle continues at its current speed
• Next telemetry update will retry the command
• Consider implementing alerts for failed commands

Do speed zones affect all vehicles?

Only vehicles:

• With an active ride
• Belonging to the zone's subaccount
• With a compatible IoT device

Vehicles without active rides are not affected.

Can customers see speed zones on the app?

Yes, speed zones are visible on the customer map:

• Displayed as yellow/gold colored zones
• Zone name shown on tap
• Speed limit displayed in zone info

What's the minimum recommended zone size?

• Minimum: ~30 meters diameter
• Reason: GPS accuracy variance (5-15m)
• Very small zones may cause flickering

How do I disable a speed zone temporarily?

Options:

1. Delete the zone - Remove it entirely (soft-delete)
2. Change zone type - Switch to "parking" or another type temporarily
3. Via database - Set deleted_at to current timestamp

Are speed limits enforced for test rides?

Yes, all rides with status "in_progress" are subject to zone enforcement, including test rides started by staff.

What's Next?

• Creating and Managing Zones - Complete zone management guide
• How Zones Work - Technical deep dive into zone enforcement
• Vehicle Telemetry - Understanding vehicle data