Low Battery Handling

Low battery handling involves three independent controls:

1. A Minimum Battery Percent that hides low-charge vehicles from riders so they can't be rented.
2. An Active ride low-battery shutdown that warns riders, pauses motor power at your cutoff, then ends the ride after a short grace period.
3. A Low battery alert that emails your ops team when an available vehicle needs charging.

They live in different places and have separate thresholds. This guide covers all three.

Overview

When a vehicle's battery drops below the minimum threshold, it's automatically hidden from the mobile app. If active ride shutdown is enabled, an in-progress ride gets a warning before the cutoff, is paused with motor power disabled at the cutoff, and is automatically ended after the grace period. These controls reduce support issues, preserve enough charge for retrieval or battery swaps, and improve customer satisfaction.

Recommended Operator Setup

Use these values as a starting point for scooter fleets where staff need enough remaining charge to find the vehicle and swap or recharge the battery:

This creates a clean progression: ops gets alerted first, active riders get warned next, motor power is disabled at the critical cutoff, and new riders cannot rent vehicles that are already too low.

Quick Setup Checklist

What Riders Experience

With the recommended values above:

1. At 15%, the rider receives a low-battery warning and is told to return soon.
2. At 10%, the ride is paused and scooter motor power is disabled so the rider can safely pull over.
3. About 1 minute later, the ride is automatically ended and final pricing is calculated.

For scooters, the low-battery pause uses motor/throttle disable instead of a wheel lock because the rider may still be moving when the battery cutoff is reached.

Key Features

• Automatic hiding - Low battery vehicles removed from customer view
• Active ride shutdown - Warn, pause, and then end rides before vehicles drain to 0%
• Configurable threshold - Set the minimum battery percentage per subaccount
• Email alerts - Notify your operations team when vehicles need charging
• Real-time monitoring - Battery levels updated via IoT telemetry
• Dashboard visibility - See all low battery vehicles in one view

How It Works

IoT device reports battery level
         ↓
System updates vehicle record
         ↓
Customer opens mobile app
         ↓
Nearby vehicles API checks each vehicle:
    Battery >= minimum threshold?
    ├── Yes → Include in nearby list
    │         Customer can see and unlock
    └── No  → Exclude from list
              Vehicle hidden from app

Active Ride Flow

Vehicle battery falls to warning threshold
         ↓
Rider receives low-battery warning
         ↓
Battery falls to shutdown threshold
         ↓
Ride is paused and motor power is disabled
         ↓
Grace period elapses
         ↓
Ride is auto-ended and final fare is calculated

Configuring the Minimum Battery (hide from riders)

Setting the Minimum Battery

Choosing a Threshold

Set this to the lowest charge at which a rider can still reasonably finish a trip on your fleet. Most operators set it between 5% and 10%. Going higher just hides rentable vehicles and costs you revenue.

Raise it only if your typical trips are long or chargers are sparse. Lower it if you rebalance and charge frequently.

Factors to Consider

1. Average ride distance - Longer typical rides need a higher threshold
2. Charging infrastructure - More chargers allow a lower threshold
3. Rebalancing frequency - Frequent rebalancing enables a lower threshold
4. Vehicle range - Larger battery capacity allows lower percentages
5. Customer expectations - Tourism fleets may want a small buffer

Active Ride Shutdown (stop before fully drained)

Enabling Active Ride Shutdown

What Happens

When enabled, the active ride billing job checks each active or paused ride's vehicle battery. The staged flow is:

• At or below the warning threshold, the rider gets a time-sensitive low-battery warning once per ride
• At or below the shutdown threshold, the ride is paused. Scooters use motor/throttle disable without engaging the wheel lock; lock-only bikes/e-bikes use their lock command because no throttle-only command is available.
• After the configured grace period, the ride is automatically ended and final pricing is calculated
• The ride is marked with a low-battery auto-end reason
• The out-of-zone abandonment fee is skipped for this automatic low-battery end

Choosing a Shutdown Threshold

Set the shutdown threshold high enough to leave a retrieval buffer, especially if your team swaps batteries in the field. Most scooter fleets should start around 10%, set the warning around 15%, and keep the grace period around 1 minute.

This threshold is separate from Minimum Battery Percent. If you want to prevent a vehicle from being rented below 8% but stop active rides at 10%, configure both values separately.

Email Alerts (notify your team)

Enabling Low Battery Alerts

Alert Triggers

Email Content

A low battery alert email lists, for each affected vehicle:

• Vehicle number
• Current battery percentage

It prompts your team to retrieve the listed vehicle(s) for charging. Multiple low vehicles in the same subaccount are grouped into one email.

Dashboard Monitoring

Viewing Low Battery Vehicles

1. Go to Dashboard → Vehicles
2. Click the Battery filter
3. Select Low Battery to see vehicles below the threshold

Dashboard Indicators

Map View

The map displays battery status for each vehicle:

• Color-coded markers by battery level
• Filter to show only low battery vehicles
• Quick access to vehicle details

Mobile App Behavior

What Customers See

When a vehicle is below the minimum battery threshold:

• Not visible on the map
• Not listed in nearby vehicles
• Cannot be scanned via QR code
• Cannot be unlocked via vehicle number

Customer Experience

Customer opens app in area with 10 vehicles
         ↓
3 vehicles are below the configured threshold
         ↓
Customer sees 7 available vehicles
         ↓
Hidden vehicles reappear once charged above the threshold

IoT Battery Reporting

Telemetry Updates

Battery levels are updated via IoT device telemetry. Reporting intervals vary by device, provider, and whether the vehicle is moving:

Data Fields

The system tracks multiple battery values:

Accuracy Considerations

1. Reporting lag - Some delay between actual and reported levels
2. Calibration - Battery percentage estimation varies by vehicle
3. Temperature effects - Cold weather affects readings
4. Age degradation - Older batteries may report inaccurately

Operational Best Practices

Proactive Charging

1. Monitor dashboard regularly - Check low battery counts
2. Set up email alerts - Get notified automatically
3. Schedule charging runs - Regular rebalancing routes
4. Track patterns - Identify high-drain areas

Charging Workflow

Response Priorities

This is a suggested triage order, not a system setting — adjust to your fleet:

Troubleshooting

Vehicles Not Hiding

1. Check the threshold - Verify Minimum Battery Percent on the Vehicles tab
2. Verify IoT reporting - Check the last telemetry timestamp
3. Confirm vehicle subaccount - The setting applies per subaccount
4. Check vehicle status - Must be "available" to be affected

Incorrect Battery Readings

1. Verify IoT connection - Check the device is reporting
2. Review telemetry data - Look for anomalies in logs
3. Check calibration - Some devices need recalibration
4. Contact IoT provider - May be a hardware issue

Alerts Not Sending

1. Verify the alert is enabled - Check Low battery alerts on the Alerts tab
2. Check the recipient email - Operational Alerts Email must be set
3. Confirm the alert threshold - The vehicle must be at or below it, and Available
4. Watch the 24-hour window - Each vehicle is only alerted once per 24 hours
5. Review email deliverability - Check spam folders

Rider Warning Not Sending

1. Confirm active ride shutdown is enabled - Check Settings -> Vehicles
2. Check the warning threshold - It should be greater than or equal to the shutdown threshold
3. Confirm push notification registration - The rider must have a valid push token
4. Check telemetry timing - If telemetry jumps from above the warning threshold directly below the shutdown threshold, the warning may be skipped and the ride may go straight to pause
5. Check per-ride deduping - The warning is sent once per ride to avoid repeated alerts

Ride Did Not Pause At The Shutdown Threshold

1. Confirm the latest vehicle battery - The system uses the latest vehicles.battery_level value from telemetry
2. Confirm the ride is still active - Already paused rides are not paused again
3. Check the subaccount - The setting is per subaccount, so verify the vehicle or ride is attached to the expected subaccount
4. Check cron execution - Active ride shutdown is evaluated by the active ride billing cron, not instantly at the exact telemetry timestamp

Ride Did Not Auto-End After Pause

1. Check the pause reason - The auto-end grace flow only applies to rides paused with low-battery reason
2. Check the grace period - The ride ends after the configured number of minutes has elapsed
3. Check cron execution - The next active ride billing cron run performs the auto-end
4. Check completion jobs - Ride completion uses the normal durable completion flow; if a completion job already exists, duplicate processing is skipped

API Reference

Get Nearby Vehicles (Mobile)

GET /api/mobile/vehicles/nearby?lat=40.7128&lng=-74.0060

Response only includes vehicles at or above the Minimum Battery Percent for the subaccount.

Vehicle Battery Data

{
  "id": "uuid",
  "vehicle_number": "V001",
  "vehicle_battery_pct": 85,
  "iot_battery_pct": 92,
  "last_telemetry_at": "2025-01-15T10:30:00Z"
}

Settings Structure

{
  "vehicles": {
    "minimum_battery_percent": 8,
    "active_ride_battery_shutdown": {
      "enabled": true,
      "threshold_percent": 10,
      "warning_percent": 15,
      "grace_period_minutes": 1
    }
  },
  "emails": {
    "operational": {
      "low_battery_alerts": true,
      "low_battery_alert_percent": 20
    },
    "recipients": {
      "operational_alerts_email": "ops@example.com"
    }
  }
}