# OCPP Troubleshooting Guide

## Overview

This guide provides a systematic approach to troubleshooting OCPP-related issues with amina charging stations. Follow the steps in order to efficiently identify and resolve problems.

## Troubleshooting Workflow

```{figure} images/ts1.png
:align: center
:name: ts_flow

Image 1: Troubleshooting Flow
```

---

## Step 1: Check LED Signal

The LED on the charging station provides immediate visual feedback about its operational status.

### LED Status Quick Reference

Refer to the detailed [LED Signal Details](#led-signal-details) section below for complete information.

**Key LED States:**

- **White (blinking patterns)** = Boot/Setup sequence
- **Green/White (alternating)** = Authorization in progress
- **Green (steady/blinking)** = Waiting for EV
- **Blue (steady)** = Charging active
- **Orange** = Warning condition
- **Red** = Error condition
- **Purple** = Firmware update
- **Yellow (10 blinks)** = Authorization failed

**Action**: Note the LED status and refer to your **User & Installer Guide** or the [LED Signals](#led-signal-details) section below for detailed information.

---

## Step 2: Check CSMS OCPP Logs

With the LED status as supporting data, examine the OCPP logs in your CSMS for the affected charging station.

### What to Look For in OCPP Logs

**Recent Messages:**
- StatusNotification
- Error Codes
- Boot Notifications

**Connection Status:**
- Last Seen Online
- Disconnect Events
- Reconnection Attempts

**Configuration Changes:**
- ChangeConfiguration
- GetConfiguration
- Setting Modifications

**Transaction Events:**
- StartTransaction
- StopTransaction
- Authorization Failures

### Key Log Analysis Steps

1. **Identify the time frame**: When did the issue start occurring?
2. **Check error messages**: Look for StatusNotification messages with error codes
3. **Review connection history**: Determine if the device has been offline
4. **Examine recent changes**: Check for configuration updates or system changes

---

## Step 3: Review OCPP Settings

Certain OCPP configuration settings may impact charging station behavior.

### Common Settings to Verify

**Connection Settings:**

- HeartbeatInterval
- Cst_AuthorizationTimeout
- WebSocketPingInterval

**Authorization Settings:**

- Cst_FreeVendActive
- AuthorizeRemoteTxRequests
- LocalAuthListEnabled
- AllowOfflineTxForUnknownId
- Cst_AuthorizationTimeout

**Transaction Settings:**

- StopTransactionOnEVSideDisconnect
- StopTransactionOnInvalidId

**Reference**: See the complete [OCPP Settings](ocpp-settings.md) documentation for detailed information on all configuration parameters.

### Settings Check in Logs

Look for:
- Recent `ChangeConfiguration` messages that may have modified critical settings
- `GetConfiguration` responses showing current values
- Settings that differ from your expected configuration

---

## Step 4: Check for Recent Configuration Changes

Review OCPP logs for any configuration modifications that might explain the behavior.

**Look for this sequence in the logs:**

1. **ChangeConfiguration.req** (CSMS to Charger)
   - What setting changed?
   - When did it change?

2. **ChangeConfiguration.conf** (Charger to CSMS)
   - Was the change accepted?

3. **StatusNotification** (if applicable)
   - Did the charger behavior change after the configuration update?

---

## Additional Troubleshooting: Offline and Reconnection Issues

If the issue involves connectivity or offline status, use this specific troubleshooting approach in combination with the main workflow above.

### Reconnection Behavior

**Important**: Amina chargers automatically attempt to reconnect to the CSMS every **30 minutes** when offline.

**Device Offline Timeline:**

1. **Last Seen Online** - Check OCPP logs for the last HeartBeat or message
2. **Disconnect Event** - Identify when the connection was lost, typically in server (CSMS) logs
3. **Reconnection Attempts** - Automatic attempts every 30 minutes
4. **Current Status** - Is the device online or still offline?

### Offline Troubleshooting Checklist

1. **Determine last online time**: Check OCPP logs for the last received message timestamp
2. **Calculate offline duration**: How long has the device been offline?
3. **Check reconnection attempts**: Look for WebSocket connection attempts every ~30 minutes
4. **Verify network connectivity**: Is the device location experiencing network issues? Use the eSim/MVNO portal


---

## Step 5: Update to Latest Firmware

Before contacting support, ensure your charging station is running the latest firmware version. Many issues are resolved through firmware updates that include bug fixes, stability improvements, and new features.

### Check Current Firmware Version

1. **Via CSMS**: Check the firmware version in your CSMS device information
2. **Via OCPP Logs**: Look for BootNotification messages which include the firmware version

### Latest Firmware Information

**Important**: Always update to the latest firmware version before reporting issues to support.

- **Latest Version**: See [Firmware Changelog](changelog-public.md#latest-fw-version) for the current version
- **Release Notes**: Review the changelog to see if your issue is addressed in recent updates
- **Download Link**: Available in the [Firmware Changelog](changelog-public.md)

### Update Methods

**OTA (Over-The-Air) Update:**

Most firmware versions can be updated remotely via OCPP using the `UpdateFirmware` message from your CSMS.


### After Update

1. **Wait for update to complete**: Firmware updates take roughly 10 minutes over Ethernet, 15 minutes over LTE and 20 minutes over Wi-Fi
2. **Device will reboot**: After installation, the device will restart automatically
3. **Verify new version**: Check BootNotification in logs to confirm the new firmware version
4. **Test the issue**: Reproduce the original problem to see if it's resolved

**Recommendation**: Deploy firmware updates using a "rolling update" approach to identify issues early before impacting all chargers.

---

## Step 6: Contact Support

If the issue remains unresolved after updating to the latest firmware and following all the steps above, contact amina support with the following information:

### Information to Provide

**Device Details:**

- Serial Number
- **Firmware Version** (confirm it's the latest version from [changelog](changelog-public.md))

**Issue Description:**

- LED Status
- When Started
- Frequency
- User Impact

**OCPP Data:**

- Recent Error Codes
- Last Seen Online
- Configuration Settings
- Relevant Log Excerpts

**Troubleshooting Done:**

- Steps Attempted
- Results Observed
- Changes Made

### How to Contact Support

See the [Support](support.md) page for contact information and support channels.

---

## LED Signal Details

### Boot and Startup States

| LED Status | Meaning | Description |
|------------|---------|-------------|
| No light / No power | Charger has no power | Check power connection and circuit breaker |
| 1 white blink every 4 sec | Starting | Charger is powering up |
| 2 white blinks every 4 sec | Connecting | Searching and connecting to network (4G LTE) |
| 3 white blinks every 4 sec | Connecting to CSMS | Searching for connection to Charge Point Operator |
| Continuous rapid white blinking | Charging current not set / Factory reset | Current wheel is in position 0 - set charging current |

### Connection and Normal Operation States

| LED Status | Meaning | OCPP Status | Action Required |
|------------|---------|-------------|-----------------|
| Steady White | Standby | Connected to CSMS, no vehicle connected | None - Normal operation |
| Steady Green | Vehicle connected | Available - ready to charge | None - Normal operation |
| Blinking Green | Charging in progress | Charging | None - Normal operation |
| Steady Blue | Charging | Charging - power delivered | None - Normal operation |

### Authorization States

| LED Status | Meaning | Description |
|------------|---------|-------------|
| Alternating Green/White | Awaiting authentication | Waiting for authorization with RFID or app |
| Rapid alternating Green/White | Authenticating | Authorization in progress |
| 10 rapid Yellow blinks | Authorization failed | User authorization failed - check RFID or app |

### Warning States

| LED Status | Meaning | OCPP Error Code | Action Required |
|------------|---------|-----------------|-----------------|
| Steady Orange | Ground Failure (RCD-DC leakage) | GroundFailure | DC leakage detected. Disconnect vehicle and try again with another vehicle. If error persists, contact installer. See [Error Codes](ocpp-error-codes.md#groundfailure) |
| Blinking Orange | Vehicle error | EVCommunicationError | Unplug charger and try connecting again. If error persists, contact installer. See [Error Codes](ocpp-error-codes.md#evcommunicationerror) |

### Critical Error States

| LED Status | Meaning | OCPP Error Code | Action Required |
|------------|---------|-----------------|-----------------|
| Steady Red | General error | HighTemperature / OverCurrentFailure | The charger has detected an error. Unplug charger and try connecting again. If error persists, contact installer. See [Error Codes](ocpp-error-codes.md) |
| Blinking Red | Relay error | PowerSwitchFailure | **Critical error - Product must be replaced**. One or more relays have malfunctioned. No one should touch the charger until power has been turned off. Contact installer immediately. See [Error Codes](ocpp-error-codes.md#powerswitchfailure) |

### Other States

| LED Status | Meaning | Description |
|------------|---------|-------------|
| Steady Purple | Updating | The charger is updating its firmware |
| Alternating Red/White | Invalid wiring | Unsupported installation of electrical wiring - contact installer |

---

## Quick Reference: Common Issues

### Issue: Charging Won't Start

```{figure} images/ts2.png
:align: center
:name: ts_flow

Image 2: Troubleshooting Flow
```

### Issue: Device Offline

```{figure} images/ts3.png
:align: center
:name: ts_flow

Image 3: Troubleshooting Flow
```

### Issue: Unexpected Transaction Stops

```{figure} images/ts4.png
:align: center
:name: ts_flow

Image 4: Troubleshooting Flow
```

---

## Additional Resources

- [OCPP Error Codes](ocpp-error-codes.md) - Complete error code reference
- [OCPP Settings](ocpp-settings.md) - Configuration parameters guide
- [OCPP Implementation](ocpp.md) - General OCPP information
- [OCPP Authorization](ocpp-auth.md) - Authentication and authorization details
- [OCPP CSMS Migration](ocpp-csms-migration.md) - Migrate to new CSMS
- [OCPP Root CA Bundle](ocpp-root-ca-bundle.md) - Supported Certificates in Root CA Bundle
- [Support](support.md) - Contact information and support resources