# AutoPi Documentation

> Documentation for AutoPi devices, AutoPi Cloud, AutoPi Core, APIs, integrations and developer guides.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Accounts

---

Welcome to the Account Management guide. This section explains how to set up and manage your AutoPi cloud environment, including accounts, customers, users, devices, and access permissions. By the end of this guide, you’ll understand how to organize your platform efficiently while ensuring secure and controlled access for all users.

AutoPi Cloud uses a **multi-tenant architecture**, which means multiple accounts (tenants) share the same platform and infrastructure, while all data, configurations, and user access remain securely isolated.

---

## Account  
An Account represents your organization’s main account in AutoPi Cloud. Each account can have multiple customers, and you can easily create as many as needed.

![Account Information](/img/cloud/accounts/account_overview.png)

### Account Owner 
The account owner is typically associated with the email address used to purchase the AutoPi devices.

### General settings for Account creation
When creating an account, you configure:
* Name, email, and country
* Cloud settings, including: Time zone, Time format and Units. These settings define how data is displayed across the platform.

## Customers 
**Customer (Main Account)** - The Customer is the top level in the hierarchy and usually represents a company. Customers are used to define the organizational structure within an account.

Example: If your company is called AutoPi, you would create a Customer named AutoPi HQ.

### Nested Customer
**Nested Customers (Sub-Accounts)** - nested customers are sub-accounts under a main Customer. They are useful for companies with branches, departments, or divisions that need separate environments while remaining under the same main account.

The account section allows an account administrator to manage nested customers, which makes it possible to create an isolated account, assign devices and users to it, so that a customer can manage a fleet of devices, and it's own users.

It makes it possible to have a structure like this: 

```
Customer
    users:
        |_ user admin
    accounts:
        |_ nested customer A
            users:
                |_ user A
        |_ nested customer B
            users:
                |_ user B
```

The permissions model follows a top down approach, and only in that direction, this means that any users created on the nested customers, will only ever be able to see the devices directly associated to that account, at most, ie. full device access for a user on a nested account will see only the devices actually associated to the account, and not devices from the parent account / top account.

So in the example above, `user A` can only see devices in the `nested customer A` 
account, and the same for `user B`, but the `admin` user can see devices from both
the top account, and any nested customers.

#### Create customer
![Create nested customer](/img/cloud/accounts/create_nested_customer.png)

To create a new (nested) customer:
* Go to Accounts page and click on Customers tab.
* Click Create in the right upper corner.
* Enter the company name, main work email, and country. 
* Configure cloud settings (time zone, time format, units).
* Specify the security settings. 
* Confirm by clicking Create.
* A confirmation pop-up will appear once the customer is created successfully.

#### Assign Devices to the New Customer

Steps to assign devices to a customer: 
* Click Devices under Accounts page. 
* Click Manage devices in the upper-right corner.
* Choose a newly created customer. 
* Now select one or more devices from the dropdown, or toggle the mode below the dropdown to input the unit id or device ids and find the desired devices.
* After you are done with choosing devices, click Process. The devices are now re-assigned to the new customer. 

#### Create an Administrator User On the New Account

Steps to create an administrator account: 
* Click the Customers tab. 
* Click the customer that was created and you want to create an admin for. 
* Click Users to manage the users for the customer. 
* Click Create. 
* Now create a new user, and remember to set the account to have `Account Administrator` group permission, this will make the user have access to the assigned devices, and also to manage the users on the customer.

You should now have a nested customer with some devices associated, and admin user.

## Users
Users are the people who log in and interact with the platform. You can create multiple users under any Customer or Nested Customer.
With users, you can:
* Set permissions (groups)— decide who gets access to what.
* Assign users to locations — make sure they only see the data they need.
* Keep control — users under a Nested Customer won’t see data from the higher levels.

### Creating or editing a user 
![User creation modal](/img/cloud/accounts/create_new_user_updated.png)

To create a user:
* Go to Users and click Create
* Enter the user’s email and username
* Choose how to handle the password:
  * Send a welcome email (recommended): sends setup instructions automatically
  * Set a password manually (users should change it after first login)
* Select the Customer or Nested Customer the user belongs to
* (Optional) Add additional details such as full name or phone number
* Set the user status:
    * Active – user can log in (default).
    * Inactive – user cannot log in.
* Click Create. 

### Modifying User Permissions
![Group Permissions](/img/cloud/accounts/create_new_user_permissions.png)

Permissions define what actions a user can perform. Users are assigned to permission groups. Available permission groups include:

**1. Account Administrator** - manages the assigned customer account. This permission is best for team leaders managing users.
* Can create/edit/delete users.
* Manage permission groups associated with the users. 
* Access only to the Users and Accounts tabs (limited view).

**2. Full Device Access** - access to all devices and vehicles. This permission group needs to be paired with Device Management or Fleet Management to be fully useful. This permission is best for device specialists or fleet managers handling all vehicles.

**3. Device Management** - full access to the Device Management section of the cloud including Overview, Devices (no devices listed unless paired with Full Device Access), OBD Library and Templates. When combined with Full Device Access, you get the full device list and settings control. This permission is best for technicians managing devices directly.

**4. Nested Customer Administrator** - manages nested customers (sub-accounts). This permission is best for admins overseeing sub-branches or regional accounts. This permission works alongside:
* Fleet Manager — to create new nested customers and users.
* Account Administrator — to handle user creation.

**5. Fleet Management** - access to the Fleet Management section of the cloud including Overview; Vehicles - Vehicles List,Geofences, Groups; Locations; Reports; Users; Diagnostics; Alerts and Configurations - Dashboards, Fault Codes, Notification Channels, States. This permission is best for fleet managers that needs full access to their fleet. 

**6. Access Control Management** - access to the RFID token history. This feature is an add-on and therefore if you are interested in using this, you can contact us at sales@autopi.io .

### Assign Locations to Users
![Assigning locations to users](/img/cloud/accounts/create_new_user_location_access.png)

If you use Locations, users can be assigned access to one or more locations. This ensures users only see relevant data to the associated location.
Learn more about Locations here: [Locations](https://docs.autopi.io/cloud/fleet_management/locations/)

## Devices 
The Devices section lists all devices associated with your account. Clicking a device name opens its overview page.
Key actions include:
* Register device - add a new device to the account.
* Manage devices - manage the devices within the different nested customers.

![Manage devices](/img/cloud/accounts/manage_devices.png)

## API Tokens
API Token allows the user to access the [AutoPi's REST API](https://api.autopi.io). API tokens can be used in many ways, below are some examples: 
* [Getting started with REST API](https://docs.autopi.io/getting_started/api/)
* [Command webhook callbacks](https://docs.autopi.io/getting_started/api/command-webhook-callbacks/)
* [Change device's settings from the REST API](https://docs.autopi.io/getting_started/api/change-device-settings-from-api/)
* [Export data from API](https://docs.autopi.io/getting_started/api/export-data-from-api/)
* [Forward device data to your own server](https://docs.autopi.io/getting_started/api/send-device-data-to-own-server/)

![API Token creation](/img/cloud/accounts/create_api_token.png)

To create a token:
* Go to API Tokens tab.
* Click create. 
* Enter a name.
* Select an expiration date.
* Press create.

--
## Profile Settings
![Profile settings](/img/cloud/accounts/profile_settings.png)

### Profile 
In your profile settings, you can:
* View your email address and username
* Adjust cloud preferences: time zone, time format and units. These settings affect how timestamps and data are displayed across the platform.
* Change your password. 

### Security 
For enhanced security, AutoPi Cloud supports Multi-Factor Authentication (MFA):
* Use an authenticator app of your choice to protect your account.
* Users with Account Administrator permissions can enforce MFA for all users during login. This helps ensure secure access to your platform and data.

---

## Triggers

---

This guide introduces **Triggers** and explains how to **create and edit them** on your AutoPi device. Triggers allow you to receive notifications when specific events occur on your device or vehicle. They provide a flexible way to monitor vehicle activity and respond automatically to events. Notifications can be sent via **email** or **webhook requests**. In this guide, we will explain how triggers work and walk through an example where a notification is sent if a vehicle starts outside of working hours (8 PM – 8 AM).

![intro_pic](/img/cloud/device_management/triggers/a_guide_to_triggers/triggers_example.png) 

---

## What Are Triggers?

Triggers allow you to receive notifications when specific **events** occur on the device.

Whenever a device receives an event (for example `vehicle/engine/running`), the device sends the event and its associated data to the **AutoPi Cloud**. The Cloud system then processes the data and checks whether any configured triggers match the event tag and conditions.

A trigger consists of:
* **Event type or signal**
* **Event tag**
* **Optional conditions**
* **Actions**.

When the event matches the trigger and all conditions are satisfied, the configured **actions are executed**, such as sending an email or triggering a webhook. Triggers are configured and managed directly in the **AutoPi Cloud** under Device > Triggers. 

---

## Create a New Trigger

### Quick Setup

To create a new trigger:
1. Navigate to **Device → Triggers**.
2. Click **Create**.
3. Fill out the **basic information**.
4. Define **conditions** (optional).
5. Configure **actions**.
6. Click **Save**.

![Create New Trigger](/img/cloud/device_management/triggers/a_guide_to_triggers/create_new_trigger.png)

Below we will explain each step in more detail to help you understand how to configure a trigger correctly.

---

### Step 1: Fill Out Basic Information

The basic settings define what event will activate the trigger.

![Basic Information](/img/cloud/device_management/triggers/a_guide_to_triggers/trigger_basic_information.png)

* **Description**  
  A descriptive name for your trigger.  
  Example: `Vehicle started outside of working hours`.

* **Last Triggered**  
  Displays the last time the trigger was executed. This value is automatically updated and visible in the triggers overview.

* **Enabled**  
  Determines whether the trigger is currently active.

* **Type**  
  Specifies whether the trigger reacts to an **event** or a **signal**.

* **Tag**  
  The event tag that the trigger will react to. Examples:
    * `vehicle/engine/running`
    * `vehicle/engine/*` (using a wildcard).

---

### Step 2: Define Conditions (Optional)

Conditions allow you to control **when a trigger should execute**. A trigger can have **zero or multiple conditions**, and all conditions must be satisfied before the action is executed.

![Conditions](/img/cloud/device_management/triggers/a_guide_to_triggers/trigger_conditions.png)

In our example we configure two conditions:
* `@ts` **time less than** `08:00:00`
* `@ts` **time greater than** `20:00:00`

This means the trigger will activate if the vehicle starts **between 8 PM and 8 AM**.

#### Condition Fields Explained: 

**Field** - the name of a field available in the event data.

    * Example event data:

        ```json
        {
        "@rec": "2021-05-25T12:33:52.636385Z",
        "@t": "event.vehicle.engine",
        "@tag": "vehicle/engine/running",
        "@ts": "2021-05-25T12:33:42.686380Z",
        "@uid": "ee3df171-ff0f-6209-a3db-aa00b00e1d05",
        "@vid": 106
        }
        ```

    * Important fields include:
        * `@rec` – When the event was received by the cloud
        * `@ts` – When the event occurred on the device
        * `@uid` – Device unit ID
        * `@vid` – Vehicle ID

**Type** - defines the data type used for comparison. Different types include: string, int, datetime, bool, float, object and time. 

    * Example:
        * When using `@ts`, you may want to compare only the time, not the full timestamp. In that case you can change the type from: datetime → time. 

        :::note
        All timestamps are stored in UTC, so the comparison value must also use UTC.
        :::

**Not** - inverts the condition logic.

    * Example:
        * You can use that with the "field present" operator, to make a condition that only executes if the field is NOT present.

**Operator** - defines the comparison method. Some operators only apply to certain data types. For example, you would probably not use the comparison operators (greater than, etc.) for a string types. Different types of operators: 
    * field present
    * equals
    * greater than
    * greater than or equal
    * less than
    * less than or equal.
   

**Value** - the value used for comparison.

    * Examples:
        * some.field should "be present" (in this case no value is needed).
        * some.field should "equal" 1234.
        * some.field "greater than"0.

#### Example Condition Use Cases
Here are some examples of how to use conditions: 
* **Notify on engine start between 01:00 and 06:00 at night.** (Remember all times are UTC, so keep that in mind when creating the conditions. So if your timezone is UTC+2, the below conditions will in reality match between 03:00:00 to 08:00:00 local time.)

    ![conditions_example_1](/img/cloud/device_management/triggers/a_guide_to_triggers/conditions_example_1.jpg) 

* **Notify on device update (No conditions)**

    ![conditions_example_2](/img/cloud/device_management/triggers/a_guide_to_triggers/conditions_example_2.jpg) 

**Notify on all events (will only execute once every minute no matter how many events are received)**

    ![conditions_example_3](/img/cloud/device_management/triggers/a_guide_to_triggers/conditions_example_3.jpg) 

---

### Step 3: Configure Actions

Actions define what happens when the trigger is executed. Currently supported actions include:
* Send email
* Send webhook request.

![Actions](/img/cloud/device_management/triggers/a_guide_to_triggers/trigger_new_actions.png)

In this example we configure an email notification to: support@autopi.io .

#### Event Context Variables
When you speicfy you'd like to send a webhook request, you can specify the payload that is sent with the request. When specifying the payload, you can use the Jinja templating language to insert data that's passed by the trigger's context. Here's what the context can offer:

```
event #the event that got fired
    @vid: int - Vehicle ID of the vehicle associated with the device
    @uid: UUID - The Unit ID of the device
    @tag: string - Additional event information
    @t:   string - Type of the event
    @ts:  string - Timestamp from the device
    @rec: string - Timestamp of when the event was received

trigger # the trigger
    created:        date - When the trigger was created
    last_modified:  date - When was the trigger last modified
    last_triggered: date - The last time this trigger got executed
    last_error:     date - When was the last error for this trigger
    description:    string - A description of the trigger
    enabled:        boolean - Whether the trigger is enabled or not
    device:         Device - The device model
    interval:       duration - How often is the trigger allowed/going to trigger

# nested models
Device
    id:                 uuid - The device id
    unit_id:            uuid - The device's unit id
    callName:           string - The name of the device (user provided)
    vehicle:            Profile - The profile (vehicle) model
    last_communication: date - The last time this device was connected to the cloud

Profile (the vehicle the device is registered to)
    type:         string - The type of the vehicle
    vin:          string - Serial number of the vehicle
    model:        Model - The model of the vehicle
    year:         integer - The creation year of the vehicle
    callName:     string - The name of the vehicle (user provided)
    licensePlate: string - The license plate of the vehicle

Model
    make: Make - The make of the model
    name: string - The name of the model

Make
    name: string - The name of the make (BMW, Mercedes-Benz, Toyota etc.)
```

You can use these values in a payload like the following example:

```
{
    "payload": "{{ trigger['description'] }}",
    "device_uid": "{{ event['@uid'] }}"
}
```

which will translate into the following payload:

```
{
    "payload": "Description that you've specified when creating the trigger",
    "device_uid": "c3cce723-79ed-4897-80cf-4cd48b62b235"
}
```

Keep in mind that some events provide additional data in the `event` context, so there will be additional fields available. An example for such a scenario is the `vehicle/battery/discharging` event which has an `event.vehicle.battery.level` value showing a percentage value of the battery.

#### Example Action Use Case
Here are some examples on how to use actions:
* **Send email**

    ![actions_example_1](/img/cloud/device_management/triggers/a_guide_to_triggers/actions_example_1.jpg)

    * Here is how an example email from a trigger looks:

    ![actions_example_email](/img/cloud/device_management/triggers/a_guide_to_triggers/actions_example_email.jpg) 

* **Send webhook request**

    ![actions_example_2](/img/cloud/device_management/triggers/a_guide_to_triggers/actions_example_2.png)  

    * Address: Your unique Slack webhook address  
    * Payload: 
        ```
        {"text": "{{ trigger['description'] }} was executed, by device {{ trigger['device']['callName'] }}"}
        ```

    * The payload in this case will end up looking something like this when being sent to Slack:
        ```
        {
            "text": "your_trigger_description_here was executed by device your_device_callName"
        }
        ```

* **Send MQTT message via webhook (home assistant etc)**  
    * Check out this tutorial: https://www.home-assistant.io/blog/2017/03/28/http-to-mqtt-bridge/  
    * Address: heroku app address  
    * Payload: 
        ```
        {"topic":"<mqtt_topic>","message":"<mqtt_message>","key":"<AUTH_KEY>"}
        ```

* **Trigger IFTTT applet via webhook**  
    * Address: Find on https://ifttt.com/services/maker_webhooks/settings .
    * Payload: optional and custom based on the IFTTT applet.  

:::tip
Like all AutoPi's cloud functionality, triggers can be managed programmatically through the AutoPi REST API, here is how to start: [REST API](https://docs.autopi.io/getting_started/api/). For more information you can also check out this documentation: [API Automation](https://api.autopi.io/#/automation). 
:::

---

## Edit a Trigger
You can easily modify existing triggers. Here are the steps: 
* Navigate to Device → Triggers.
* Locate the trigger in the triggers table.
* Click the trigger row to open the editing dialog.
* Make your changes.
* Click Save.

![Edit a Trigger](/img/cloud/device_management/triggers/a_guide_to_triggers/edit_trigger.png)

You can also enable or disable triggers directly from the triggers table by clicking the toggle icon.

---

## Introduction

The configuration settings controls the behaviour of the [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) device.

:::note
Like any [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) functionality, configuration settings can be changed programmatically through the [AutoPi](https://www.autopi.io) REST API. For more information see our [API docs page](https://api.autopi.io/).
:::

This documentation provides an overview of the adjustable settings on the AutoPi Mini device, helping you optimize its functionalities for your vehicle type.

![Mini advanced settings](/img/cloud/device_management/advanced_settings/autopi_mini/mini_advanced_settings.png)

## Obd settings

| Name | Description | Default |
| ------ | ------ | ------ |
| Obd Feature | Specifies how the device communicates with the vehicle’s onboard diagnostics (OBD) system. | OBD (auto) |

:::tip
If you have an internal combustion engine (ICE) vehicle, select OBD (Auto) in the OBD Feature field. This is the default setting for all AutoPi Mini devices.
If you have an electric vehicle (EV), select Non-OBD Compliant in the OBD Feature field.
:::

## Obd Vin Settings

| Name | Description | Default |
| ------ | ------ | ------ |
| Vin | If the vehicle identification number (VIN) cannot be retrieved automatically, you can enter it manually. The VIN is a 17-character code consisting of digits and capital letters. | - |
| Vin source | Specifies how the VIN is obtained: either automatically from the device (Auto) or entered manually by the user (Manual). | Auto |

:::tip
If your device cannot automatically detect the VIN, you can enter it manually in the VIN field after selecting Manual for VIN Source.
:::

## System

| Name | Description | Default |
| ------ | ------ | ------ |
| Ignition settings | Specifies how the system detects vehicle ignition status. | Power Voltage or Engine RPM |

:::tip
If you have an ICE vehicle, select Power Voltage or Engine RPM as the ignition detection method.
If you have an EV, select Accelerometer for ignition detection.
:::

## Tracking 
This setting is used to determine if a vehicle has been driven by using these 2 sources: 
* Trip start/stop - created events for both trip start and trip stop that can be found under Device > Events; the whole trip taken can be seen in Vehicle > Trips.
* obd.rpm - values for RPM detected from the vehicle. 

| Name | Description | Default |
| ------ | ------ | ------ |
| Source | What data source should be used to determine if a vehicle/asset has been used/driven? Changing this will only apply to new data being logged. | Trip start/stop |

---

## Accelerometer

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SAMPLING RATE | How many samples per second? Increasing this will affect system performance negatively. Only change this value if you know what you are doing. | float | 12.5 | Hz |
| RANGE | Maximum number of g-forces being measured. | int | 8 | g |

## Gyroscope

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SAMPLING RATE | Gyroscope sampling rate. How often will the gyroscope sample new data? A value of 0 means the gyroscope is disabled. | float | 0 | Hz |
| RANGE | Maximum number of degrees per second that the gyroscope will measure. | int | 250 | deg/s |

## Logger

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| RETURNERS | Which [Cloud](https://www.autopi.io/software-platform/cloud-management) returner(s) should be used? | str |  | - |
| FILTER DUPLICATES | Filter out duplicate measurements? | bool | True | - |
| DECIMALS | More decimals means a lot more data. Be very careful about increasing this value. | int | 2 | - |

## Motion Events

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLE | Trigger motion events based on XYZ measurements? | bool | True | - |
| SHAKE PERCENTAGE | Percentage of positive motion detections required within duration period to conclude shaking. | float | 90 | % |
| SHAKE G THRESHOLD | G force threshold for shaking detection. Disabled when set to zero. | float | 0.01 | g |
| JOLT DURATION | How long in seconds should the G force threshold be observed over? | int | 1 | s |
| DEBOUNCE DELAY | Minimum delay in seconds between triggering events. | int | 1 | s |
| JOLT G THRESHOLD | G force threshold for jolting detection. Disabled when set to zero. | float | 0.6 | g |
| SHAKE DURATION | How long in seconds should the G force threshold be observed over? | int | 3 | s |

## Wake On Motion

Devices with a hardware version of **5.1** and earlier have the wake on motion available, this includes Gen 2 devices as well.

Devices with a hardware version of **5.2** and above **don't** support wake on motion.

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SENSITIVITY | The sensitivity of a trigger for the motions/jolts. Minimum value is 0 and maximum value is 127. The sensitivity value defines how much G force is required to trigger a wake event using the formula `sensitivity * 0.063 = G` | int | 5 | - |
| MODE | Enable the device to wake up whenever it detects motion or transient (jolt) acceleration of the device. Transient mode detects jolts (fast movements), while motion mode detects even slow and steady changes in accelerometer readings. | string | disabled | - |

#### Axes

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| Z | Wake if motion/jolt is detected on the Z axis. | bool | True | - |
| X | Wake if motion/jolt is detected on the X axis. | bool | True | - |
| Y | Wake if motion/jolt is detected on the Y axis. | bool | True | - |

---

## Alerts

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| EVENT TAGS | A list of events (expressed in regex) that should create alerts on the [Cloud](https://www.autopi.io/software-platform/cloud-management) system. Example: 'system/usb/.*/.*/(disconnected|not_connected)' | str | - | - |

---

## Audio

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SPEAK ALERTS | Let dongle speak out important events immediately when they occur. | bool | True | - |

---

## Bluetooth

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MODE | Setup bluetooth mode for the built-in device. Changes require a system reboot to take effect. | str | disable | - |

## Expansion

#### Le

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MAC ADDRESS | MAC address of the BLE device. | str | - | - |
| DEVICE | Specify Bluetooth Low Energy device provided by expansion board connected to the [AutoPi](https://www.autopi.io) main board. | str | - | - |

###### Firmware

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| VERSION | Version number of the BLE firmware release. | str | 3.2.1 | - |

###### Gatt Terminal

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ALLOW COMMAND REGEX | Specify regular expression for allowed command(s) that can be executed via the GATT terminal service. | str | - | - |

---

## Can Logging

## Disk Housekeeper

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Enable automatic disk cleanup to prevent the disk from running full? The oldest files will be deleted first. | bool | True | - |
| USE TARGET | Disk usage percentage which is the target to reach when deleting files. | int | 85 | % |
| USE LIMIT | Disk usage percentage which is the limit for when file deletion should begin. | int | 90 | % |
| CRITICAL USE LIMIT | Disk usage percentage that is considered critical and which causes an event to be triggered. | int | 95 | % |
| WORKER DELAY | Delay after startup before performing the first check for files to cleanup. | int | 60 | s |
| WORKER INTERVAL | Time period between each check for files to cleanup. | int | 60 | s |

## Frame Listener

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| WORKER INTERVAL | Time period between each check of the executing frame listener process(es). | int | 10 | s |
| WORKER DELAY | Delay at startup before executing of the frame listener process(es). | int | 0 | s |
| WORKER RUN AT | When should the frame listener process(es) be running? | str | startup | - |

## Output Handler

#### S3

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| WORKER INTERVAL | Time period between each check of the executing AWS S3 sync process(es). | int | 10 | s |
| WORKER DELAY | Delay after startup before executing of the AWS S3 sync process(es). | int | 60 | s |
| WORKER AUTO START | Enable automatic start of the AWS S3 sync process(es). | bool | True | - |

---

## Cellular

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| OVERRIDE | Overwrite all cellular settings that may already be specified on the device itself? | bool | False | - |

## Connection

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MTU | The MTU (Maximum Transmission Unit) to be used for the network connection. Only change this value if you know what you are doing. | int | 1500 | - |

#### Checker

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| PING ADDRESS | The address to ping when the state of the cellular connection is checked. | str | google.com | - |
| ONLINE INTERVAL | How often should the connection state be re-checked when already considered online? | int | 300 | s |
| OFFLINE INTERVAL | How often should the connection state be re-checked when already considered offline? | int | 30 | s |

## Sim

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| APN | The APN (Access Point Name) defines the network path for all cellular data connectivity. | str | internet | - |
| USERNAME | Optional username to be used togehter with the APN. | str | - | - |
| PASSWORD | Optional password to be used togehter with the APN. | str | - | - |
| PIN CODE | Optional PIN code required to unlock the SIM card. | str | - | - |

---

## Charging Session

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| REOPEN LIMIT | For how long time can an ended charging session be reopened? | int | 600 | s |

## Event

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| START TAGS | Which event tags can start a new charging session or reopen latest? Navigate to the Events page to view actual events for Device. | str | ['vehicle/engine/charging'] | - |
| END TAGS | Which event tags can end an active charging session? Navigate to the Events page to view actual events for Device. | str | ['vehicle/engine/not_charging'] | - |

---

## Cloud Storage

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| DEFAULT RETURNER | Which cloud returner should be used as default? Only change this value if you know what you are doing. | str | cloud | - |

## Https

#### Cache

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MAX BATCH SIZE | The maximum amount of entries to include in an upload batch. | int | 1000 | - |
| MAX RETRY | The maximum retry attempts before transferring batch to fail queue. Retry and fail queues are disabled if set to zero, meaning that pending will block until success. | int | 30 | - |
| FAIL TTL | How many days of retention before a fail queue is deleted? | int | 30 | d |

#### Compression

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| LEVEL | Integer from 0 to 9 controlling the level of compression; 1 is fastest and produces the least compression, and 9 is slowest and produces the most compression. 0 is no compression. | int | 9 | - |
| ALGORITHM | Compress data with selected algorithm before uploading. | str | None | - |

#### Endpoint

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| URL | The endpoint URL of the API where data is pushed to. | url | https://api.autopi.io/logbook/storage | - |
| AUTH TOKEN | The authentication token used in HTTP header when pushing data to the API. | str | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX | - |

#### Upload

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SPLAY | The maximum amount of time in seconds between consecutive uploads of batches. The actual delay is a randomly generated value between zero and the splay value. In error scenarios, the delay is increased by an incrementing factor. | int | 10 | s |
| INTERVAL | How often should cached data be uploaded to the cloud endpoint? | float | 60 | s |
| TIMEOUT | How long to wait for server to respond? | int | 60 | s |
| EVENT REGEX | In addition to repeated interval, upload data to cloud when event(s) occur. | str | ^system/power/(sleep\|hibernate\|reboot) | - |

## Jsonl Returner

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| FILENAME FORMAT | How should the JSONL files be named? | str | `{now:%y%m%d%H%M%S}_{pid}.jsonl` | - |
| DIRECTORY | In which directory should the JSONL files be stored? | str | /opt/autopi/data | - |
| FILE MODE | In which mode should new files be opened? | str | a | - |

#### Async File Writer

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| FLUSH TIMEOUT | Time limit for when the internal buffer should be written to disk. | int | 1 | s |
| FLUSH THRESHOLD | Size limit for when the internal buffer should be written to disk. | int | 5242880 | b |
| BUFFER HIGH WATERMARK | Size for buffer highwater mark warning. | int | - | b |
| BUFFER SIZE | Size of the internal buffer. | int | 52428800 | b |

#### File Rotation

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SIZE THRESHOLD | Size limit for when to rorate to a new file. | int | 524288000 | b |
| INTERVAL | Time interval for when to rorate to a new file. | int | - | s |
| CRON EXPRESSION | Cron expression for when to rotate to a new file. | str | 0 0 * * * | - |

## Jsonl Shipper

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Enable service for shipping JSONL files to cloud? | bool | False | - |

#### Cleanup

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| OLDER THAN | The minimum age before fully harvested JSONL files are removed. | int | 3600 | s |
| INTERVAL | How often should cleanup of harvested JSONL files be performed? | int | 3600 | s |

#### Input

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| PATHS | Where to crawl for JSONL files? | str | ['/opt/autopi/data/*.jsonl'] | - |

#### Output

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| USERNAME | The username for connecting to Kafka. | str | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX | - |
| HOSTS | Kafka broker addresses from where to fetch the cluster metadata. The cluster metadata contain the actual Kafka brokers messages are published to. | str | ['localhost:9093'] | - |
| PASSWORD | The password for connecting to Kafka. | str | XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX | - |

---

## Docker

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Enable support for docker containers. Enabling this will install balena-engine on the device. | bool | False | - |
| CONTAINER WHITELIST | A list of container names that will be whitelisted, so that the docker release process will not remove them during the deploy process. | str | - | - |

---

## Doip

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Enable the DOIP UDS service? | bool | False | - |
| NO GATEWAY | Do not use the 'eth0' interface as a default gateway. | bool | True | - |
| HOST | Hostname or IP of the TCP endpoint. | str | 127.0.0.1 | - |
| PORT | Port number of the TCP endpoint. | int | 13400 | - |
| TIMEOUT | Timeout of the TCP connection. | float | 0.1 | s |
| DEFAULT PIN SETUP | Choose between main or alternative configuration of DOIP pins in the OBD-II connector. | str | main | - |
| BOARD VERSION | Version of the installed DOIP HAT board. | str | 1.6 | - |

---

## Introduction(Advanced_settings)

The configuration settings controls the behaviour of the device.

:::tip
Like any AutoPi [Cloud](https://www.autopi.io/software-platform/cloud-management) functionality, configuration settings can be changed programmatically through the AutoPi REST API. For more information see our [API docs page](https://api.autopi.io/).
:::

You can control a lot of different things on the device. Each of the settings is explained in details on the following pages.

![AutoPi Cloud Configuration](/img/cloud/device_management/advanced_settings/autopi_tmu_cm4/intro/configuration.jpg)

---

## Key Fob

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| EXTENSION PORT | Which user extension port on the [AutoPi](https://www.autopi.io) main board is the key fob connected to? | int | 2 | - |
| ENABLED | Enable control of a key fob connected to the [AutoPi](https://www.autopi.io) main board. | bool | False | - |

## Button

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ACTIONS | Define available actions corresponding to the key fob buttons. | json | See below | - |

```json
[
  {"duration": 0.25, "name": "green", "pin": {"initial": true, "wire": "green"}},
  {"duration": 0.25, "name": "white", "pin": {"initial": true, "wire": "white"}},
  {"duration": 0.25, "name": "grey", "pin": {"initial": true, "wire": "grey"}},
  {"duration": 0.25, "name": "red", "pin": {"initial": true, "wire": "red"}},
  {"duration": 0.25, "name": "black", "pin": {"initial": true, "wire": "black"}}
]

## Pins

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| DELAY AFTER INITIALIZATION | Specify a delay after initialization of GPIO pins to ensure a pause before execution of any button actions. | int | 0 | s |
| RESET AFTER DELAY | How long time after powering off the key fob should the GPIO pins be reset (all pins set to low)? If a negative value is specified, no reset occurs. If set to zero, reset occurs immediately without any delay. | int | -1 | s |
| LAZY INITIALIZATION | Initialize GPIO pins lazily after first manual key fob power state check (or change) instead of during startup? | bool | False | - |

---

## Mqtt

## Broker

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| INSTALL | Run a local broker/server on the device? | str | none | - |

#### Bind

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ADDRESS | Specify which address the broker/server should bind to. | str | 0.0.0.0 | - |
| PORT | Specify which port the broker/server should listen on. | int | 1883 | - |

## Returner

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Enable MQTT returner for this device. The returner will automatically be added as hook in all services. | bool | False | - |

#### Connection

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| PROTOCOL | Specify the version of the MQTT protocol to use. | str | MQTTv311 | - |
| TLS | Enable SSL/TLS support? | bool | False | - |
| CLIENT ID | The unique client ID string used when connecting to the broker. | str | AutoPi-XXXXXXXXXXXX | - |
| PORT | The port of the broker to connect to. Note that the default port for MQTT over SSL/TLS is 8883. | int | 1883 | - |
| HOST | Specify the hostname or IP address of the broker. | str | localhost | - |

###### Authentication

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| PASSWORD | Password for broker authentication. | str | - | - |
| USERNAME | Username for broker authentication. | str | - | - |

###### Tls

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| CA CERTS | Path to the Certificate Authority certificate files that are to be treated as trusted. | str | - | - |
| CERT REQS | Defines the certificate requirements that the client imposes on the broker. | str | CERT_REQUIRED | - |
| VERSION | Specifies the version of the SSL/TLS protocol to be used. | str | - | - |
| CERT FILE | String pointing to the PEM encoded client certificate key. | str | - | - |
| KEY FILE | String pointing to the PEM encoded client private key. | str | - | - |
| CIPHERS | String specifying which encryption ciphers are allowable for this connection. | str | - | - |

---

## Obd

## Advanced

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| PRINT SPACES | Turn printing of spaces in OBD responses on or off. To get better performance, turn spaces off. | bool | True | - |
| ADAPTIVE TIMING | Set adaptive timing mode. Sometimes, a single OBD requests results in multiple response frames. The time between frames varies significantly depending on the vehicle year, make, and model - from as low as 5ms up to 100ms. | int | 1 | - |
| RESPONSE TIMEOUT | When adaptive timing is on, this sets the maximum time that is to be allowed, even if the adaptive algorithm determines that the setting should be longer. In most circumstances, it is best to let the adaptive timing algorithm determine what to use for the timeout. | int | 50 | ms |

## Can Database

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| PROTOCOL CONFIGURATIONS | Protocol-specific configurations used when loading a CAN database (from DBC file). | json | - | - |

## Elm327 Proxy

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| RESET AFTER USE | Reset the underlying STN subsystem after the proxy has been used? | bool | True | - |
| PORT | Specify which port to listen on. | int | 35000 | - |
| PAUSE WORKERS | Pause all OBD worker threads while the ELM327 proxy is being used? The threads will be resumed when the proxy is no longer in use. | bool | True | - |
| ENABLED | Enable the ELM327 proxy to support 3rd party mobile apps like Torque Lite/Pro on Android and Car Scanner on iOS. This is currently an experimental feature. | bool | False | - |

#### Logging

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| LEVEL | Change if you want more detailed logging. Please note that more logging can have a negative impact on performance. | int | 20 | - |
| FILE | The filename to which logs should be written. The default directory path is '/var/log/salt' if none other specified. Leave empty to disable logging. | str | elm327_proxy.log | - |

---

## Power

## Battery

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| READ INTERVAL | How often should the battery voltage be read out and checked? Disabled if set to zero. | int | 5 | s |

#### Critical Level

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| DURATION | How long should the specified voltage remain before triggering the 'vehicle/battery/critical_level' event. | int | 180 | s |
| VOLTAGE | Specifies the voltage threshold where the device should trigger the 'vehicle/battery/critical_level' event and then go into hibernation. To have any effect, this value must be greater than the safety cut-out voltage. | float | - | V |

## Firmware

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| VERSION | Version number of the power management firmware. | str | 3.1 | - |
| AUTO UPDATE | Automatic update of the firmware on the power management chip? | bool | True | - |

## Modem

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| POWER SAVE | Put modem into lower power mode during sleep? When enabled it is no longer possible to wakup device on SMS. | bool | True | - |

## Safety Cut-Out

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| DURATION | How long time should the specified voltage remain before taking effect? It is important that this value is lower than any sleep timer period, otherwise the device can power down normally before this condition is met. | int | 240 | s |
| VOLTAGE | Specifies at what voltage the device will be forcibly powered off to prevent battery drain. It is never recommended to go below 12.1 volts, as it may damage the battery and shorten its life. | str | 12.20 | V |

## Sleep Timer

#### Event Driven

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| INTERVAL | How long time should the device sleep before waking up again? | int | 3600 | s |
| REASON | Explanatory reason for sleeping. | str | engine_stopped | - |
| DELAY | How long delay before the actual shutdown takes effect? | int | 10 | s |
| PERIOD | How long time after the event has triggered should the device go to sleep? | int | 1800 | s |
| EVENT REGEX | On which event(s) should this sleep timer be enabled? | str | ^vehicle/engine/stopped | - |

#### Inactivity After Sleep

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| INTERVAL | How long time should the device sleep before waking up again? | int | 21600 | s |
| PERIOD | When waking up after sleep, how long time will the device stay awake before going to sleep again? | int | 300 | s |
| DELAY | How long delay before the actual shutdown takes effect? | int | 10 | s |

#### Inactivity Fallback

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| INTERVAL | How long time should the device sleep before waking up again? | int | 21600 | s |
| DELAY | How long delay before the actual shutdown takes effect? | int | 10 | s |
| PERIOD | How long time should the device stay awake until it is powered down due to inactivity? | int | 300 | s |

#### Suppress

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SCHEDULE | Specifies one or more time periods during which the device must be awake. Added sleep timers are adjusted accordingly to not sleep for the specified time periods. The format consists of a cron expression in UTC, then a pipe sign (\|) as separator and finally a duration in seconds. Example: 0 8 * * * | 7200 | str |  | - |
| EVENT REGEX | Which event(s) should disable current sleep timers and prevent new ones from being enabled? | str | ^vehicle/engine/running | - |

## Wake Trigger

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| VOLTAGE CHANGE | How much should the voltage change for the device to power up on engine start? Be careful about changing this parameter too much, as it could prevent your dongle from powering on. | str | +0.50 | V |
| VOLTAGE LEVEL | At what voltage level should the device power on? | - | - | V |
| VOLTAGE CHANGE DURATION | How long should the specified voltage change be observed before the device powers up on engine start? | int | 1000 | ms |
| VOLTAGE LEVEL DURATION | How long should the specified voltage level be observed before the device powers on? | int | 3 | s |

---

## Rfid

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Enable the RFID reader functionality for your device. | bool | False | - |
| AUTHORIZED TOKENS | A list of RFID authentication tokens. Follow timestamp,duration,rfid structure. Example: 2021-11-23T09:50:00,7200,0011252203 | str | - | - |

---

## System

## Display

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | If unused, disable HDMI display to conserve power. | bool | True | - |

#### Gpu

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MEMORY | Amount of memory that is addressable from the GPU. Set as low as possible to give the system as much memory as possible. | int | 16 | - |

## Filesystem

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| AUTO MOUNT USB | Automatically mount and and unmount USB mass storage devices? Mounted drives can be found on the filesystem below '/media'. | bool | - | - |
| EXPECTED USB DEVICES | Specify a list of devices' vendor and product IDs in the following format: `<vendor_id>:<product_id>`. Example: `0123:abcd` | str | ['2c7c:0125'] | - |

#### Swap

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Allocate more virtual memory by using a swap file? | bool | False | - |

## Locale

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| COUNTRY CODE | The overall (ISO) country code used on the device (in WiFi configuration etc). The default value is derived from the one specified in your customer profile. | iso_country_code | GB | - |

## Logging

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| LEVEL | The log level of the Salt Minion log. Change if you want more detailed logging. | str | warning | - |

#### Kernel

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| CLEAR BUFFER | Allow clearing of the kernel ring buffer when retrieving log entries? | bool | True | - |
| QUIET BOOT | Suppress display of all but very serious log messages during boot? | bool | True | - |

## Network

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| TCP MTU DISCOVERY | Configure Packetization Layer Path MTU Discovery (PLPMTUD) through the net.ipv4.tcp_mtu_probing system variable (0 - disabled; 1 - probe only when packets are dropped; 2 - probe always). Active in Core Version 1.24.3+. | int | 0 | - |
| ENFORCE CELLULAR MTU | Enforce the MTU defined for the cellular connection on all available network interfaces? | bool | False | - |
| DENY INTERFACES | Specify interfaces to deny in the 'dhcpcd' configuration. Enter 'veth*' to deny any virtual ethernet interfaces. | str | - | - |

#### Ethernet

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| STATIC IP | Specify a static IP address for the 'eth0' interface, if available. | str | - | - |
| DHCPCD ENTRIES | Specify additional 'dhcpcd' entries for the 'eth0' interface, if available. | str | ['metric 150'] | - |

#### Firewall

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENTRIES | Specify additional 'iptables' entries (IPv4). | str | - | - |

## Security

#### Decryption

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| FUNCTION | Qualified name of the function used to decrypt on the device. | str | - | - |

#### Encryption

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| KEY | Key used for encryption. It must be 16, 24, or 32 characters long. | str | - | - |
| ALGORITHM | Algorithm used for encryption. | str | AES | - |

#### Rsa

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| KEY SIZE | Specify bit size of RSA key pair to be generated for this device. | int | 0 | - |
| PRIVATE KEY | Private RSA key belonging to this device. | str | - | - |
| PUBLIC KEY | Public RSA key belonging to this device. | str | - | - |

## Setup

#### Mpcie

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MODULE | Specify which modem is installed in the Mini PCI Express slot. Change if you replace the modem. | str | ec2x | - |

## Time

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SOURCE | Choose strategy for how to keep track of the current time. | str | rtc | - |

#### Rtc

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| AUTO UPDATE | Allow automatic update of real-time clock after NTP synchronization? | bool | True | - |

## User

#### Pi

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| PASSWORD | Password for the pi user. | str | autopi2018 | - |

---

## Tailscale

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Enable the Tailscale VPN service? | bool | False | - |
| AUTH KEY | Specify the Tailscale auth key to be used by the device. Generate a new key on the Tailscale console below 'Settings' > 'Keys'. | str | - | - |

---

## Tracking

## Gnss

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| FIX FREQUENCY | Set the fix frequency of the GNSS engine. | int | 1 | Hz |

## Logger

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| FILTER DUPLICATES | Filter out duplicate measurements? | bool | True | - |
| RETURNERS | Which cloud returner(s) should be used? | str | ['cloud'] | - |
| INTERVAL | How often should the position of the vehicle be logged? The smaller the interval, the more data is potential logged. Disabled if set to zero. | float | 5 | s |

---

## Trip

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| REOPEN LIMIT | For how long time can an ended trip be reopened? | int | 600 | s |
| ACTIVE TRIP MAX AGE | The maximum trip age in seconds before it will be closed. Defaults to 90 minutes. | int | 5400 | s |
| DYNAMIC TRIP BUFFER | How long into the future should artificially closed trips be maximally extended to. Defaults to 60 minutes | int | 3600 | s |
| MIN BUFFER SPEED | Speed cutoff for how fast the vehicle should move before registered. Defaults to 5 km/h | int | 5 | km/h |
| MIN BUFFER INTERVAL | How many minutes between each interval should we count in a batch to take average traveling speed for. Defaults to 5 minutes | int | 5 | min |
| MAX TRIP OFFSET | Max distance for last position to be used when determine trip start position | int | 20 | km |
| ENABLE TRIP OFFSET | Enable the max distance offset between the first position before trip and first position inside trip | bool | True | bool |
| TRIP LOGIC VERSION | Which trip logic algorithm version to use, or disable the functionality. | str | Improved | - |

## Final Event

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| END TAGS | Which event tags can end an active trip, which do not allow reopening? Navigate to the Events page to view actual events for Device. | str | ['vehicle/rfid/.*/(unauthenticated\|rejected)'] | - |

## Primary Event

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| START TAGS | Which event tags can start a new trip or reopen latest? Navigate to the Events page to view actual events for Device. | str | ['vehicle/engine/running'] | - |
| END TAGS | Which event tags can end an active trip? Navigate to the Events page to view actual events for Device. | str | ['vehicle/engine/stopped'] | - |

## Secondary Event

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| START TAGS | Which event tags can start a new trip or reopen latest? Navigate to the Events page to view actual events for Device. | str | None | - |
| END TAGS | Which event tags can end an active trip? Navigate to the Events page to view actual events for Device. | str | ['vehicle/engine/not_running'] | - |

---

## Update Release

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| PAUSE WORKERS | Pause worker threads before updating in order to release system resources? | bool | False | - |
| DEMAND | Demand that the latest software release is installed on next shutdown? | bool | False | - |
| AUTOMATIC | Automatically keep the device updated with the lastest software release? | str | False | - |
| ATTEMPTS LIMIT | How many times the device will keep retrying the update. | int | 5 | - |

---

## Vehicle

## Ignition Event

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SOURCES | Which sources should be the basis for triggering ignition events? | str | ['bat_charging'] | - |

#### Transition To Off

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MATCH COUNT | How many sources must agree before transitioning to 'off'? If undefined or zero all sources must agree. | int | - | - |
| ALLOW DUPLICATES | Allow duplicate 'off' events to be triggered one after the other? For example, when sources have the same outcome. | bool | False | - |
| DETAIN PERIOD | How long should the state remain unchanged before the 'off' event is triggered? | int | - | s |

#### Transition To On

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MATCH COUNT | How many sources must agree before transitioning to 'on'? If undefined or zero all selected sources must agree. | int | 1 | - |
| ALLOW DUPLICATES | Allow duplicate 'on' events to be triggered one after the other? For example, when sources have the same outcome. | bool | False | - |
| DETAIN PERIOD | How long should the state remain unchanged before the 'on' event is triggered? | int | - | s |

## Trip Event

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SOURCES | Which sources should be the basis for triggering trip events? | str | ['acc_motion', 'gnss_movement'], ['acc_motion', 'gnss_movement'] | - |

#### Transition To Start

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MATCH COUNT | How many sources must agree before transitioning to 'start'? If undefined or zero all selected sources must agree. | int | 1 | - |
| ALLOW DUPLICATES | Allow duplicate 'start' events to be triggered one after the other? For example, when sources have the same outcome. | bool | False | - |
| DETAIN PERIOD | How long should the state remain unchanged before the 'start' event is triggered? | int | 5 | s |

#### Transition To Stop

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| MATCH COUNT | How many sources must agree before transitioning to 'stop'? If undefined or zero all sources must agree. | int | - | - |
| ALLOW DUPLICATES | Allow duplicate 'stop' events to be triggered one after the other? For example, when sources have the same outcome. | bool | False | - |
| DETAIN PERIOD | How long should the state remain unchanged before the 'stop' event is triggered? | int | 300 | s |

---

## Wifi

## Antenna

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| EXTERNAL | Enable external antenna for WiFi and Bluetooth? | bool | True | - |

## Client

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Enable connection to WiFi networks? | bool | True | - |
| ALLOW SSH | Allow incoming SSH connections on port 22 from the WiFi client network? | bool | False | - |

#### Connection

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| OVERRIDE | Overwrite all wifi settings that may already be specified on the device itself? | bool | False | - |
| NETWORK ENTRIES | JSON of wifi network to connect to. This field accepts all options that `wpa_supplicant.conf` for an RPI accepts. Example \{'ssid': 'my network', 'pass': 'SuperSecretPass', 'key_mgmt': 'WPA-PSK'\}. Required are ssid and pass, rest is optional. Will not be applied to device unless override is set to true. | json | \{"ssid": "network1", "pass": "SuperSecretPassword"\} | - |
| DHCPCD ENTRIES | Specify additional 'dhcpcd' entries for the 'wlan0' interface, if available. Example static ip_address=192.168.1.0/24 | str | ['metric 200'] | - |

## Hotspot

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| SSID | The name of the hotspot. Length must be between 1 and 32 characters. | str | AutoPi-XXXXXXXXXXXX | - |
| HIDE SSID | Should the hotspot name be broadcasted? | bool | False | - |
| PASS | The password to access the hotspot. Length must be between 8 and 63 characters. | str | XXXXXXXX-XXXX | - |
| CHANNEL | Which channel to use for the hotspot. If connected to a WiFi access point, due to hardware limits, the hotspot will use the same channel as the connected WiFi access point. | int | 6 | - |
| SECURITY | Which security mechanism to use for the hotspot. | int | 2 | - |

#### Client

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ALLOW LIST | Specify which client MAC addresses are allowed to connect to the WiFi hotspot. | str | - | - |

#### Dhcp

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| RANGE | Specify the range of addresses available for lease and optionally a lease time. | str | 192.168.4.2,192.168.4.20,255.255.255.0,24h | - |
| HOSTS | Supply parameters for specified hosts using DHCP. Note that IP addresses do not have to be in the specified range, they just need to be on the same network. | str | - | - |
| OPTIONS | Specify different or extra options to DHCP clients. | str | - | - |

#### Dns

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| HOSTS | Specify additional host entries. | str | ['192.168.4.1 local.autopi.io'] | - |

---

## Wireguard

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| ENABLED | Enable WireGuard VPN? | bool | False | - |
| ALLOW SSH | Allow incoming SSH connections on port 22 from the WireGuard network? | bool | True | - |

## Interface

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| NAME | Specify the configuration name of the WireGuard interface. | str | wg0 | - |
| PRIVATE KEY | Enter the generated private key for this interface. | str | - | - |
| PUBLIC KEY | Enter the generated public key for this interface. | str | - | - |
| ADDRESS | Specify the IP address of the interface. | str | - | - |
| MTU | Specify the Maximum Transmission Unit of the interface. It is recommended to verify the MTU with the command: 'ping -M do \ -s \' | int | - | - |

## Peer

| Name | Description | Type | Default | Unit |
| ------ | ------ | ------ | ------ | ------ |
| PUBLIC KEY | Specify the public key of the peer. | str | - | - |
| ALLOWED IPS | Specify the allowed IPs from the peer. | str |  | - |
| ENDPOINT | Specify the server endpoint to connect to. | str | - | - |
| PERSISTENT KEEPALIVE | Interval at which keepalive packets should be sent to the server endpoint. | int | 25 | - |
| LATENCY CHECK INTERVAL | Interval for how often the latency to the server endpoint should be measured. | int | 30 | - |

---

## Device Alerts

---

The **Device Alerts** page is a centralized view for monitoring all active alerts related to a specific device. It helps you quickly identify issues, understand their severity, and decide what action, if any, is required.

In addition to Device Alerts, AutoPi also provides alerting at other levels:
* [Vehicle Alerts](https://docs.autopi.io/cloud/fleet_management/vehicles/vehicle-details/#alerts)
* [Fleet Alerts](https://docs.autopi.io/cloud/fleet_management/fleet-alerts/)

These can be used as complementary or alternative alerting mechanisms, depending on whether you want to monitor individual devices, vehicles, or your entire fleet.

---

## Interacting with Device Alerts

### View Alert Details

To see more information about a specific alert:
* Click on the alert row in the table to expand it.
* This reveals additional technical and contextual details related to the alert.

![View Alert Details](/img/cloud/device_management/device_alerts/view_alert_details.png)

### View Alert History

Each alert includes historical information to help you understand its behavior over time, including:
* First Occurence - the **first time** the alert was triggered.
* Last Occurence - the **most recent** occurrence.
* Count - the **total number of times** it was triggered between the first and last occurrence.

![View Alert History](/img/cloud/device_management/device_alerts/view_alert_history.png)

This makes it easier to identify recurring or persistent issues.

---

## Alert Severity Levels

Alerts are categorized by severity so you can prioritize your response:

1. **Critical** – requires immediate attention.
2. **High** – important but not urgent.
3. **Medium** – should be monitored.  
4. **Low** – informational or minor issues.  

---

## Managing Alerts

Each alert has a state that indicates its current status:

* **Open** – the alert is currently active.
* **Closed** - the alert has been manually closed by using dismiss functionality on the AutoPi cloud. 
* **Resolved** – the alert has been resolved on the vehicle. 

![Alerts page](/img/cloud/device_management/device_alerts/device_alerts.png)

### Dismissing an Alert

You can dismiss an alert when it does not require further action, such as in the case of a known condition or a false positive.

When an alert is dismissed:
* It remains available in the alert history.
* You can still see when it was triggered and when it was dismissed.

This helps keep your active alerts list focused while preserving a complete historical record.

---

## CAN Analyzer

---
The **CAN Analyzer** in the AutoPi Cloud is an interactive tool for **discovering, testing, and validating CAN bus communication** on a connected vehicle or machine. It provides a UI-based interface for running low-level CAN/OBD commands, monitoring raw traffic, and validating protocol configurations before deploying loggers or integrations.

This tool is primarily used during **initial setup, troubleshooting, reverse engineering, and integration validation**.

---

## Overview

The CAN Analyzer enables:

* Passive listening of CAN traffic (sniffing)
* Testing different CAN protocols and baud rates
* Sending diagnostic requests (PID / UDS / J1939)
* Recording and replaying CAN messages
* Verifying communication between AutoPi and ECU(s)

It acts as a **real-time inspection layer** between the AutoPi device and the vehicle network.

---

## Interface Structure

The CAN Analyzer page consists of four main tabs:

1. **Sniffer** - passive monitoring of CAN traffic.
2. **Recorder** - captures CAN messages and stores them for later use.
3. **Player** - replays previously recorded CAN traffic.
4. **PID Tester** - sends request-response queries to ECUs.

![CAN Analyzer Table](/img/cloud/device_management/can_analyzer/can_analyzer.png)

---

## Sniffer (Passive CAN Monitoring)

![CAN Sniffer](/img/cloud/device_management/can_analyzer/can_sniffer.png)

> **Note:** This will only work on vehicles which allow direct CAN streaming. 

### Purpose

Used to detect:
* Active CAN bus.
* Correct protocol and baud rate.
* Raw CAN messages.

### How it works

The sniffer runs a passive monitor similar to:

```bash
obd.monitor duration=5 protocol=<protocol> baudrate=<baudrate>
```

This listens to all CAN frames being broadcast on the bus. This is required because:
* Some vehicles stream data continuously.
* Others only respond to requests (PIDs).

### Configuration

| Field         | Description                              |
| :-----------: | :--------------------------------------: |
| Vehicle Bus   | Select CAN interface (auto or manual)    |
| Protocol      | CAN protocol (e.g. ISO 15765-4, J1939)   |
| Baud Rate     | Typical values: 125k, 250k, 500k         |
| Duration      | Capture time in seconds                  |

### Workflow
1. Start with `Auto` Vehicle Bus or a known protocol. 
2. Click Sniff. 
3. Observe output:
    * No data → wrong configuration.
    * Data present → valid configuration.
4. If you didn't receive any data in the output field, adjust the protocol and/or baud rate until consistent data is received. 
5. You can also use `Verify Connection` when an obd request is sent to the vehicle and device awaits for the response, as a second layer of verification of the correct connection setup. 
6. Create bus, if you are sure of a Vehicle Bus used by your vehicle. 

This process is essential when:
    * Vehicle protocol is unknown. You can read more here: [Setting up CAN Bus Protocol](https://docs.autopi.io/getting_started/autopi_tmu_cm4/create-loggers-cm4/#use-can-analyzer-sniffer).
    * Working with heavy-duty (J1939) or proprietary buses. You can read more here: [Heavy Duty Vehicles/ J1939 Protocol](https://docs.autopi.io/getting_started/heavy_duty_vehicles/j1939-getting-started-guide/).

---

## Recorder

![CAN Recorder](/img/cloud/device_management/can_analyzer/can_recorder.png)

### Purpose

Stores CAN traffic for:
* Offline analysis
* Debugging intermittent issues
* Sharing datasets

Backend equivalent: 
```python
can.dump duration=10 file=test.log
```

This captures raw CAN frames to files such as `.log`, `.csv`, or `.blf`

---

## Player

![CAN Player](/img/cloud/device_management/can_analyzer/can_player.png)

### Purpose
Replays recorded CAN data onto the bus.

### Use cases
* Simulate ECU behavior
* Test integrations without a live vehicle
* Reproduce issues from recorded sessions

---

## PID Tester (Active Requests)

![CAN PID Tester](/img/cloud/device_management/can_analyzer/pid_tester.png)

### Purpose
Send request-response messages to ECUs.

Example:
```python
obd.query rpm mode=01 pid=0C
```

This requests engine RPM from the ECU.

### When to use
Use PID Tester when:
* Data is not broadcast automatically.
* Specific signals are required.
* Validating diagnostic communication.

---

## Terminal Integration
All actions in the CAN Analyzer correspond to terminal commands.

Example:
```python
obd.dump protocol=6 baudrate=500000 duration=1
```

This allows:
* Reproducibility.  
* Automation via scripts.
* Debugging outside the UI.

### Typical Use Cases
1. **Protocol Detection** - identify correct CAN configuration by testing:
    * Protocol.
    * Baud rate.

2. **Vehicle Integration** - verify that:
    * AutoPi can access CAN data.
    * ECUs respond correctly.

3. **Reverse Engineering** - analyze unknown CAN signals by:
    * Sniffing traffic.
    * Correlating values with real-world behavior.

4. **Troubleshooting** - detect issues such as:
    * No CAN traffic.
    * Incorrect wiring.
    * Unsupported protocol.

5. **Development & Testing:**
    * Validate CAN-based applications.
    * Simulate environments using Player.

---

## Summary
The CAN Analyzer is a diagnostic and validation tool that sits between raw CAN access and production logging.
It allows you to:
* Discover how a vehicle communicates
* Validate configurations before deployment
* Debug issues at the lowest level
* Build reliable CAN-based solutions on top of AutoPi

It is typically the first step in any CAN integration workflow.

**Important Notes**
* Requires vehicle support for CAN access (OBD or direct wiring)
* Ignition needs to be ON
* Some vehicles require wake-up communication
* Avoid testing on moving vehicles

**Best Practice Workflow**
* Ensure device is powered on and online
* Start with Sniffer:
  * Test common baud rates (250k / 500k)
* Identify working configuration
* Use PID Tester to validate responses
* Record traffic if needed
* Build loggers or integrations based on findings

---

## Change History

---

The **Device Change History** page gives you a clear overview of all configuration and state changes applied to a device, both recent and historical. It’s a useful tool for tracking what was changed, when it happened, and whether those changes were applied successfully. This helps with troubleshooting, auditing configuration updates, and understanding the current state of your device.

---

## Change History Table

The **Change History** table lists all changes applied to the device. For each entry, you can see:

- **Timestamp** – when the change was applied to the device.  
- **Successful changes** – number of changes successfully applied. 
- **Failed changes** – number of changes that failed to apply.  
- **Changed states** – number of states that were updated.  
- **Failed states** – number of states that failed to apply. 
- **Result** – overall outcome of the change operation:
  - **Success** – all changes were applied successfully.  
  - **Failed** – one or more changes failed to apply.  

![Change History Table](/img/cloud/device_management/change_history/change_history_table.png)

---

## How to Use Change History

The Change History allows you to verify:
* What changes were made to a device.  
* When those changes were applied. 
* Whether the changes were successful or failed.  

You can click on any row in the table to view detailed information for that specific change event.

---

## Change History for AutoPi TMU CM4 and AutoPi CAN-FD Pro Devices

For **AutoPi TMU CM4** and **AutoPi CAN-FD Pro** devices, clicking a row opens a detailed view for the selected timestamp. This view contains two tabs:

**1. Changes** - simplified overview of the applied changes:

* **Changed** – shows the old and new values that were successfully applied.  
* **Failed** – shows the changes that failed to apply to the device.  

![Changes for TMU devices](/img/cloud/device_management/change_history/changes_tmu_devices.png)

**2. State Results** - a more detailed, raw view of all state changes, grouped into:

* **Changed** – states successfully applied.  
* **Unchanged** – states that did not change.  
* **Failed** – states that failed to apply. 

Each state result includes additional technical details such as:
* Run number
* State
* ID
* Name
* Duration
* Start time
* Comment.

![State Results for TMU devices](/img/cloud/device_management/change_history/state_results_tmu_devices.png)

This view is especially helpful when diagnosing why certain changes did not apply as expected.

---

## Change History for AutoPi Mini Devices

For **AutoPi Mini** devices, clicking a row opens a simplified **Changes** view:

* **Changed** – shows configurations that were successfully updated, including the old and new values.  
* **Failed** – shows configurations that failed to apply to the device.  

![Changes for Mini devices](/img/cloud/device_management/change_history/changes_mini_device.png)

---

## Summary

The Device Change History provides full transparency into how and when your device configuration has evolved. By reviewing successful and failed changes, you can quickly identify issues, confirm deployments, and maintain better control over your device configurations.

---

## Custom Code

---

The **Custom Code** feature in the AutoPi Cloud allows you to **extend the functionality of your device by writing your own Python code**. It enables full control over how data is processed, how services behave, and how the device interacts with hardware and external systems.

Custom Code runs directly on the device and integrates with the AutoPi Core platform, including services, workers, hooks, and triggers.

---

## Overview

Custom Code enables you to:

* Create custom logic using Python.
* Extend or modify existing AutoPi services.
* Process CAN / OBD / GPS data.
* Trigger actions based on conditions.
* Build fully custom workflows on the device.

It is the foundation for **advanced customization and integration** on AutoPi devices.

AutoPi devices support executing custom commands and modules directly from the AutoPi cloud or Rest API, allowing programmatic control of device behavior.

---

## Interface Overview

Navigate to: **Device → Custom Code**.

![Custom Code Table](/img/cloud/device_management/custom_code/custom_code_table.png)

The page lists all custom modules configured on the device.

| Field          | Description  |
|:--------------:|:------------:|
| Name           | Module name  |
| Description    | Optional description |
| Modified       | Last updated timestamp |
| Type           | Module type (Execution, Service, etc.) |
| Enabled        | Whether the module is active |

---

## What is a Custom Module?

A **custom module** is a Python file that defines one or more functions that can be used by the AutoPi system.

Modules can be used in:

* Services - read more here: [Create Custom Services](https://docs.autopi.io/cloud/device_management/services/create-custom-services/). 
* Workers - read more here: [Create Custom Workers](https://docs.autopi.io/cloud/device_management/services/create-custom-workers/). 
* Hooks - read more here: [Create Custom Hooks](https://docs.autopi.io/core/services/#creating-custom-hooks).
* Triggers - read more here: [Triggers](https://docs.autopi.io/cloud/device_management/a-guide-to-triggers/).
* Direct command execution - using AutoPi cloud and its Terminal. 

---

## Module Types

### Execution

Used for:
* Standalone functions.
* Hooks and triggers.
* Data processing.

Example use cases:
* Transform CAN data.
* Validate incoming data.
* Trigger events.

### Service

Used for:
* Long-running processes.
* Background logic.

A service typically includes a `start()` function that runs continuously.

Custom services run alongside built-in services on the device.

---

## Creating Custom Code

### Step-by-step

1. Go to **Device → Custom Code**.
2. Click **Create**.
3. Configure:
   * Name.
   * Description (optional).
   * Type (Execution or Service)
   * Enabled (or disabled).
4. Add Python code. 
5. Specify requirements (optional).
6. Click **Save**.
7. Click **Sync** to deploy to the device.

![Create Custom Code](/img/cloud/device_management/custom_code/create_custom_code.png)

> **Note:** If the device is offline, changes will sync automatically when it reconnects.

---

## Example: Simple Execution Module

```python
import logging

log = logging.getLogger(__name__)

def log_message():
    log.info("Custom code executed successfully")

This function can be called from:
* Jobs
* Services
* Terminal

## Example: Custom Service 
```python
import logging
import time

log = logging.getLogger(__name__)

def start(**settings):
    log.info("Starting custom service")

    while True:
        log.info("Running background task")
        time.sleep(5)
```
This creates a continuously running process on the device.

---

## Using Custom Code 
Custom modules can be integrated into different parts of the system:
1. Jobs 
    Example: 
    ```python
    my_module.log_message
    ```

2. Services & Workers - use custom logic inside workflows to process data or trigger actions.

3. Hooks - allow custom processing of data inside service workflows. Hooks are integrated into service pipelines and can control execution flow.
    * Receive data from previous step.
    * Modify or filter it.
    * Return processed result.

4. Triggers - triggers react to data conditions, for example: 
     * Play sound when speed exceeds threshold.
     * Emit event when value changes. 

---

## Passing Settings
You can pass configuration into your module using JSON settings.
Example:
```JSON
{
  "threshold": 50
}
```

Access inside code:
```python
def start(**settings):
    threshold = settings.get("threshold", 50)
```

## PIP Dependencies
Custom modules support external Python dependencies. Use standard `requirements.txt` format:
```python
requests==2.31.0
```

Dependencies are installed on the device when synced.

## Typical Use Cases
* Data Processing:
  * filter CAN messages.
  * transform raw data into structured format.
* Event Handling:
  * trigger alerts based on thresholds.
  * emit events for cloud processing.
* Automation:
  * combine multiple commands into workflows.
  * create device-side logic independent of cloud.
* Integration:
  * send data to external APIs.
  * interface with third-party systems.

---

## Summary
Custom Code allows you to:
* Extend AutoPi functionality using Python.
* Build custom services and workflows.
* Process and react to vehicle data in real time.
* Integrate with external systems.

It is the core feature for advanced and scalable customization of AutoPi devices.

### Best Practices
* Keep modules focused and simple.
* Use logging for debugging.
* Test functions manually before integrating.
* Avoid blocking operations unless using services.
* Restart services after changes if required.
Custom services may require restarting the salt-minion process to take effect.

### Common Issues
* *Code not running:*
  * Module not synced.
  * Device offline.
  * Service not restarted.
* *Import errors:*
  * Missing dependencies.
  * Incorrect requirements format.
* *High CPU usage:*
  * Infinite loops without delay.
  * Heavy processing in execution modules.

### Best Practice Workflow
* Write and test code locally (simple function).
* Create module in Custom Code.
* Sync to device.
* Test via terminal or job.
* Integrate into services or workflows.
* Monitor logs and refine.

---

## Device Dashboard

---

The **Device Dashboard** is the central workspace for monitoring real-time vehicle and device data. It helps you track key metrics such as location, speed, RPM, and custom signals, whether you manage one vehicle or an entire fleet.

In this guide, you will learn how to:

- Create and manage device dashboards
- Add and configure widgets
- Use dashboard actions effectively
- Build a custom widget from OBD data end-to-end

The dashboard supports the following visualization types:

* Line chart
* Area chart
* Map
* Gauge
* Bar chart
* Pie chart
* State timeline
* Linear gauge
* Numeric

![Device Dashboard](/img/cloud/device_management/dashboard/device_dashboard_example.png)

Use the date range filter to analyze specific time periods. You can also create **custom widgets** to display only the signals you need. If you are starting from scratch, use **Autogenerate** to create an initial dashboard based on the most recent data received from the device.

You can create and manage multiple dashboards for different monitoring use cases.

---

## Dashboard Types

There are three dashboard types:

1. **Autogenerated**: Created automatically from device data.
2. **Mine**: Dashboards created by the current user.
3. **Shared**: Dashboards shared by an admin in your organization (visible in the Vehicle Dashboard view).

![Dashboard Types](/img/cloud/device_management/dashboard/vehicle_dashboard_types.png)

:::note
With admin permissions, you can create shared dashboards and assign them to vehicles by type or make/model. For details, see [Creating a Shared Dashboard](https://docs.autopi.io/cloud/fleet_management/configurations/dashboards/#creating-a-shared-dashboard).
:::

---

## Create a New Device Dashboard

To create a dashboard:

1. Navigate to **Device > Dashboard**.
2. Click **Create dashboard**.
3. Enter:
   - **Name**: A clear dashboard name.
   - **Description** (optional): A short description of its purpose.
4. Click **Create**.

![Create New Device Dashboard](/img/cloud/device_management/dashboard/create_new_device_dashboard.png)

---

## Adding Widgets to the Dashboard

Use real device data when possible to validate widget configuration.

:::note
The **Autogenerate** option creates widgets automatically from available device data. This is a practical starting point when creating a dashboard from scratch.
:::

To add a widget manually:

1. Navigate to the **Dashboard** and click **Actions**.
2. Click **Add widget**.
3. Select a widget type.
   ![Widget types](/img/cloud/fleet_management/configurations/dashboards/widget_type.png)
4. Configure the widget:
   ![Widget configuration](/img/cloud/fleet_management/configurations/dashboards/configure_widget.png)
   - **Title**: Widget display name.
   - **Visualization**: Chart or display type (line chart, map, gauge, and so on).
   - **Field**: Logger or signal to display.
   - **Aggregation**: Average, minimum, maximum, sum, or raw data.
   - **Unit**: Unit shown in the widget.
   - **Auto scale**: Scales values automatically to fit the visualization.
   - **Hide gaps**: Shows or hides periods with no data.
5. Click **Save** in the widget editor, then save the dashboard.

### Widget Controls

Each widget has the following controls in the top-right corner:

| Icon | Action |
|:------:|:--------:|
| Circle (refresh) | Refresh the data displayed in the widget |
| Two-dot (edit) | Open the widget editor |
| Download | Download the data for this widget only |
| X (delete) | Remove the widget from the dashboard |

### Editing a Widget

To edit a widget, click **Edit** in the top-right corner of the widget. Update the settings in the configuration dialog, then save your changes.

---

## Dashboard Actions

The following actions are available for each device dashboard:

| Action | Description |
|:--------:|:-------------:|
| **Restore to default** | Resets the dashboard to the default widget layout. |
| **Save as default** | Sets this dashboard as the default view shown when opening the Dashboard tab for a device. |
| **Download all data** | Downloads all data currently shown on the dashboard, based on the selected time range and all visible widgets. |
| **Show Events** | Redirects to the Events page with the time range pre-filtered to match the current dashboard view. |
| **Edit** | Opens the dashboard for editing. |
| **Duplicate** | Creates a copy of the dashboard, useful as a starting point for a new layout. |
| **Delete** | Permanently removes the dashboard. |

---

## How to Add a New Widget from Scratch

This workflow shows how to create a widget from OBD data collected directly from your vehicle. The process has three steps:

![Create widget steps](/img/cloud/device_management/dashboard/adding_a_new_widget_from_scratch/create_widget_steps.png)

Follow the steps below in order.

### Step 1: Library - Find the PID

Use the OBD library to identify the signal you want to log. The library has two sections:

- Your [library](/cloud/obd_library/library.md): Commands specific to your vehicle, extracted automatically or added manually.
- The [community library](/cloud/obd_library/community_library.mdx): Commands available globally in the [AutoPi](https://www.autopi.io) platform.

If you find a relevant command in the community library, add it to your own library first.

:::note
You can create loggers only from commands in your own library.
:::

![Add command](/img/cloud/device_management/dashboard/adding_a_new_widget_from_scratch/add_command.jpeg)

### Step 2: Loggers - Configure Data Collection

After selecting a PID, configure logging for the device. Go to **Devices > Loggers** and click **Create**:

![Create logger](/img/cloud/device_management/dashboard/adding_a_new_widget_from_scratch/create_logger.jpeg)

Select the PID from the list. This list includes only commands from your own library. Then set the **interval** (in seconds), which determines how often the logger runs. For example, `30` means the logger runs every 30 seconds.

After saving, sync changes to the device. Logging starts immediately after sync.

### Step 3: Widgets - Visualize Logged Data

With logging enabled, create a widget to display the collected data on your dashboard.

Open the dashboard, click **Add widget**, and select a custom widget type.

![Create widget](/img/cloud/device_management/dashboard/adding_a_new_widget_from_scratch/create_widget.jpeg)

Enter a title and select a visualization type. In **Field**, set the data source in this format:

```
obd.<logger_name_lowercase>.value
```

For example, if your logger name is `RPM`, use `obd.rpm.value`. The widget automatically loads up to 14 days of available data.

:::note
Widgets can display only data that has already been logged. If the logger is new, data may take a short time to appear. Once the device streams data to [Cloud](https://www.autopi.io/software-platform/cloud-management), it becomes available for visualization across trips where that logger was used, including previously collected data.
:::

After completing these three steps, your dashboard widget will display vehicle data from your configured OBD logger.

---

## Devices

---

## Devices List

The **Devices List** provides a table view of all your devices, including key details such as device name, unit ID, last communication timestamp, and more.

![Devices List](/img/cloud/device_management/devices/devices_list.png)

### Search and Filter Devices

To quickly find a specific device:

* Use the **Search for Vehicle** field at the top of the page.
* Use **Filters** to refine the list based on specific criteria.

	
		 Available Filters:  
        * **Last Communication** – online now, last 15 minutes, last hour, today, last 7 days, last 30 days.  
        * **Update State** – up-to-date, awaiting update, update failed. 
        * **Release** – filter by software release.  
        * **Open Alerts** – filter by severity (low, medium, high, critical).
        * **Active Alerts** – filter by specific active device alerts.  
        * **Board Version** – filter by device hardware version.
        * **Type** – filter by device type: 4G - TMU CM4; Mini; Pro - CAN-FD Pro. 

	
	

### Customize Table View

You can customize the table using **Edit Columns** to include additional details.

	
		 Available Columns:  
        * Status  
        * Vehicle  
        * Device ID  
        * IMEI  
        * UNIT ID  
        * Last Communication  
        * Update State  
        * Phone Number  
        * ICCID  
        * WiFi Password  
        * Release  
        * Open Alerts  
        * Tags  
        * Board Version  
        * Pending Syncs  
        * VIN  
        * Type. 
	
	

### Additional Actions

* **Register Device** – add a new device to your account. 
* **Go to Docs** – open documentation for this page.  
* **Export CSV** – export device data for reporting or sharing. 

![Devices List Functionalities](/img/cloud/device_management/devices/device_list.functionalities.png)

To view more details about a device, click on it to open the **Device Overview** page.

---

## Device Overview

When you select a device from the list, you are redirected to its dedicated **Device Overview** page.

![Device Overview](/img/cloud/device_management/devices/device_overview.png)

### General Information

At the top of the page, you will find:

* Device name. 
* Last communication timestamp. 
* "Go to Vehicle" button (to view the associated vehicle).   
* "Edit Device" option (top-right corner). 

![Device Overview Details](/img/cloud/device_management/devices/device_details.png)

### Other Available Tabs for Device 

Each device includes multiple tabs for configuration and monitoring:

* Dashboard  
* Jobs *(not available for AutoPi Mini devices)*  
* Custom Code *(not available for AutoPi Mini devices)*  
* Geofences *(not available for AutoPi Mini devices)*  
* Services *(not available for AutoPi Mini devices)*  
* Events  
* CAN Analyzer *(TMU CM4 only)*  
* Loggers / CAN Logging  
* Change History  
* Variables *(not available for AutoPi Mini devices)*  
* Advanced Settings  
* Triggers  
* Alerts  
* Software Updates  

### Overview Widgets

The Device Overview page includes several widgets that provide key insights:

![Device Widgets](/img/cloud/device_management/devices/device_widgets.png)

* **Key Status** - accepted/ denied. 
* **Last Communication** - timestamp of the last time the device send data.
* **Installed Version** - backend installed version. 
* **Voltage Measured**  - the Voltage reading from the vehicle. 
* **Network Interfaces** - basic information about network interfaces. 
* **Vehicle Information** - Make, Model, Year, engine type. 
* **CAN Bus Configuration**  - CAN Bus protocol with Baud Rate. 
* **Open Alerts** (by severity) - shows the count of open alerts.  
* **Device Specifications** - information such as UNIT ID, Device ID, template, modem, board version.  
* **AutoPi.io SIM** - if you purchased the AutoPi SIM you will be able to access: status, phone number and monthly data usage overview.   
* **Device Metrics** - information about device metrics such as CPU, memory, storage..

These widgets provide a quick and comprehensive overview of your device’s status, configuration, and activity.

---

## Connecting Your AutoPi Device to a Vehicle

Follow the steps below to connect your AutoPi device to either a new or existing vehicle.

### Step-by-Step Instructions

1. **Log in** to the [AutoPi Cloud Platform](https://my.autopi.io/) using your account credentials.
2. From the main dashboard, go to the **Devices** tab.  
   ![Main screen - Devices tab](/img/cloud/device_management/device_install_procedure/main_screen_devices.jpg)
3. **Select the device** you want to configure.  
   ![Device selection screen](/img/cloud/device_management/device_install_procedure/device_screen.jpg)
4. Click the **Settings** button in the upper-right corner.  
   ![Device settings button](/img/cloud/device_management/device_install_procedure/selected_device_settings.jpg)

#### Option A: Pair with a New Vehicle

If you haven't created a vehicle yet, follow these steps:
1. In the settings pop-up, go to the **Vehicles Editor** tab.  
   ![Vehicles editor tab](/img/cloud/device_management/device_install_procedure/device_settings_new_vehicle.png)
2. Click the **New Vehicle** button.
3. Fill in the required vehicle details, such as:
   - Make  
   - Model  
   - Year  
   - Vehicle type  
   ![New vehicle form](/img/cloud/device_management/device_install_procedure/create_new_vehicle_screen_button.png)
4. (Optional) Set up CAN bus settings if applicable.
5. Click **Save** to store the changes. Your AutoPi device is now paired with the new vehicle.  
   ![Return to device settings](/img/cloud/device_management/device_install_procedure/return_to_device_settings.png)

#### Option B: Connect to an Existing Vehicle

If a vehicle is already set up, follow these steps:

1. In the settings pop-up, go to the **Device** tab.  
   ![Device tab](/img/cloud/device_management/device_install_procedure/device_settings_new_vehicle.png)
2. At the top of the device settings, there is a **dropdown menu** showing the currently connected vehicle.
3. Click the dropdown to view a list of all existing vehicles. Select the one you want and click **Save**.  
   ![Vehicle selection dropdown](/img/cloud/device_management/device_install_procedure/device_settings_select_vehicle.png)

Your AutoPi device is now successfully paired with a vehicle and ready for use!

---

## Introduction(Device_management)

In the Events section, you will find records of specific state changes or
conditions encountered by the device. The system running on the device is capable of
monitoring and responding to these events, performing additional actions when they
occur. Each Event includes a timestamp, a tag, and additional data fields.

Events play a crucial role in setting up triggers and are also available for
historical reference. Events are categorized into two areas: 'System' and 'Vehicle'.
In the Device Management section of the platform, you can access both System and
Vehicle events. However, in the Fleet Management section, you will find only Vehicle
Events.

For detailed information about Events and their settings, please take a look at the documentation below:

  - [System](system.md)
  - [Vehicle](vehicle.md)

![AutoPi Cloud Events](/img/cloud/device_management/events/intro/events_example.png)

---

## System(Events)

System events relate to the running system of the device.

## Device Events

These events apply depending on which peripherals are installed inside the dongle.

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/device/ec2x/gnss/assist_data_updated` | GNSS assist data of the installed EC2X compatible device has been updated. | - |
| `system/device/ec2x/powered_off` | Installed EC2X compatible device was powered off. Automatic power on is expected immediately after. | `reason` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | - |

## Disk Housekeeper

**NOTE**: These events are only available for the Pro edition with the _CAN Logging_ feature.

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/disk_housekeeper/ordinary_purge` | Files have been deleted because the disk usage percentage was exceeded. | `files` |
| `system/disk_housekeeper/critical_purge` | Files have been deleted because the disk usage percentage exceeded the critical level. | `files` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `files` | List | List of files that have been deleted. | - |

## Minion Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/minion/ready` | The Minion is started up and ready. | - |
| `system/minion/online` | The Minion is connected to the hub. | - |
| `system/minion/offline` | The Minion is not connected to the hub. | - |
| `system/minion/restarting` | The Minion is restarting because of the specified reason. | `reason` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | - |

## Network Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/network/wwan0/online` | The network interface _wwan0_ has gone online. | - |
| `system/network/wwan0/offline` | The network interface _wwan0_ has gone offline. | `reason` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | - |

## Power Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/power/_booting` | The prefixed underscore indicates that this is a private event and should only be used for debugging purposes. The event describes the internal state of the SPM subsystem. This event may be discarded in the future. | `awaken`, `trigger` |
| `system/power/on` | Triggered when it is confirmed that the SPM subsystem is in *on* state. | `awaken`, `trigger` |
| `system/power/last_off` | Informs during start-up the last known timestamp where the device was last powered off. The actual timestamp is retrieved from the syslog and should only be used for debugging purposes. | `timestamp` |
| `system/power/recover` | Informs during start-up if the device has recovered from an error condition handled by the SPM subsystem. | `trigger` |
| `system/power/sleep` | Device went into sleep because of specifed reason.  | `delay`, `interval`, `reason`, `uptime` |
| `system/power/hibernate` | Device went into hibernation because of specifed reason. | `delay`, `interval`, `reason`, `uptime` |
| `system/power/3v3/restarted` | The 3V3 power supply has been restarted. | `reason` |
| `system/power/config_failed` | One or more configuration parameters of the SPM subsystem could not be loaded and have therefore been restored to default. This event only applies to SPM version 3. | `params` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `awaken` | Text | The state from which the device awakens. | `off`, `sleeping`, `hibernating` |
| `delay` | Number | Delay in seconds before execution. | 10 |
| `interval` | Number | Planned duration in seconds before expiration. | 300 |
| `reason` | Text | The explanatory cause for the event. | - |
| `timestamp` | Timestamp | Time to be reported. | 2019-03-13T11:10:14 |
| `trigger` | Text | Underlying cause of the event reported by the SPM subsystem. | `acc`, `boot_timeout`, `heartbeat_timeout`, `modem`, `rpi`, `spm`, `stn`, `timer` |
| `uptime` | Number | System uptime in seconds. | 3745 |
| `params` | List | List of parameter names. | - |

## Release Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/release/pending` | Installing latest release. | `id` |
| `system/release/forcing` | Force installing latest release. | `id` |
| `system/release/retrying` | Retrying installation of latest release. | `id` |
| `system/release/failed` | Installation of latest release failed. | `id` |
| `system/release/updated` | Installation of latest release succeeded. | `id` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `id` | UUID | ID of the concerned release. | 8ff5526a3dafe2fc0e80675f32755578ddaf3962 |

## STN Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/stn/not_connected` | Not connected to STN11XX interface. | - |
| `system/stn/interface_connected` | Connected to STN11XX interface. | - |
| `system/stn/bus_connected` | Connected to bus using specified protocol.  | `protocol`, `autodetected` |
| `system/stn/bus_disconnected` | Was connected to a bus but is now disconnected. | - |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `protocol` | Text | ID of the protocol. | 6 |
| `autodetected` | Boolean | Has the protocol been autodetected or not? | `true` |

## Time Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/time/synced` | The system clock was synchronized with the specifed source. | `new`, `old`, `source` |
| `system/time/uncertain` | The system clock is not synchronized. | - |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `new` | Timestamp | The new time after synchronization. | 19-03-13 10:08:19 |
| `old` | Timestamp | The old time before synchronization. | 2019-03-13 10:08:30 |
| `source` | Text | The source that was synchronized against. | `network`, `ntp`, `rtc`  |

## RFID Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/rfid/<rfid_token>/read` | A new RFID token has been read by the reader. | - |
| `system/rfid/<rfid_token>/rejected` | A token that was read was rejected. | - |
| `system/rfid/<rfid_token>/authenticated` | A token that was read was authenticated. | `valid_from`, `valid_for` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `valid_from` | Timestamp | From what time is the token valid. The timestamp is in UTC. | 2019-03-13 10:08:30 |
| `valid_for` | Number | For how long (in seconds) is the token valid for. | 7200  |

## Short Message Service (SMS) Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/sms/received` | A new SMS message was received. | `sender`, `timestamp`, `text` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `sender` | Text | The phone number of whoever sent the message, including country code. | +4501020304 |
| `timestamp` | Timestamp | The timestamp that the message was received on. Timestamp is in UTC. | 2019-03-13 10:08:30 |
| `text` | Text | The text contained in the mesage. | 'An example text message.'  |

## Hotspot Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/hotspot/client/<mac>/connected` | A client with MAC accress `<mac>` has connected to the device's hotspot. | - |
| `system/hotspot/client/<mac>/disconnected` | A client with MAC accress `<mac>` has disconnected from the device's hotspot. | - |
| `system/hotspot/client/<mac>/not_connected` | A client with MAC accress `<mac>` hasn't connected to the device's hotspot. This is only available with the custom handler `hostapd.expect_allow_list_handler`. | - |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `mac` | Text | A Media Access Control address. | 2C-54-91-88-C9-E3 |

## USB Device Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/usb/<vendor_id>/<product_id>/connected` | A USB device was connected to the [AutoPi](https://www.autopi.io). Run `usbutil.devices` to get a list of currently connected devices. | `bus`, `device`, `name` |
| `system/usb/<vendor_id>/<product_id>/disconnected` | A USB device has disconnected from the [AutoPi](https://www.autopi.io). | `bus`, `device`, `name` |
| `system/usb/<vendor_id>/<product_id>/not_connected` | A device with `<vendor_id>` and `<product_id>` has been specified as expected, but was not found to be connected when the device was started. | - |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `bus` | Text | The (linux) bus number the device is connected on. | 001 |
| `device` | Text | The device number the system has assigned to the device. | 001 |
| `vendor` | Text | The vendor hexadecimal number/ID of the device. | 1d6d |
| `product` | Text | The product's hexadecimal number/ID of the device. | 0002 |
| `name` | Text | The device's name. | Linux Foundation 2.0 root hub |

## Docker Events

We pass through the following docker events from the docker instance event stream.
* start
* stop
* die
* pull

See more information about the events here:
https://docs.docker.com/engine/reference/commandline/events/

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/docker/container/<name>/start` | A container was started. This event will occur every time the device starts. | `release_hash`, `image`, `name`, `project`, `id`, `release` |
| `system/docker/container/<name>/stop` | A container was stopped. | `release_hash`, `image`, `name`, `project`, `id`, `release` |
| `system/docker/container/<name>/die` | A container stopped unexpectedly. | `release_hash`, `image`, `name`, `project`, `id`, `release` |
| `system/docker/image/<name>/pull` | An image was pulled | `tag`, `release_hash`, `image`, `name`, `project`, `id`, `release` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `release_hash` | Text | The version of the docker release | `e205220a` |
| `image` | Text | The name of the image | redis:bullseye |
| `name` | Text | Unique name of the container | project_name-container_name-pretty_version |
| `project` | Text | Project name | my_project |
| `id` | Text | ID of docker object | 40d7a9a7d6bb3c085149a45fc1874de8b4541bac7a28a46f60f734e34f52989b |
| `release` | Text | Pretty version of the release | 1.2.3 |

## Kernel Error Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/kernel/error` | A kernel error was detected. | - |

## Mosquitto Error Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/mosquitto/error` | An error occurred in the Mosquitto MQTT broker. | - |

## Temperature Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `system/temperature/cold` | The system temperature has dropped to a cold level. | `reason` |
| `system/temperature/warm` | The system temperature has reached a warm level. | `reason` |
| `system/temperature/hot` | The system temperature has reached a hot level. | `reason` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | - |

---

## Vehicle(Events)

## Battery Events

These events are calculated from the voltage level measured via the OBD-II connector and are fired by the trigger [`battery_event`](/core/services/core-services-obd-manager/#battery_event) in the [Obd Manager](/core/services/core-services-obd-manager/).

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/battery/unknown` | The battery state is unknown. | `reason` |
| `vehicle/battery/charging` | The battery has started charging. | - |
| `vehicle/battery/discharging` | The battery is discharging. | `level` |
| `vehicle/battery/overcharging` | The battery is overcharging compared to normal. | - |
| `vehicle/battery/charging_slow` | The battery charges slowly. | - |
| `vehicle/battery/critical_level` | The battery voltage has reached a critically low level. | `level` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | - |
| `level` | Number | Battery level as a percentage. | 90 |

## Battery Nominal Voltage Events

**NOTE**: These events are only available for the Pro edition.

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/battery/nominal_voltage/unknown` | The battery nominal voltage is unknown. | `reason` |
| `vehicle/battery/nominal_voltage/autodetected` | The battery nominal voltage is autodetected. | `value` |
| `vehicle/battery/nominal_voltage/predefined` | The battery nominal voltage is predefined to a fixed value. | `value` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | `nominal_voltage_absent` |
| `value` | Number | Battery nominal voltage value. | 12 |

## CAN Logging Events

**NOTE**: These events are only available for the Pro edition with the _CAN Logging_ feature.

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/bus/<can0\|can1\|...>/logger/<logger_name>/writing` | The logger is starting to write raw CAN frames to an output file. | `file` |
| `vehicle/bus/<can0\|can1\|...>/logger/<logger_name>/rollover` | The logger is performing rollover of the output file. | `source_file`, `destination_file` |
| `vehicle/bus/<can0\|can1\|...>/logger/<logger_name>/decoder/<decoder_name>/reading` | The decoder is starting to read raw CAN frames from an input file. | `file` |
| `vehicle/bus/<can0\|can1\|...>/logger/<logger_name>/decoder/<decoder_name>/writing` | The decoder is starting to write decoded data to an output file. | `file` |
| `vehicle/bus/<can0\|can1\|...>/logger/<logger_name>/decoder/<decoder_name>/rollover` | The decoder is performing rollover of the output file.. | `source_file`, `destination_file` |
| `vehicle/bus/<can0\|can1\|...>/logger/<logger_name>/s3_sync/started` | An AWS S3 sync job has started. | - |
| `vehicle/bus/<can0\|can1\|...>/logger/<logger_name>/s3_sync/completed` | An AWS S3 sync job has finished with success. | `uploaded_files` |
| `vehicle/bus/<can0\|can1\|...>/logger/<logger_name>/s3_sync/timeout` | An AWS S3 sync job has timed out. | - |
| `vehicle/bus/<can0\|can1\|...>/logger/<logger_name>/s3_sync/failed` | An AWS S3 sync job has finished with errors. | `errors`, `uploaded_files` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `file` | Text | Path of file. | - |
| `source_file` | Text | Path of source file. | - |
| `destination_file` | Text | Path of destination file. | - |
| `uploaded_files` | List | List of files that have been uploaded. | - |
| `errors` | List | List of errors that occurred. | - |

## Engine Events

These events are fired by the trigger [`rpm_engine_event`](/core/services/core-services-obd-manager/#rpm_engine_event) in the [Obd Manager](/core/services/core-services-obd-manager/) and are only intended for ICE-type cars.

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/engine/not_running` | The engine is currently not running. This event is usually seen during start-up. | `reason` |
| `vehicle/engine/running` | The engine is now running. | - |
| `vehicle/engine/stopped` | Before the engine was started, now it is stopped. | `reason` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | - |

## Communication Events

These events are fired by the trigger [`communication_event`](/core/services/core-services-obd-manager/#communication_event) in the [Obd Manager](/core/services/core-services-obd-manager/) and used with EV-type cars that are unable to produce [Motor Events](#motor-events).

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/communication/inactive` | Communication with the vehicle is currently inactive. This event is usually seen during start-up. | `reason` |
| `vehicle/communication/established` | Communication with the vehicle is established. | - |
| `vehicle/communication/disconnected` | Communication with the vehicle is disconnected. | `reason` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | - |

## Motor Events

These events are fired by the trigger [`rpm_motor_event`](/core/services/core-services-obd-manager/#rpm_motor_event) in the [Obd Manager](/core/services/core-services-obd-manager/) and are intended for EV-type cars.

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/motor/not_running` | The motor(s) is currently not running. This event is usually seen during start-up. | `reason` |
| `vehicle/motor/running` | The motor(s) is now running. | - |
| `vehicle/motor/stopped` | Before the motor(s) was running, now it is stopped. | `reason` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | - |

## Position Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/position/unknown` | The vehicle's current position is not confirmed. | `reason` |
| `vehicle/position/standstill` | The vehicle's position is known and stationary.  | - |
| `vehicle/position/moving` | The vehicle has started moving. | - |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `reason` | Text | The explanatory cause for the event. | no_fix |

## Motion Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/motion/steady` | The accelerometer readings detect a steady device (there is no movement). | - |
| `vehicle/motion/shaking` | The accelerometer readings detect a shaking motion. | - |
| `vehicle/motion/jolting` | The accelerometer readings detected a sudden jolt in the device. | - |

## Geofence Events

These events are triggered by the [`position_event`](/core/services/core-services-tracking-manager/#position_event) trigger in the [Tracking Manager](/core/services/core-services-tracking-manager/) after first acquiring a GPS signal after startup (entering the `on` power state). 
The geofence_slug is a URL-safe version of the geofence's name.

`enter|exit` gets triggered while driving when the vehicle enters/exits a geofence.

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/geofence/<geofence_slug>/enter` | The vehicle went from being outside a geofence to inside a geofence. | `fence_id` |
| `vehicle/geofence/<geofence_slug>/exit` | The vehicle went from being inside a geofence to outside a geofence. | `fence_id` |

`inside|outside` events are triggered once for each geofence when the device wakes up, and is a snapshot of the current state.

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/geofence/<geofence_slug>/inside` | The vehicle is inside a geofence. | `fence_id` |
| `vehicle/geofence/<geofence_slug>/outside` | The vehicle is outside a geofence. | `fence_id` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `fence_id` | Number | Id of the geofence that triggered the event | `3306` |

## Ignition Events

| Tag | Description | Fields |
| ------ | ------ | ------ |
| `vehicle/ignition/on` | The vehicle ignition was turned on. | `source` |
| `vehicle/ignition/off` | The vehicle ignition was turned off. | `source` |

**FIELD DEFINITIONS**

| Name | Type | Description | Example |
| ------ | ------ | ------ | ------ |
| `source` | Text | The source that triggered the ignition event. | - |

---

## Geofences

---

> **Note:** This functionality is only available for devices that had **Device Geofences** set up in the past.  
> For new setups, we recommend using **[Fleet Geofences](https://docs.autopi.io/cloud/fleet_management/vehicles/fleet-geofences/)**, which provide improved functionality and easier management.

## Create a Device Geofence

Geofences allow you to define a specific area on a map and receive notifications when a vehicle **enters** or **exits** that area. A geofence can be defined as either:

* A **polygon** (custom shape).
* A **circle** (point with radius).

![Create Device Geofence](/img/cloud/device_management/device_geofences/create_device_geofence.png)

### Steps to Create a Device Geofence

1. Navigate to **Device → Geofence** tab.  
2. Click **Create**.  
3. Fill out the following:

**Basic Information**
* **Name** – name of your geofence.  
* **Description** *(optional)* – additional details  

**Define the Geofence Area**
* Use the **search bar** to locate a specific address.  
* Enable **vehicle position** to draw more precisely.
* Use **zoom controls (+ / -)** to adjust the map view.  
* Draw the geofence using:
  * **Circle**.
  * **Polygon**.
* Adjust the shape using:
  * **Edit layers** – modify points.  
  * **Drag layers** – move the geofence.  
  * **Rotate layers** – rotate the shape of the geofence.  
  * **Remove layers** – delete the geofence.  

**Settings**
* **Enabled** – toggle the geofence on or off. 

---

## How Device Geofences Work

Once created, the geofence is synchronized to the device. The device evaluates its position and triggers events based on geofence state.

### Event Types

#### 1. Wake-Up State Check
When the device wakes up, it reports whether it is inside or outside each geofence:
* `vehicle/geofence/GEOFENCE_NAME/inside`
* `vehicle/geofence/GEOFENCE_NAME/outside`

#### 2. Enter / Exit Events
When a new position is logged:

* The device checks if the geofence state has changed. 
* If **3 consecutive positions** confirm the change, an event is triggered:
    * `vehicle/geofence/GEOFENCE_NAME/enter`
    * `vehicle/geofence/GEOFENCE_NAME/exit`

These events are sent to the AutoPi Cloud, where they can be used for monitoring and automation.

---

## Use Geofences with Templates

Device geofences are typically assigned to a **single device**. To apply the same geofence to multiple devices, use **[Templates](https://docs.autopi.io/cloud/device_management/templates/)**.

![Use geofences with Templates](/img/cloud/device_management/device_geofences/template_geofences.png)

### Steps

1. Navigate to **Templates**.  
2. Select a template or Create a new one.   
3. Open the **Geofences** tab.  
4. Click **Create**.  
5. Configure the geofence (same as above). 
6. Assign devices and apply the template.  

This allows you to deploy geofences across multiple devices efficiently.

---

## Use Device Geofences with Triggers

Geofence events can be used together with **[Triggers](https://docs.autopi.io/cloud/device_management/a-guide-to-triggers/)** to automate actions.

### Example Use Case

* Notify by email when a vehicle enters a restricted area:
    ![Use device geofences with Triggers](/img/cloud/device_management/device_geofences/trigger_geofence.png)

### How It Works

* Geofence events appear under **Device → Events**. 
* You can create a **Trigger** based on:
  * `vehicle/geofence/*/enter`
  * `vehicle/geofence/*/exit`

### Possible Actions

* Send email notifications. 
* Trigger webhook requests. 
* Send an alert on AutoPi Cloud.   

---

> **Recommendation:** For improved usability and fleet-wide management, consider using **[Fleet Geofences](https://docs.autopi.io/cloud/fleet_management/vehicles/fleet-geofences/)**, which provide a more scalable and user-friendly approach.

---

## Global Variables

---

The Global Variables feature allows Account Administrators to define custom values that can be reused across templates. This makes it easy to apply consistent configurations (e.g. stream IDs, API keys, etc.) without having to manually update templates for each device.

:::note
This section is only available for users with **Account Administrator** permissions. You can read more at this guide about the different permissions on AutoPi Cloud: [Accounts permissions](https://docs.autopi.io/cloud/accounts/). 
:::
---

## What are Global Variables?  
Global Variables are reusable key-value pairs that can be inserted into templates. They function as **keyword replacements**, allowing you to dynamically apply values when templates are used. You can also read more about Templates functionality in this guide: [Templates](https://docs.autopi.io/cloud/device_management/templates/). 

For example:  
- An `API_KEY` for an external service, can be stored as a global variable and automatically applied across devices.  
- Unique stream keys or IDs can be set once and reused in multiple templates.  

This saves time, reduces errors, and ensures consistency.  

![Global Variables Table](/img/cloud/device_management/global_variables.png)

---

## How to Create Global Variables  

1. Navigate to the **Global Variables** section.  
2. Click the **Create** button.  
3. Enter the following details:  
   - **Key**: The variable name (e.g., `API_KEY`).  
   - **Value**: The variable’s value (e.g., `example`).  
4. Save the variable.  

Your new global variable will now appear in the table.  

![Create Global Variable](/img/cloud/device_management/create_global_variable.png)

---

## How to Use Global Variables  

### Example of Global Variable
At the moment, our AutoPi Cloud have a couple of default environment variables that exists by default. One of the examples is Unit IDs of AutoPi devices. Where `AUTOPI_UNIT_ID` holds the device unit id (format: `00000000-0000-0000-0000-000000000000`). 

* When applying templates, global variables can be used as **placeholders** that are replaced with the defined values. 
* When applying templates, custom settings will substitute the found environment keys with the value provided in the global variables, in this format: 
 ```python 
    $AUTOPI_UNIT_ID
  ```
* The environment variables will be synced to the device and are available to any custom service. This allows templates and other services to remain generic, while device-specific or account-specific values are dynamically filled in.  

### Device Overrides  

In some cases, a global variable can be **overridden per device**. This means that while the variable has a global default value, you can assign a different value to specific devices when needed.  

To override a variable for a specific device, navigate to the device's detail page and open the **Variables** tab. There you can define device-specific values that take precedence over the global defaults.

For example:  
- Global API key = `Office123`  
- Device override for Device A = `Home456`  

This ensures flexibility when some devices require unique values.  

### Docker Container Integration  

Global variables (and any device-level overrides) are **automatically injected as environment variables** when deploying Docker containers to a device. This means your containerized applications can access them directly at runtime without any extra configuration.  

For more details on deploying Docker containers to your AutoPi device, see the [Setting Up Docker on Your Device](https://docs.autopi.io/developer_guides/setting-up-docker/) guide.  

### Best Practices  

- Use descriptive keys (e.g., `API_KEY`, `WIFI_PASSWORD`, `DEVICE_NAME`).  
- Avoid duplicating keys with different values to prevent confusion.  
- Regularly review and clean up unused variables.

---

## Overview

---

## Overview of Devices 

The **Overview** section in the AutoPi Cloud Platform (under **Device Management**) provides a centralized view of all your devices. It is designed to help you monitor device activity, track system health, and ensure that your fleet operates efficiently with continuous communication and data exchange.

![Device management overview](/img/cloud/device_management/device_management_intro.png)

---

## What You Can See in the Overview

### Devices Activity

The activity section shows how your devices are performing over time:

![Device activity](/img/cloud/device_management/overview/fleet_overview.png)

* **Online now** – devices currently online. 
* **Online today** – devices that have been active during the day.  
* **Online in the last 30 days** – long-term activity overview.  

This helps you identify devices that are inactive or underutilized.

### Open Alerts

Displays the number of active alerts across four severity levels:

![Open alerts severity](/img/cloud/device_management/overview/open_alerts.png)

* **Critical**
* **High**
* **Medium**
* **Low**.

Monitoring this section helps you quickly detect issues. If there are **critical alerts**, it usually indicates that immediate attention is required.

### Software Updates Status

Provides an overview of update status across your devices:

![Open alerts severity](/img/cloud/device_management/overview/software_updates.png)

* Devices **up to date**
* Devices with **failed updates**
* Devices **waiting for updates**. 

This allows you to ensure that your fleet is running the latest software versions.

---

## Summary

The **Overview** page gives you a quick, high-level snapshot of your entire fleet, helping you:

* Monitor device connectivity. 
* Track alerts and issues.   
* Manage software updates efficiently. 

We continuously improve our platform and strongly recommend keeping your devices updated to ensure optimal performance.

**Best Practices:**
* Regularly check the **Overview** page to monitor fleet health.  
* Pay close attention to **critical alerts**. 
* Keep devices **up to date** to benefit from improvements and fixes.

---

## Jobs

---

The **Jobs** feature in the AutoPi Cloud is used to **schedule and execute commands on a device automatically**. It allows you to run tasks at defined intervals or specific times without manual interaction.

Jobs are part of the **device management layer** in AutoPi Cloud, which provides centralized control over connected devices and their behavior. 

## Overview

A Cloud Job consists of:

* A **function** (command to execute).
* A **schedule** (when to run it). 
* A **returner** (where the result is sent). 

![AutoPi Cloud Jobs](/img/cloud/device_management/jobs/jobs.jpg)

Jobs are executed on the device and can return results back to:
* AutoPi Cloud. 
* External systems (via returners). 

Jobs are commonly used for:
* Periodic data collection.
* Health monitoring.
* Diagnostics.
* Automation of workflows.

---

## Key Concepts

### Function

Defines what the job does.

Examples:
```bash
rpi.stats
metrics.collect
obd.query rpm
```

These correspond to AutoPi Core modules running on the device.

### Schedule (Cron)
Jobs use cron expressions to define execution timing. Cron is a standard Linux scheduling system used to run tasks at specific intervals.

Example schedules:
| Cron Expression   | Meaning             |
| :---------------: | :-----------------: |
| `* * * * *`       | Every minute        |
| `*/5 * * * *`     | Every 5 minutes     |
| `0 * * * *`       | Every hour          |
| `0 0 * * *`       | Daily at midnight   |

### Returner
Defines where the output is sent.

Typical options:
* `cloud` → stored in AutoPi Cloud.
* Custom returners → external systems (e.g. APIs, storage).

---

## Interface Overview
The Jobs page lists all configured jobs for a device.

Each job includes:
| Field         | Description             |
| :-----------: | :---------------------: |
| Name          | Job identifier          |
| Description   | Optional explanation    |
| Function      | Command executed        |
| Returner      | Output destination      |
| Enabled       | Whether job is active   |

---

## Creating a Job
Step-by-step: 
* Navigate to Device → Jobs.
* Click Create.
* Configure:
  * Name.
  * Description (optional).
  * Enabled (or Disabled).
  * Run on Start (or Not Run on Start). 
  * Max Running. 
  * Schedule (cron).
  * Function.
  * Arguments (optional).
  * Returner.
* Create the job.

![Create New Job](/img/cloud/device_management/jobs/create_new_job.png)

### Example Jobs
1. Collecting system metrics - this job runs every 5 minutes and uploads system metrics.

    ![System Metrics Example](/img/cloud/device_management/jobs/create_system_metrics.png)

    Function used: `metrics.collect`

    Schedule (to run every 5 minutes): `*/5 * * * *`. 

2. Log device stats - this job runs every hour and uploads rpi stats. 

    ![Log Device Stats](/img/cloud/device_management/jobs/create_system_metrics.png)

    Function used: `rpi.stats`
    
    Schedule (to run every hour): `0 * * * *`. 

3. Query vehicle data - this job runs every minute to fetch engine RPM. 

    ![Query vehicle data](/img/cloud/device_management/jobs/create_engine_rpm.png)
 
    Function used: `obd.query rpm`
    
    Schedule (to run every minute): `*/1 * * * *`. 

---

## Typical Use Cases
* Periodic Data Collection: 
  * Vehicle data (RPM, speed, battery)
  * System metrics (CPU, memory, network)
* Device Monitoring:
  * Connectivity checks
  * Signal strength logging
  * Hardware status tracking
* Automation:
  * Trigger actions at intervals
  * Run diagnostics automatically
  * Synchronize data with external systems
* Fleet Operations
  * Apply consistent behavior across devices
  * Standardize data collection intervals
  * Reduce manual interaction.

### API Integration
Jobs can be managed via the [AutoPi REST API](https://api.autopi.io/). 

This enables:
* Automated provisioning.
* CI/CD integration.
* Bulk job deployment across fleets.

The Cloud UI and API provide the same functionality. You can read more about how to use API here: [Getting started with API](https://docs.autopi.io/getting_started/api/). 

---

## Summary
Cloud Jobs provide a way to:
* Automate command execution on devices
* Collect data at defined intervals
* Integrate device behavior into larger systems

They are a core building block for scalable device automation and data collection in AutoPi Cloud.

### Best Practices
* Use clear naming conventions.
* Avoid overly frequent schedules (resource impact).
* Validate commands manually before scheduling.
* Use returners appropriate for your data flow.
* Monitor job results and logs.

### Common Issues
* Job runs but returns no data.
  * Incorrect function.
  * ECU not responding (for OBD commands).
* Job does not run.
  * Invalid cron expression.
  * Job not enabled.
  * Device offline.
* High resource usage.
  * Too frequent execution.
  * Heavy commands (e.g. CAN dump).

### Best Practice Workflow
* Test command manually (terminal or CAN Analyzer).
* Define job function.
* Set appropriate schedule.
* Configure returner.
* Enable job.
* Monitor output.

---

## Loggers

Loggers are the foundation for collecting reliable device and vehicle data in AutoPi Cloud. They define what data should be captured, when it should be recorded, and how it becomes available for analysis, dashboards, triggers and alerts.

While the goal is the same across all AutoPi devices, the logging model is not identical. Some devices focus on parameter-based logging, while others use CAN channel pipelines with filtering, decoding, and output management. Because of this, using the wrong setup flow can lead to missing data, unnecessary traffic, or hard-to-debug configurations.

This guide gives you a device-specific path so you can configure logging correctly from the start. It is designed as a practical overview that helps you understand the main differences between device types, choose the right configuration approach, and validate that data is being captured as expected.

Use the section that matches your hardware:

* AutoPi Mini
* AutoPi TMU CM4
* AutoPi CAN-FD Pro

---

## Quick Comparison

| Device | Logger model | Typical setup flow |
|:---:|:---:|:---:|
| AutoPi Mini | Predefined logger list (parameter-based) | Select parameter, choose trigger mode, sync to device |
| AutoPi TMU CM4 | OBD/CAN logger model | Configure CAN bus, prepare Library items, create loggers |
| AutoPi CAN-FD Pro | CAN Logging pipeline | Configure channels, create CAN logger, add filters/decoders/outputs |

---

## AutoPi Mini

On AutoPi Mini, loggers are based on a predefined parameter catalog. The easiest path is to start from the default logger set and then add custom loggers as needed.

### Create or edit Mini loggers

1. Open your device in AutoPi Cloud.
2. Go to **Loggers**.
3. Click **Create** to add a logger, or edit an existing one.
4. Configure the logger:
   * **Parameter**
   * **Enabled**
   * **Periodic monitoring** or **Event on**
5. Save and sync the changes to the device.

![Loggers for Mini device](/img/cloud/device_management/loggers/create_mini_logger.png)

### Important behavior

* **Periodic monitoring** is recommended for continuously changing values.
* **Event on: Change** can create a high number of events for noisy values (for example voltage), which may increase data usage and affect sleep behavior.
* **Restore default** removes current logger setup and reapplies default loggers for the selected vehicle type.

For a full walkthrough, see: [Create Loggers (AutoPi Mini)](https://docs.autopi.io/getting_started/autopi_mini/create-mini-loggers/).

---

## AutoPi TMU CM4

On AutoPi TMU CM4, logger creation depends on correct CAN bus configuration and available items in your OBD Library.

### Create or edit TMU CM4 loggers

1. Ensure CAN bus protocol is configured (auto-detection, manual setup, or CAN Analyzer).
2. Prepare required items in the OBD Library:
   * PIDs
   * PGNs
   * CAN messages/signals
3. Open your device and go to **Loggers**.
4. Create or update logger definitions and sync them to the device.

![Loggers for AutoPi TMU CM4 device](/img/cloud/device_management/loggers/create_pid_logger.png)

### Best practices

* Validate protocol first to avoid empty logger output.
* Reuse Library items across devices to keep logger configuration consistent.
* When custom formulas are used, verify the returned values before applying the logger broadly.

For a complete guide, see: [Create Loggers (AutoPi TMU CM4)](https://docs.autopi.io/getting_started/autopi_tmu_cm4/create-loggers-cm4/).

---

## AutoPi CAN-FD Pro

On AutoPi CAN-FD Pro, logging is managed through **CAN Logging** and is designed for high-volume CAN/CAN-FD capture. This flow is different from Mini and TMU CM4 loggers.

### Create or edit CAN-FD Pro loggers

1. Open your device and go to **CAN Logging**.
2. Configure channels (for example can0/can1), including bitrate and autodetect settings.
3. Create a CAN logger and configure:
   * **General** settings
   * **Filters** (pass/block and frame options)
   * **Decoders** (standard or ASAM)
   * **Outputs** (local storage and optional S3)
4. Save changes and confirm runtime status.

![Loggers for AutoPi CAN-FD Pro device](/img/cloud/device_management/loggers/create_pro_logger.png)

### Best practices

* Start with passive bitrate detection when possible.
* Use filters and decoder-specific pass filters to reduce unnecessary traffic.
* Monitor logger health with `logger.status` and verify disk/S3 output behavior.

For full details, see: [User guide (AutoPi CAN-FD Pro)](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/).

---

## Verify Data in Dashboard

After creating or changing loggers on any device type:

1. Open **Dashboard**.
2. Add or edit a widget and select the relevant field.
3. Save and refresh the widget.

If a field is missing, confirm that the logger is enabled and that the device has already produced the required data.

---

## Create Custom Returners

---

This guide demonstrates how to redirect accelerometer data to a file on disk using a custom returner. The same approach applies to any data type, including OBD, GPS, and others.

1. Create a custom code module of type **Returner**. Navigate to **Device** > **Custom Code**:

  ![Create custom returner](/img/cloud/device_management/services/create_custom_returners/create_custom_returner.png) 

  The default implementation appends results to `/tmp/returner_data.txt`. This can be replaced with any storage backend or external integration.

2. Register the returner as a hook on the **acc_manager** service so it can be used in worker workflows. Navigate to **Device** > **Services** > **acc_manager** > **Hooks** > **Create**:

  ![Register custom returner hook](/img/cloud/device_management/services/create_custom_returners/register_custom_returner_hook.png) 

3. Apply the registered hook to the **xyz_logger** worker's workflow. Navigate to **Device** > **Services** > **acc_manager** > **Workers** > **xyz_logger** and change the returner from *cloud* to *my_returner*:

  ![Use custom returner in workflow](/img/cloud/device_management/services/create_custom_returners/use_custom_returner_in_workflow.png) 

Once the changes have been successfully synced to the device, it will begin logging accelerometer data to the specified file.

To monitor the output in real time over SSH, run the following command:

When logged onto the device using SSH, it is possible to monitor the data in realtime with the
command:
```python 
tail -f /tmp/returner_data.txt
```

---

## Create Custom Services

---

Services, also referred to as managers, are background processes that run independently on the device, each managed by the Salt minion parent process. If a service fails, the Salt minion automatically restarts it and reports the error.

The default services included with an [AutoPi](https://www.autopi.io) device serve as the primary communication layer between the Core software and the corresponding hardware components. This architecture makes services the ideal place to implement operations that are tightly coupled to specific hardware on the device.

## Built-in Services

The following services are available by device type:

| Service | Description | Available On |
|---|---|---|
| `acc_manager` | Manages the accelerometer hardware and provides access to motion and orientation data. | AutoPi TMU CM4, AutoPi CAN-FD Pro |
| `audio_manager` | Controls audio output on the device, such as playing sounds or alerts. | AutoPi TMU CM4, AutoPi CAN-FD Pro |
| `cloud_manager` | Handles buffering of data, and sending data in batches to the cloud server. | AutoPi TMU CM4, AutoPi CAN-FD Pro |
| `modem_manager` | Manages the cellular modem, including connectivity, signal monitoring, and data sessions. | AutoPi TMU CM4, AutoPi CAN-FD Pro |
| `event_reactor` | Listens for internal events fired by other services and triggers configured reactions in response. | AutoPi TMU CM4, AutoPi CAN-FD Pro |
| `obd_manager` | Communicates directly with the STN chip to query vehicle data over the OBD-II interface. | AutoPi TMU CM4, AutoPi CAN-FD Pro |
| `spm_manager` | Interfaces with the Smart Power Manager (SPM) to handle power states and wake-up logic. | AutoPi TMU CM4, AutoPi CAN-FD Pro |
| `gnss_manager` | Manages the GNSS/GPS module and provides location and positioning data. | AutoPi TMU CM4, AutoPi CAN-FD Pro |
| `crypto_manager` | Controls and holds the connection to the secure element. | AutoPi TMU CM4, AutoPi CAN-FD Pro |
| `can0_manager` | Manages CAN interface `can0` for CAN-FD communication workflows. | AutoPi CAN-FD Pro |
| `can1_manager` | Manages CAN interface `can1` for parallel or secondary CAN-FD communication workflows. | AutoPi CAN-FD Pro |
| `disk_housekeeper` | Performs disk cleanup and housekeeping tasks to maintain healthy storage usage. | AutoPi CAN-FD Pro |

In addition to these built-in services, it is also possible to create fully custom services that run alongside the defaults on device boot. Custom services support PIP package requirements, giving you the flexibility to integrate third-party Python libraries as needed.

## Creating a Custom Service

:::note
Ensure your device is up to date before proceeding. An outdated device may prevent module syncing from completing successfully.
:::

1. Navigate to the **Services** section and click **Create**.
2. Fill in the required fields and click **Save**.
3. The service and its associated custom module are now created.
4. Navigate to the custom module to edit the code. See the examples below for reference.
5. Sync the changes by clicking the **Sync** button, or restart the device — it will automatically pull the latest changes on boot.
6. When prompted to restart the Salt minion process, click **Yes**. The service will not be loaded until the minion has restarted. You can also restart it manually using one of the following commands:

  * In the web terminal: 
    ```python
    minionutil.restart
    ```

  * Over SSH:
    ```python
    systemctl restart salt-minion
    ```

---

## PIP Requirements

PIP requirements can be added to any custom code module as shown below:

![Adding PIP requirements](/img/cloud/device_management/services/create_custom_services/adding_pip_requirements.png) 

:::tip
Follow the standard `requirements.txt` format when specifying PIP dependencies.
:::

---

## Passing Settings Into the Service

To pass configuration into the service, set the **Settings** field to a valid JSON object:

![Passing settings to custom service](/img/cloud/device_management/services/create_custom_services/passing_settings_to_custom_service.png) 

These settings are then accessible inside the service as follows:

```python
some_setting = settings.get("some_setting", "default_value")
```
---

## Examples

### Log a Message Every 5 Seconds

The following example creates a service that writes "Hello World" to the log every 5 seconds.

```python
import logging
import time

log = logging.getLogger(__name__)

def start(**settings):
    try:
        log.info("Starting SERVICE with settings: {:}".format(settings))

        while True:
            log.info('HELLO WORLD, anything new in the last 5 seconds?')
            time.sleep(5)

    except Exception:
        log.exception("Failed to start SERVICE")

        raise
    finally:
        log.info("Stopping SERVICE")

        # Stop everything, close connections etc.
```

With `info` level logging enabled on your device, you should see the message appearing in the log every 5 seconds.

:::note
The device log level can be adjusted in the advanced settings under **System** > **Logging level**.
:::

### Service With Cloud-Configurable Workers and Failure Event Reporting

```python
import logging
import time

from common_util import factory_rendering
from messaging import EventDrivenMessageProcessor

log = logging.getLogger(__name__)

context = {
}

edmp = EventDrivenMessageProcessor("custom_service", context=context)

@factory_rendering
def start(**settings):
    try:
        log.info("Starting custom manager")

        context["settings"] = settings

        # Init the message processor
        edmp.init(__salt__, __opts__,
            hooks=settings.get("hooks", []),
            workers=settings.get("workers", []),
            reactors=settings.get("reactors", []))
        edmp.run()

        # Initialize stuff here
    
    except Exception as ex:
        log.exception("Failed to start custom manager")

        if settings.get("trigger_events", True):
            try:
                edmp.trigger_event({
                    "reason": str(ex),
                }, "system/service/{:}/failed".format(__name__.split(".")[-1]))
            except:
                log.exception("Unable to trigger service failed event")

        restart_delay = settings.get("restart_delay", 1)
        if restart_delay:
            log.info("Enforcing restart delay of {:} second(s)...".format(restart_delay))
            time.sleep(restart_delay)

        raise

    finally:
        log.info("Stopping custom manager")
        # Clean up
```

### Subscribe to MQTT Topics

The following service subscribes to all MQTT topics and logs incoming messages. Add the following PIP requirement to the module before use:

```
paho-mqtt==1.5.0
```

**Code**:

```python
import logging
import paho.mqtt.client as mqtt

log = logging.getLogger(__name__)

connect_results = {
    0: "Connection accepted",
    1: "The Server does not support the level of the MQTT protocol requested by the Client",
    2: "The Client identifier is correct UTF-8 but not allowed by the Server",
    3: "The Network Connection has been made but the MQTT service is unavailable",
    4: "The data in the user name or password is malformed",
    5: "The Client is not authorized to connect",
}

def on_message(mqttc, obj, msg):
    log.info(msg.topic + " " + str(msg.qos) + " " + str(msg.payload))

def on_subscribe(mqttc, obj, mid, granted_qos):
    log.info("Subscribed: " + str(mid) + " " + str(granted_qos))

def on_log(mqttc, obj, level, string):
    log.info(string)

def on_connect(mqttc, obj, flags, rc):
    result = "{:}: {:}".format(rc, connect_results.get(rc, "Unknown result code"))    
    if rc == 0:
        log.info(result)
    else:
        raise Exception(result)

    try:
        mqttc.subscribe("#", qos) # Subscribes to all topics.
    except Exception as ex:
        log.exception("Exception occurred when setting up registers")

# glocal settings
qos = 0

def start(**settings):
    global qos

    usetls = True
    tlsVersion = None # will use most recent version
    cacerts = None

    port = 8883
    host = ""
    username = "username"
    password = "password"

    debug = False
    keepalive = 60

    # Setup
    mqttc = mqtt.Client(None, clean_session=True)
    if usetls:
        mqttc.tls_set(ca_certs=cacerts, certfile=None, keyfile=None, cert_reqs=ssl.CERT_REQUIRED, tls_version=tlsVersion)
    mqttc.username_pw_set(username, password)

    mqttc.on_message = on_message
    mqttc.on_connect = on_connect
    mqttc.on_subscribe = on_subscribe

    if debug:
        mqttc.on_log = on_log

    try:
        log.info("Starting MQTT engine")

        log.info("Connecting to {:} port: {:}".format(host, port))
        mqttc.connect(host, port, keepalive)
        mqttc.loop_forever(retry_first_connection=True)

    except Exception:
        log.exception("Failed to start MQTT engine")

        raise
    finally:
        log.info("Stopping MQTT engine")
        mqttc.disconnect()
```

---

For further reference on writing custom services (also referred to as engines):
* [Salt documentation](https://docs.saltstack.com/en/2017.7/topics/engines/index.html).
* [Examples AutoPi.io on Github](https://github.com/autopi-io/autopi-core/tree/master/src/salt/base/ext/_engines).

---

## Create Custom Triggers

---

This guide explains how to create a custom trigger for an [AutoPi](https://www.autopi.io) service. The example used here is a trigger that plays a beep sound when the vehicle speed reaches or exceeds 50 km/h.

:::note
Service triggers are distinct from [Cloud](https://www.autopi.io/software-platform/cloud-management) triggers. Service triggers run **on the device** and respond to data produced by a handler — for example by emitting events or playing audio. Cloud triggers, by contrast, respond to events emitted by the device and execute **on the server side**.
:::

1. Create a custom code module named *my_triggers* with the type **Execution**. Navigate to **Device** > **Custom Code**:

  ![Editing custom code](/img/cloud/device_management/services/create_custom_triggers/editing_custom_code.png) 

  Here is the complete code:

  ```python
  import logging
  
  from messaging import extract_error_from
  
  log = logging.getLogger(__name__)
  
  def speed_warning_beep(result):
      """
      Trigger that will play a warning beep sound when vehicle speed exceeds value of 50.
      """
  
      # Check for error result
      error = extract_error_from(result)
      if error:
          log.warning("Speed warning beep trigger got error result: {:}".format(result))
  
          return
  
      # Check if speed value is above threshold
      if result.get("value", 0) >= 50:
  
          # Only play sound when threshold value is exceeded
          if not __context__.get("speed_warning_beep", False):
              __salt__["cmd.run"]("aplay /opt/autopi/audio/sound/beep.wav")
  
              # Set flag in context
              __context__["speed_warning_beep"] = True
  
      # Speed value is below threshold
      else:
  
          # Reset flag in context
          __context__["speed_warning_beep"] = False
  ```

  This function checks whether the result contains a `value` key with a value of 50 or higher. When the threshold is first crossed, it plays a beep sound. A context flag is used to ensure the sound does not play repeatedly while the vehicle remains above the threshold. When the speed drops below 50 km/h, the flag is reset.

  Once the code is ready, sync the changes to the device by clicking **Sync**. If the device is offline, the changes will be applied automatically on next start-up.

2. Register the trigger as a hook on the **obd_manager** service. Navigate to **Device** > **Services** > **obd_manager** > **Hooks** > **Create**:

  ![Creating a custom hook](/img/cloud/device_management/services/create_custom_triggers/creating_a_custom_hook.png) 

4. Add the registered trigger hook to a worker workflow. Navigate to **Device** > **Services** > **obd_manager** > **Workers** > **Create**:

  ![Creating a new worker](/img/cloud/device_management/services/create_custom_triggers/creating_a_new_worker.png) 

  Once the changes have been successfully synced to the device, it will begin monitoring vehicle speed and play a single beep when 50 km/h is exceeded.

  :::note
  The `query` handler with a `SPEED` argument is supported on most internal combustion engine (ICE) vehicles. For electric vehicles, a different approach may be required. Consult your vehicle's make and model forums for guidance.
  :::

  :::tip Not Working?
  Check the device logs for warnings or errors. See [this guide](/developer_guides/autopi_logs.md) for instructions on retrieving logs from your device.
  :::

## Firing an Event Instead of a Beep

Events can also be fired from custom code modules. To trigger one or more actions based on a condition — in this case, exceeding 50 km/h — add the following function to the *my_triggers* module:

```python
def speed_warning_event(result):
    """
    Trigger that will fire a 'vehicle/speeding' event when vehicle speed exceeds value of 50.
    """

    # Check for error result
    error = extract_error_from(result)
    if error:
        log.warning("Speed warning event trigger got error result: {:}".format(result))

        return

    # Check if speed value is above threshold
    if result.get("value", 0) >= 50:

        # Only play sound when threshold value is exceeded
        if not __context__.get("speed_warning_event", False):
            __salt__["event.fire"]({}, "vehicle/speeding")

            # Set flag in context
            __context__["speed_warning_event"] = True

    # Speed value is below threshold
    else:

        # Reset flag in context
        __context__["speed_warning_event"] = False
```

This function follows the same logic as the previous example, but fires an internal event instead of playing a sound. The event will be sent to the `event_reactor` service for further processing and will also appear in the [Cloud](https://www.autopi.io/software-platform/cloud-management) under **Device** > **Events**.

---

## Create Custom Workers

---

This guide covers how to create workers for any available service — whether it is a default service such as the OBD manager, or a custom one you have built yourself. It begins with an overview of what workers are and how they function, then walks through a practical example: creating a worker that continuously fetches OBD data and saves it to a file.

![Service list](/img/cloud/device_management/services/create_custom_workers/service_list.png) 

## Workers

A worker is a process executed by a manager according to a defined [workflow](/core/services/index.md). Each workflow consists of a series of ordered steps that produce a desired output.

![Worker list](/img/cloud/device_management/services/create_custom_workers/worker_list.png) 

### Creating a Worker

Start by selecting the appropriate manager for your use case. For example, use `obd_manager` to read OBD data, or `ec2x_manager` to execute AT commands not implemented by default.

For this guide, a worker will be created inside the `obd_manager`. Navigate to **Device** > **Services** and select the `obd_manager` entry. From the manager's home page, click **+ Create** to open the worker creation window:

![Create empty worker](/img/cloud/device_management/services/create_custom_workers/create_worker_empty.png) 

The creation window contains the following fields:

1. **Name** — A descriptive name for the worker, used for identification purposes.

2. **Delay** — The number of seconds to wait before the worker begins its first execution loop.

3. **Interval** — The time (in seconds) between each execution loop.

4. **Loop** — The number of times the worker will execute within a single power cycle of the [AutoPi](https://www.autopi.io) device:
    - *Less than 0*: The worker loops indefinitely.
    - *0 or more*: The worker executes the specified number of times and then stops. Total executions equal the loop count plus one.

5. **Order** — Determines the execution order relative to other workers in the same service. Workers with a lower order value execute first.

6. **Transactional** — When enabled and a workflow fails, all subsequent workflows on the same worker are skipped. When disabled, remaining workflows continue to execute regardless of prior failures.

### Workflows

Each workflow is represented as a row in the table and consists of the following columns:

1. **Handler** — The first step in the workflow. Communicates directly with the device hardware and produces the initial output.

2. **args** — Positional arguments passed to the handler.

3. **kwargs** — Keyword arguments passed to the handler.

4. **Converter** — Transforms the handler output into a more usable form.

5. **Trigger** — Executes logic based on the handler result, such as [playing a beep sound](/cloud/device_management/a-guide-to-triggers/).

6. **Filter** — Determines whether the data is significant enough to continue processing. If a [falsy](https://stackoverflow.com/questions/39983695/what-is-truthy-and-falsy-how-is-it-different-from-true-and-false) value is returned (e.g. `False`, `None`, or an empty string), execution stops.

7. **Enricher** — Augments the data by adding computed or supplementary values.

8. **Returner** — Delivers the result to a destination, such as [saving it to a file](/cloud/device_management/services/create-custom-returners/) or forwarding it to a cloud platform. The built-in [Cloud](https://www.autopi.io/software-platform/cloud-management) returner, for example, sends data to [my.autopi.io](https://my.autopi.io/).

All of the above — except **args** and **kwargs** — are referred to as *hooks* and are covered in the next section.

Available handlers vary by service. For a full reference, see [the services page](/core/services/index.md). For this guide, the [query](/core/services/core-services-obd-manager/#query) handler will be used to continuously query OBD data.

Arguments (`args`) and keyword arguments (`kwargs`) are specified in JSON format — note that JSON requires double quotes rather than single quotes. To read the fuel level, specify the following `args`:

```json
[ "FUEL_LEVEL" ]
```

The `kwargs` are optional but provide additional control over execution:

```json
{
    "mode": 1,
    "force": true
}
```

With the handler configured, the remaining workflow steps are optional and depend on your use case. To persist the data, add a returner — see the [Create Custom Returners](/cloud/device_management/services/create-custom-returners/) guide for details. The completed worker configuration looks like this:

![Create worker completed](/img/cloud/device_management/services/create_custom_workers/create_worker_completed.png)

Click **Save** and allow the device to sync the changes. After a service restart, the device will begin executing the new worker.

### Hooks

Custom hooks can be created by adding a new custom code module under **Device** > **Custom Code** with an execution type. Each hook must then be registered to the relevant service via the **Hooks** tab.

All hooks must follow this function signature:

```python
def some_function_name(result):
    # work with result and return some manipulated value
    return value
```

The function receives a result and returns a value. If a falsy value is returned at any point in the workflow, execution of subsequent steps will stop. **The exception to this rule is triggers** — they always execute, even if an earlier step fails or raises an exception. This ensures that time-sensitive logic in triggers is never skipped.

### Troubleshooting

#### The service does not start, or no logs are appearing
1. Verify that the service is enabled in the [Cloud](https://www.autopi.io/software-platform/cloud-management) and that it is listed in the engines file at `/etc/salt/minion.d/engines.conf`.
2. Confirm that the associated custom module contains valid Python code.
3. Enable debug logging on the device via the advanced settings, restart the Salt minion, and review the logs for errors.

To filter logs for a specific service, run the following command on the device:

```python
sudo tail -f /var/log/salt/minion | grep service_name
```

## Conclusion

Workers are a powerful mechanism for interacting with the hardware components of an [AutoPi](https://www.autopi.io) device or your vehicle. They can run continuously or for a fixed number of iterations, and their workflows can be composed to achieve complex outcomes without writing custom code. Make use of them whenever you need reliable, repeatable communication with device hardware.

---

## Services

---

Services, also referred to as managers, are background processes that run independently on the device, each managed by the Salt minion parent process. If a service fails, the Salt minion automatically restarts it and reports the error.

The default services included with an [AutoPi](https://www.autopi.io) device serve as the primary communication layer between the Core software and the corresponding hardware components. This architecture makes services the ideal place to implement operations that are tightly coupled to specific hardware on the device.

![Services Table](/img/cloud/device_management/services/services_table.png)

## Built-in Services

The following services are available by device type:

| Service | Description | Available On | Core Specs |
|:---:|:---:|:---:|:---:|
| `acc_manager` | Manages the accelerometer hardware and provides access to motion and orientation data. | AutoPi TMU CM4, AutoPi CAN-FD Pro | [acc_manager](https://docs.autopi.io/core/services/core-services-acc-manager/) |
| `audio_manager` | Controls audio output on the device, such as playing sounds or alerts. | AutoPi TMU CM4, AutoPi CAN-FD Pro | [audio_manager](https://docs.autopi.io/core/services/core-services-audio-manager/) |
| `cloud_manager` | Handles buffering of data, and sending data in batches to the cloud server. | AutoPi TMU CM4, AutoPi CAN-FD Pro | [cloud_manager](https://docs.autopi.io/core/services/core-services-cloud-manager/) |
| `modem_manager` | Manages the cellular modem, including connectivity, signal monitoring, and data sessions. | AutoPi TMU CM4, AutoPi CAN-FD Pro | [modem_manager](https://docs.autopi.io/core/services/core-services-modem-manager/) |
| `event_reactor` | Listens for internal events fired by other services and triggers configured reactions in response. | AutoPi TMU CM4, AutoPi CAN-FD Pro | [event_reactor](https://docs.autopi.io/core/services/core-services-event-reactor/) |
| `obd_manager` | Communicates directly with the STN chip to query vehicle data over the OBD-II interface. | AutoPi TMU CM4 | [obd_manager](https://docs.autopi.io/core/services/core-services-obd-manager/) |
| `spm_manager` | Interfaces with the Smart Power Manager (SPM) to handle power states and wake-up logic. | AutoPi TMU CM4, AutoPi CAN-FD Pro | [spm_manager](https://docs.autopi.io/core/services/core-services-spm-manager/) |
| `gnss_manager` | Manages the GNSS/GPS module and provides location and positioning data. | AutoPi TMU CM4, AutoPi CAN-FD Pro | [gnss_manager](https://docs.autopi.io/core/services/core-services-gnss-manager/) |
| `crypto_manager` | Controls and holds the connection to the secure element. | AutoPi TMU CM4, AutoPi CAN-FD Pro | [crypto_manager](https://docs.autopi.io/core/services/core-services-crypto-manager/) |
| `can0_manager` | Handles communication to and from the vehicle via the SocketCAN `channel_1` interface. | AutoPi CAN-FD Pro | [can_manager](https://docs.autopi.io/core/services/core-services-can-manager/) |
| `can1_manager` | Handles communication to and from the vehicle via the SocketCAN `channel_2` interface.  | AutoPi CAN-FD Pro | [can_manager](https://docs.autopi.io/core/services/core-services-can-manager/) |
| `disk_housekeeper` | Performs file deletion to avoid the disks running full. | AutoPi CAN-FD Pro | [disk_housekeeper](https://docs.autopi.io/core/commands/core-commands-disk-housekeeper/) |

In addition to these built-in services, it is also possible to create fully custom services that run alongside the defaults on device boot, you can read more here: [Create Custom Service](https://docs.autopi.io/cloud/device_management/services/create-custom-services/). Custom services support PIP package requirements, giving you the flexibility to integrate third-party Python libraries as needed.

---

## Configuring a Service

Clicking on any service in the list opens its detail page, which is organized into four tabs:

![Configuring a Service](/img/cloud/device_management/services/services_edit.png)

### Workers

Workers define workflows that run continuously on the device. Each worker executes a sequence of steps — referred to as a workflow — at a configurable interval and loop count. Workers are the primary mechanism for reading data from hardware, transforming it, and delivering it to a destination.

See the [Create Custom Workers](/cloud/device_management/services/create-custom-workers/) guide for a full walkthrough.

Within a service multiple worker threads can run. Each worker is setup to process one or more workflows sequentially for a limited period of time or indefinitely, you can read more here: [Workers](https://docs.autopi.io/core/services/#workers). 

Available options for a worker instance:

| Field | Type | Description | Default Value |
| :------: | :------: | :------: | :------: |
| `name` | Text | System name to identify the given worker. | - |
| `delay` | Decimal | Initial delay in seconds before starting the worker. No delay if left empty. | - |
| `interval` | Decimal | Pause in seconds between each run. Enter `0` if no pause. | `1` |
| `loop` | Integer | How many runs should the worker do? Enter `-1` if infinite. | `-1` |
| `suppress_exceptions` | Boolean | Suppress errors/exceptions so that they do not kill the worker thread? | `True` |
| `kill_upon_success` | Boolean | Kill the worker thread after the first successful run? Successful means that no errors/exceptions occurred. | `False` |
| `transactional` | Boolean | Ensure that consecutive workflows are processed in an uninterrupted sequence and not potentially mixed with others from other workers? | `False` |

### Reactors

Reactors allow the device to respond to incoming events. Each reactor defines a regex pattern to match against event names, along with one or more actions to execute when a match is found. This makes it straightforward to implement event-driven logic directly on the device.

Reactors can be managed using the `reactor.manage` command, which provides runtime control over the reactor service. 

Supported commands: 
``` python
reactor.manage reactor list
reactor.manage reactor show <name>
``` 

See the [Reactors](https://docs.autopi.io/core/services/#reactors) guide for a full walkthrough.

### Hooks

Hooks extend the behavior of a worker's workflow by registering custom functions at specific points in the pipeline. When creating a hook, you can select one of the following types:

| Hook Type | Description |
|:---:|:---:|
| **Handler** | The entry point of the workflow. Communicates with the device hardware and produces the initial output. |
| **Converter** | Transforms the handler output into a more usable format. |
| **Trigger** | Executes logic based on the result, regardless of whether earlier steps failed. Useful for alerts and events. |
| **Filter** | Determines whether the data is significant enough to continue processing. Returns a falsy value to halt the workflow. |
| **Enricher** | Augments the data by appending computed or supplementary values. |
| **Returner** | Delivers the final result to a destination, such as a file or a cloud endpoint. |

See the [Create Custom Workers](/cloud/device_management/services/create-custom-workers/) guide for more detail on how hooks fit into the workflow pipeline. 
Also we have a guides on how to create a custom returners and triggers to fit into your use case, check them out: 
* [Create Custom Returners](https://docs.autopi.io/cloud/device_management/services/create-custom-returners/)
* [Create Custom Trigger](https://docs.autopi.io/cloud/device_management/services/create-custom-triggers/)

### Settings

The Settings tab allows you to adjust the configuration of the service without modifying its code. Settings are passed as a JSON object and are accessible from within the service at runtime, making it easy to tune behavior per environment or deployment.

![Settings on Service](/img/cloud/device_management/services/services_settings.png)

---

## Workflows

A worker can process one or more workflows in a sequence. A worflow consists of a number of steps. The primary step of a workflow is called __`handler`__ and is always required. Then more steps may occur both before and/or after, and are not normally required. At present, there are two built-in workflows. Below is an overview of the steps in the first workflow called `simple`:

| __`handler`__ | → | _`trigger`_ | → | _`filter`_ | → | _`returner`_ |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ |

And secondly the `extended` workflow:

| _`validator`_ | → | __`handler`__ | → | _`converter`_ | → | _`trigger`_ | → | _`filter`_ | → | _`enricher`_ | → | _`returner`_ |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |

Each step in a workflow has a defined area of responsibility:

| Step | Description | Example |
| ------ | ------ | ------ |
| _`validator`_ | Validates the request and decide whether or not to proceed to the handler. | - |
| __`handler`__ | Produces a result typically by interacting with an external device or system. | [See](https://docs.autopi.io/core/services/core-services-obd-manager/#handlers) |
| _`converter`_ | Converts the result returned from the handler into a more usable format. | [See](https://docs.autopi.io/core/services/core-services-obd-manager/#converters) |
| _`trigger`_ | Decides whether to trigger an event based on the result. | [See](https://docs.autopi.io/core/services/core-services-obd-manager/#triggers) |
| _`filter`_ | Filters out result if insignificant. | [See](https://docs.autopi.io/core/services/core-services-obd-manager/#filters) |
| _`enricher`_ | Enriches result with additional information. Could for example be calculations. | [See](https://docs.autopi.io/core/services/core-services-acc-manager/#enrichers) |
| _`returner`_ | Returns the final result to an external system or service. | [See](https://docs.autopi.io/core/returners/) |

---

## Software Updates

---
Keeping your AutoPi device up to date ensures you have access to the latest features, improvements, and bug fixes. This guide explains how to update your device and how to monitor update activity.

## Updating Your Device

There are two main ways to update your device:
1. Update through the AutoPi Cloud (recommended). 
2. Update using a command (not supported for AutoPi Mini devices). 

### Update Through the AutoPi Cloud 

This is the most common and recommended method on how to queue a software update on a device.

![software-updates-page](/img/cloud/device_management/software-updates/software-updates-page.jpg)

1. Navigate to **Device → Software Updates** in the AutoPi Cloud.
2. Click the **Update on startup** button (top-right corner).
3. Confirm whether you want to update immediately or not. 

#### Update behavior:
* If you choose to update immediately and device is online, the process starts right away. 
* If you don't update the device right now but queue it, the device will try to perform the update before going to sleep if it's currently online, or on next start up if it's currently offline. Whether or not the update is performed successfully, the device will go to sleep right after, but if the update failed, it will be retried after it wakes up every time until the update goes through.

#### Automatic Updates

If enabled, the device will update automatically based on your configuration under Device > Advanced Settings > Update Release:
* **Before sleep**
* **At startup (or before sleep)**. 

### Update With a Command

> **Tip:** This method should only be used when necessary. 

To perform a manual update on your device, you can run the command below through the web terminal. Using this method will still show an update attempt on the Software Updates page in case you need to review the update afterwards.

```python
minionutil.update_release force=True
```

> ⚠️ Always run this command from the Cloud terminal, not directly on the device. Running it locally may result in incomplete or incorrect updates.
---

## Check if Your Device is Already Performing an Update

Before starting an update, it’s useful to verify whether the device is already performing one. There are two general ways that you can determine if an update is currently being run on your device:
* Using the events tab.
* Running a command. 

### Method 1: Events Tab

One of the ways to determine if the device is being updated right now is to check the events from the device by navigating to Device > Events. 

* Events showing **Update in progress**:
  * [`system/release/*`](/cloud/device_management/events/system.md#release-events)
  * `system/release/pending`
  * `system/release/retrying`
  * `system/release/forcing`.

* Events showing **Update completed or stopped**:
  * `system/release/updated`
  * `system/release/failed`
  * Power-related events (e.g. shutdown).

You can also check events directly on the device by running: 

```python
reactor.manage context cache
``` 

If this list of events contains the above mentioned `system/release/pending`, that means the device us currently applying the update. This is done either during the startup or before sleep, based on your settings. 

### Method 2: Command: `saltutil.running`

With the `saltutil.running` command you can check the jobs the device is currently running. Using this command,
you can also determine if your device is currently updating. 

First possible response: 

```python
$ saltutil.running
- fun: state.sls
  jid: req
  pid: 1124
  ret: ''
  arg:
    - - startup
```

  The above response is returned usually when the device has just booted up. It signifies that the `startup` state is being executed (there is a small startup procedure whenever the device starts up and is connected to the server). If you have enqueued an update or your device is setup to try the update as soon as it starts up, a response like the one above would mean that the update is being attempted. 
  

Another possible response:

```python 
$ saltutil.running
- jid: '20220610114357378648'
  pid: 1630
  _stamp: '2022-06-10T11:43:57.382915'
  ret: event_result
  arg:
    - shutdown
    - pillar:
        allow_auto_update: true
      __kwarg__: true
  fun: state.sls
- tgt_type: glob
  jid: '20220610114357091317'
  tgt: 629c06b123213bf84126afecd44a0340
  pid: 1627
  ret: ''
  user: 2
  arg:
    - __kwarg__: true
      confirm: true
  fun: power.sleep
```

  This one is a bit more complex to look at, but there are a few key things to look at here. The response shows us that there are two jobs running - let's start with the second job. That job tells the reader that the device is going to go to sleep (notice the `fun: power.sleep` line). The `power.sleep` function will put the device to sleep, but first, it will execute the `shutdown` state. That `shutdown` state is the first job on the list returned above and it is the one that triggers the update as well. Notice the `allow_auto_update: true` argument, which signifies the device is most likely attempting the update right now. This type of response is usually seen when the device has been "forced" to update or it has been setup to attempt updates right before shutting down.

---

## Viewing Update Attempts

You can review all update attempts under Device > Software Updates. Click on a specific update to open the Update Run details.

Update run states:
* Success - states that have been executed without error, but have made no changes on the device. 
* Changed - states that have been executed without error and have made a change on the device.
* Failed - states that have been executed with an error. Those states usually have comments to try and explain what has gone wrong.

![update-release-run](/img/cloud/device_management/software-updates/update_runs.png)

This view helps you understand:
* What steps were executed.
* Which steps succeeded or failed.
* Where issues occurred (if any).

---

## Summary
* Use AutoPi Cloud for standard updates.
* Use manual command for update only when necessary.
* Always check if an update is already running before starting a new one.
* Review update attempts to troubleshoot issues.

Keeping your device updated ensures stable performance and access to the latest improvements.

---

## Templates

---

## What are Templates?

Templates let you define a reusable device configuration and apply it to many devices at once. Instead of repeating setup on each device, you configure it once in a template and then apply that template whenever needed.

This approach helps you:
* Scale deployments faster.
* Keep configuration consistent across devices.
* Reduce manual errors and maintenance overhead.

![Templates overview](/img/cloud/device_management/templates/templates_table.png)

## Highlighted Template Features

Templates can include most cloud-managed configuration elements, including:
* Advanced settings.
* Custom code.
* Services.
* Loggers/CAN Logging.
* Triggers.
* Jobs.
* Geofences.
* Locations. 
* Vehicle Groups. 

Each configured item becomes part of your reusable template baseline.

## Quick Start

Use this workflow for day-to-day template management:
1. Create a template.
2. Configure the template (settings + functional sections).
3. Assign devices.
4. Apply template.

Once applied, all selected devices will inherit the configuration defined in the template.

---

## Step 1: Create a New Template

Create a template that will serve as your baseline configuration.

![Create new template](/img/cloud/device_management/templates/create_new_template.png)

Steps:
* Navigate to the Templates section.
* Click **Create**.
* Fill in:
  * **Template name**: use a clear, descriptive name.
  * **Description**: add context so the template is easy to identify.
  * **Type** (optional): choose the correct device type:
    * *Default* is meant to be used for AutoPi TMU CM4 and CAN-FD Pro devices.
    * *Mini* is meant to be used for AutoPi Mini devices.
  * **Parent** (optional): select a parent template to inherit its configuration.
* Click **Create**. The template will appear in the Templates table.

## Step 2: Configure Template Settings

Open any template, then click **Settings**. This section controls the template identity and shared associations.

![Template's settings](/img/cloud/fleet_management/vehicles/geofences/template_geofences.png)

Available settings:
* **Name**: change the template name.
* **Description**: add or update a description.
* **Parent** (optional): choose another template as parent. This template becomes a child template and inherits parent configurations.
* **Default bus** (optional): select the bus that should be used as default on devices in this template.
* **Geofences** (optional): associate fleet geofences with the template.
* **Locations** (optional): associate locations with the template.
* **Groups** (optional): associate vehicle groups with the template.

Click **Save** to apply the changes.

## Step 3: Define Functional Configuration

After the Settings section is configured, define the behavior you want all assigned devices to inherit.

Templates support most options available on individual devices, while excluding highly device-specific options to preserve reusability.

#### Advanced Settings

Most advanced settings can be configured on templates.

![Advanced settings for templates](/img/cloud/device_management/templates/custom_configuration.png)

The configuration table shows all key/value pairs currently associated with the template. To update settings:
* Click **Edit** to open the advanced settings UI.
* Make your changes.
* Click **Save**.

![Templates' Advanced Settings](/img/cloud/device_management/templates/templates_advanced_settings.png)

To learn more about individual settings, refer to the relevant guides:
* For AutoPi Mini devices: [Advanced settings for Mini](https://docs.autopi.io/cloud/device_management/advanced_settings/autopi_mini/)
* For AutoPi TMU CM4 devices: [Advanced settings for TMU CM4](https://docs.autopi.io/cloud/device_management/advanced_settings/autopi_tmu_cm4/)

#### Custom Code

Custom modules are created in templates similarly to individual devices.

![Custom code table](/img/cloud/device_management/templates/custom_code_table.png)

When creating a custom module of type **Service**, a corresponding custom service is automatically created and associated with the same template.

![Example of the custom code](/img/cloud/device_management/templates/create_custom_code.png)

To learn more about how to create a custom code, refer to the relevant guide: [Custom Code](https://docs.autopi.io/cloud/device_management/custom-code/). 

#### Services

Services (managers) are background processes running on the device and supervised by Salt Minion.

![Services on template](/img/cloud/device_management/templates/services_table.png)

Default AutoPi services provide the interface between Core software and hardware components. For example, `obd_manager` handles communication with the STN chip. Templates also support custom services, including required Python packages.

![Example of the service](/img/cloud/device_management/templates/create_services.png)

:::note
To override a default service (for example `obd_manager`) through a template, create a custom service with the same name.
:::

To learn more about individual services, refer to the relevant guides:
* [Services](https://docs.autopi.io/cloud/device_management/services/).
* [Creating Custom Services](https://docs.autopi.io/cloud/device_management/services/create-custom-services/). 

#### Loggers 

Logging setup is device-specific. Use the correct flow for your device type.

* **AutoPi TMU CM4 (Loggers tab)**:
  * Template logger creation is intended for TMU CM4 workflows.
  * Creating a logger in a template also creates a bus associated with that template.
  * Before creating template loggers, prepare CAN Messages, CAN Signals, or PIDs in OBD Library/My Library. 
* **AutoPi Mini**:
  * Mini uses a different logger layout as the device above, focused on predefined parameters and trigger modes.
  * Follow the Mini logger flow in [Loggers](https://docs.autopi.io/cloud/device_management/loggers/).
* **AutoPi CAN-FD Pro**:
  * CAN-FD Pro uses a separate **CAN Logging** tab, not the standard logger flow.
  * Configure channels, filters, decoders, and outputs in the CAN Logging workflow.
  * See [Loggers](https://docs.autopi.io/cloud/device_management/loggers/) for the device-specific overview or [User Guide for Pro device](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/). 

If you want to learn more about about different device types flows and their comparison, check out this guide: [Loggers](https://docs.autopi.io/cloud/device_management/device-loggers/).

##### AutoPi TMU CM4 

For TMU CM4 template loggers, you can create:
* [Create CAN Signal Loggers](https://docs.autopi.io/cloud/obd-ii/create-can-signal-loggers/)
* [Create PID Loggers](https://docs.autopi.io/cloud/obd-ii/create-pid-loggers/)

![Loggers table](/img/cloud/device_management/templates/loggers_table.png)

Before creating template loggers, prepare CAN Messages, CAN Signals, or PIDs in OBD Library/My Library. If you want to learn more about the whole process check out this guide: [Create Loggers for AutoPi TMU CM4](https://docs.autopi.io/getting_started/autopi_tmu_cm4/create-loggers-cm4/).

##### AutoPi Mini 

For AutoPi Mini templates, logger setup uses the Mini logger layout with parameter-based configuration.

![Loggers Tab for Mini Devices](/img/cloud/device_management/templates/templates_mini_loggers.png)

To create a new logger:
1. Open a template of type **Mini**.
2. Go to the **Loggers** page.
3. Click **Create**.
4. Configure the logger:
   * Select the logger from the **Parameter** dropdown.
   * Set whether the logger should be **Enabled**.
   * Choose the trigger mode: **Periodic monitoring** or **Event on**.
5. Click **Save**.

Repeat this process to add as many loggers as needed for your Mini deployment.

##### AutoPi CAN-FD Pro 

For AutoPi CAN-FD Pro templates, logging is managed through the **CAN Logging** tab, not the standard **Loggers** page used by AutoPi TMU CM4 and AutoPi Mini.

This tab is available only for Pro device templates. If CAN Logging configuration is applied to other device types, those Pro-specific settings are ignored during template apply.

![CAN Logging Tab](/img/cloud/device_management/templates/templates_pro_can_logging.png)

In the **CAN Logging** tab, you can configure:
* **Channels**: add or edit channel definitions.
* **Loggers**: add or edit loggers.
* **Queries**: add or edit queries.
* **Frame Listeners**: add or edit frame listeners.
* **Event Reactors**: add or edit event reactors.
* **Workflow Hooks**: add or edit workflow hooks.

Because CAN-FD Pro logging includes many advanced capabilities, use the [User Guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/) to ensure a correct end-to-end setup.

#### Triggers 

Triggers send notifications when specific events or signals occur on a device. Conditions can be added so triggers fire only when defined criteria are met.

![Triggers](/img/cloud/device_management/templates/triggers_table.png)

When a device reports data to cloud, the system evaluates trigger rules based on event tag or signal name, plus any defined conditions.

Supported trigger actions include: 
* Send an email.
* Send webhook request.
* Create an alert.

Example of setting up a new trigger: 

![Example of trigger](/img/cloud/device_management/templates/create_trigger.png)

To learn more about individual settings, refer to the relevant guide: [A Guide to Triggers](https://docs.autopi.io/cloud/device_management/a-guide-to-triggers/).

#### Jobs 

Jobs allow you to schedule commands to run on devices. Results can be uploaded to AutoPi Cloud or external systems using returners.

![Jobs](/img/cloud/device_management/templates/jobs_table.png)

Example of the Job for getting CPU core temperature: 

![Example of Job](/img/cloud/device_management/templates/create_job.png)

To learn more about individual settings, refer to the relevant guide: [A Guide to Jobs](https://docs.autopi.io/cloud/device_management/cloud-jobs/). 

#### Geofences 

:::note
Templates currently support both device geofences and fleet geofences. Fleet geofences are included in the Settings under template, you can read more here: [Use Fleet Geofences with Templates](https://docs.autopi.io/cloud/fleet_management/vehicles/fleet-geofences/#use-fleet-geofences-with-templates).
:::

Device geofences allow you to define geographic areas and receive notifications when a vehicle enters or exits those areas. Geofences can be defined as a polygon shape, or a point with a radius.

![Creation of device geofence](/img/cloud/device_management/templates/create_device_geofence.png)

To learn more about individual settings, refer to the relevant guide: [A Guide to Device Geofences](https://docs.autopi.io/cloud/device_management/geofences/).

## Step 4: Assign Devices and Apply Template

Once the template is configured, assign devices and apply changes.

* Navigate to the Templates table.
* Open the template and go to the **Devices** page.
* Click **Add** and select devices to assign.
* After assigning devices, click **Apply template** (upper-right corner) and choose one of the following:
  * Apply all async.
  * Apply all async + all descendants.

After apply completes, assigned devices receive the full template configuration.

---

## How to Work with Templates Efficiently

The main value of templates is operational efficiency at scale:
* Configure once in the template.
* Add as many devices as needed.
* Apply the template to push all configured functionality in one workflow.

This avoids repeating manual setup on each device and helps keep fleet behavior consistent over time.

Recommended operating model:
1. Keep template configuration as the source of truth.
2. Minimize manual per-device changes after template assignment.
3. Reapply template whenever shared configuration is updated.
4. Use parent/child templates to inherit common baseline settings and specialize only where needed.

:::tip
For reproducible results, keep device-level configuration as clean as possible and limit manual changes on devices that use templates. This reduces conflicts between manual updates and template-applied configuration.
:::

---

## Variables

---

The **Global Variables** feature allows Account Administrators to define custom key-value pairs that can be reused across templates. This makes it easy to apply consistent configurations such as stream IDs, API keys, or environment-specific values without manually updating each template or device.

When needed, global variables can be overridden on individual devices via the **Variables** page on the device, providing flexibility where device-specific values are required.

:::note
Global Variables are available only to users with **Account Administrator** permission. You can learn more about permissions in AutoPi Cloud here:  
[Accounts permissions](https://docs.autopi.io/cloud/accounts/)  

Even without administrator permissions, variables can always be viewed on a specific device under the **Variables** tab.
:::

---

## What Are Variables?

Variables are reusable **key-value pairs** that can be referenced inside templates. They function as **keyword replacements**, meaning their values are dynamically injected when a template is applied.

You can read more about how to use: [Global Variables](https://docs.autopi.io/cloud/device_management/global-variables/).

You can read more about how to set up templates: [Templates](https://docs.autopi.io/cloud/device_management/templates/).

### Common Use Cases

* Storing an `API_KEY` for an external service and reusing it across multiple templates.
* Defining unique stream IDs or identifiers once and referencing them everywhere.  
* Keeping templates generic while injecting device- or account-specific values. 

Using variables saves time, reduces configuration errors, and ensures consistency across devices.

---

## How to Create Device Variables

To create or manage variables on a specific device:

1. Navigate to the **Device** and open the **Variables** tab.  
2. Click **Create**.  
3. Enter the following details:
   * **Key** – The variable name (for example, `API_KEY`).
   * **Value** – The value assigned to the variable.
   ![Create a Device Variable](/img/cloud/device_management/variables/create_device_variable.png)

4. Click **Save**.

The new variable will now appear in the variables table for that device.

---

## How to Use Global and Device Variables

### Example of a Global Variable

AutoPi Cloud includes several default environment variables. One example is the device Unit ID:

* `AUTOPI_UNIT_ID` – Holds the unique device unit ID  
  * Format: `00000000-0000-0000-0000-000000000000`

When applying templates:

* Global variables can be used as **placeholders**.
* These placeholders are replaced with the defined values at runtime.
* Variables are referenced using the following format:

```python
$AUTOPI_UNIT_ID
```

Once applied, environment variables are synced to the device and are available to any custom service. This allows templates and services to remain generic while values are injected dynamically.

### Device Variables  
In some scenarios, a global variable may need to be overridden for a specific device. When this happens, the variable becomes a **Device Variable** for that device only.

![Device Variables Table](/img/cloud/device_management/variables/variables_table.png)

Example:  
* Global API key = `Office123`.  
* Device override for Device A = `Home456`. 

**To override a variable:**
* Navigate to Device -> Variables.
* Find the variable you want to override. 
* Click "Override" button.
* Edit the value as needed and click Save. 

The table will now show both the global value and the device-specific override.

---

## Docker(Cloud)

---

## What Is Docker Support on AutoPi?

AutoPi devices and the AutoPi Cloud natively support running **Docker containers** directly on the device. This enables you to package applications, scripts, or services into standardized container images and deploy them to AutoPi devices remotely from the cloud — without requiring physical access to the hardware.

The AutoPi Cloud acts as the central control plane for container management. It handles **registries** (image storage), **projects** (application grouping), and **releases** (deployment versions), automatically coordinating image delivery and container startup across one or more devices.

![Docker on AutoPi Cloud](/img/cloud/device_management/docker/docker_page.png)

---

## Why Run Docker on an AutoPi Device?

AutoPi devices function as edge computers installed in vehicles, continuously collecting real-time data from vehicle systems (CAN bus, GPS, OBD-II, sensors) while maintaining network connectivity. Running Docker containers alongside the AutoPi core software enables you to:

| Benefit | Description |
|:---:|:---:|
| **Edge processing** | Run computations directly on the vehicle rather than transmitting all raw data to the cloud, reducing bandwidth consumption and latency. |
| **Custom integrations** | Deploy any software stack without modifying the AutoPi core system. |
| **Independent updates** | Update your application container independently of the AutoPi firmware. |
| **Isolation** | Containers are isolated from the host system, reducing the risk of dependency conflicts. |
| **Reproducibility** | The same container image runs identically on every device in your fleet. |

---

## How It Works

The deployment flow is built around three core concepts in the AutoPi Cloud:

  Docker Registry
  →
  Project
  →
  Release
  →
  AutoPi Device

**Registry** stores your container images and provides authentication credentials that devices use to securely pull images at deployment time.

**Project** groups related application releases together, serving as a logical container for all versions of your application within AutoPi Cloud. You must create a project before you can create any releases.

**Release** defines the specific deployment configuration: which container image to run, what version tag to use, environment variables, network mode, restart policies, and other runtime settings. Each new application version corresponds to a new release.

**Deployment** occurs when you create a release. The AutoPi Cloud automatically delivers the release configuration to all associated devices. Devices apply the release at their next idle window (typically before entering sleep mode), which includes logging into the registry, pulling the image, stopping previous containers, and starting updated ones. You can also trigger immediate deployment using the `state.sls docker.release` command without waiting for the next idle window.

---

## Prerequisites

Before deploying a Docker container to your AutoPi device, ensure the following requirements are met:

1. **Docker add-on is available on your account** - docker support is a functionality only avaiable for Account Administrators, you can read more about modifying user permissions here: [Permission Groups](https://docs.autopi.io/cloud/accounts/#modifying-user-permissions). Contact the AutoPi sales team at **sales@autopi.io** to get more information.

2. **Docker is enabled in Advanced Settings** - in the AutoPi Cloud, navigate to **Advanced Settings → Docker** and confirm that Docker is enabled for each device you intend to use.

---

## Hardware Requirements

Docker support is available on the following AutoPi devices:

- **[AutoPi TMU CM4](https://shop.autopi.io/products/autopi-telematics-unit-cm4-4g-lte-edition)**
- **[AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro?pr_prod_strat=e5_desc&pr_rec_id=b9d9a5d6d&pr_rec_pid=14759832158557&pr_ref_pid=8609941160285&pr_seq=uniform)**
- **[AutoPi CAN-FD Pro + IP67 Casing](https://shop.autopi.io/products/autopi-can-fd-pro)**

---

## Deploying a Docker Container

### Step 1: Build and Push Your Image

Begin by creating a `Dockerfile` for your application, you can read more here: [Build Dockerfile](https://docs.docker.com/build/concepts/dockerfile/#:~:text=A%20Dockerfile%20is%20a%20text,Description). Since the AutoPi TMU CM4 and CAN-FD Pro devices run on **ARM64** architecture, you must use an ARM-compatible base image to ensure your container runs properly on the device.

#### Example Dockerfile

```dockerfile
# Dockerfile
# Target: ARM64 (AutoPi TMU CM4 / CAN-FD Pro)
FROM --platform=linux/arm64 python:3.11-slim-bookworm

# Install any system dependencies your application needs
RUN apt-get update && apt-get install -y --no-install-recommends \
    curl \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application source
WORKDIR /app
COPY app.py .

# Start the application
CMD ["python", "app.py"]
```

After creating your Dockerfile, build the image and push it to your container registry. If you are building on an x86/x64 machine, use Docker's `buildx` tool to cross-compile for ARM64 architecture:

```bash
# Cross-compile for ARM64 from any host (recommended)
docker buildx create --use
docker buildx build --platform linux/arm64 -t my-registry/my-image:1.0.0 --push .

# Or, if building directly on an ARM machine:
docker build -t my-registry/my-image:1.0.0 .
docker login my-registry
docker push my-registry/my-image:1.0.0
```

### Step 2: Create a Registry in AutoPi Cloud

Create a registry entry in AutoPi Cloud to enable devices to securely authenticate with your container registry and pull images during deployment. When you configure a registry entry, devices automatically authenticate using the stored credentials each time they start up or pull a new image.

**Using the AutoPi Cloud UI:**

Navigate to **Docker** in the AutoPi Cloud and create a new registry. Configure these settings:
- **Registry URL** — the address of your container registry (e.g., `docker.io`, `gcr.io`, or your private registry URL)
- **Authentication credentials** — username and password or access token for private registries
- **Registry type** — specify which registry service you are using

![Create Docker Registry](/img/guides/docker/create_registry.png)

**Using the API:**

```
POST /docker/registries/
```

:::note
If your image is hosted in a private registry, the registry must be referenced when creating the release container definition.
:::

---

### Step 3: Create a Project

Create a project to organize all releases of your application. A project acts as a logical container for managing application versions and their associated devices. You must create at least one project before you can create any releases.

**Using the AutoPi Cloud UI:**

Navigate to **Docker** in the AutoPi Cloud and create a new project. Configure:
- **Name** — a descriptive name for your application
- **Description** — optional details about the project's purpose
- **Associated registry** — select the registry where your container images are stored
- **Devices** — select which AutoPi devices should be part of this project

![Create Docker Project](/img/guides/docker/create_project.png)

:::note
Devices must have Docker enabled in **Advanced Settings** before they can be added to a project.
:::

**Using the API:**

```
POST /docker/projects/
```

---

### Step 4: Create a Release

Create a release to define a specific version of your container deployment. A release specifies which container image to run, its version, runtime configuration (environment variables, network mode, restart policy), and which devices should receive this deployment.

**Using the AutoPi Cloud UI:**

From your project, navigate to the **Releases** section and click **Create**.

![Releases Page](/img/guides/docker/releases_page.png)

Configure these required fields:
- **Version** — a semantic version string (e.g. `1.0.0`) to track different releases
- **Devices** — select which devices in your project should receive this release
- **Container settings** — specify the container image name, version tag, registry reference, and runtime parameters

![Create Docker Release](/img/guides/docker/docker_create_new_release.png)

**Using the API:**

```
POST /docker/projects/{project_pk}/releases/
```

#### Example Release Payload

```json
{
  "version": "1.0.0",
  "devices": ["<device_id>"],
  "containers": [
    {
      "name": "my-service",
      "image": "my-registry/my-image",
      "tag": "latest",
      "startup_parameters": {
        "privileged": false,
        "network_mode": "host",
        "restart_policy": "always",
        "environment": [
          "ENV_VAR=value"
        ]
      },
      "purge_data": false
    }
  ],
  "remove_containers": []
}
```

**Release payload fields:**

| Field | Required | Description |
|:---:|:---:|:---:|
| `version` | Yes | A semantic version string (e.g., `1.0.0`) to identify this release. |
| `devices` | Yes | Array of device IDs that should receive this release. |
| `containers` | Yes | Array of container definitions, each specifying image name, tag, registry, and startup parameters. |
| `remove_containers` | No | Array of container names to stop and remove from devices before applying the new release. Containers are removed on successful deployment; on failure, they are restarted. |
| `version_hash` | Readonly | Auto-generated identifier for this release version, used for API references. |
| `successful_deployments` | Readonly | Read-only array showing which devices have successfully deployed this release. |

---

### Step 5: Apply the Release

After you create a release, the AutoPi Cloud automatically distributes it to all associated devices. Devices apply the release at their next idle window (typically just before entering sleep mode). During this process, the device:
1. Authenticates with the configured container registry
2. Pulls the specified container image
3. Stops and removes any previous instances of the container
4. Starts the updated container with the configured parameters

**Immediate deployment:** To apply a release without waiting for the next idle window, execute this command on the target device:

```
state.sls docker.release
```

This command triggers immediate deployment and can be executed via the AutoPi Cloud terminal or API.

---

## Container Runtime Configuration

Each container is configured through the `startup_parameters` field in your release definition. These settings control how the container behaves when it starts and while it runs. The following configuration options are supported:

| Parameter | Description |
|:---:|:---:|
| `network_mode` | Network mode for the container (`host`, `bridge`, etc.). Set to `host` if the container needs to access hardware interfaces such as the CAN bus or GPS sockets. |
| `restart_policy` | Container restart behavior: `always` (restart on any exit), `on-failure` (restart only on error), or `no` (do not restart). |
| `environment` | Array of environment variables in `KEY=VALUE` format that the container can access. |
| `privileged` | Set to `true` only if the container requires elevated host-level permissions. Use sparingly for security reasons. |
| `volumes` | Array of volume mounts from the host filesystem into the container (e.g., `/host/path:/container/path:ro`). |

---

## Example Use Cases

### 1. MQTT Data Bridge

**Use case:** Forward vehicle data to a custom MQTT broker in real-time without modifying AutoPi's return system.

**Description:** This lightweight container reads vehicle data from AutoPi and publishes it to your MQTT broker, enabling real-time data streaming to external systems.

**Configuration:**

```python
{
  "version": "1.0.0",
  "containers": [
    {
      "name": "mqtt-bridge",
      "image": "my-registry/mqtt-bridge",
      "tag": "latest",
      "startup_parameters": {
        "network_mode": "host",
        "restart_policy": "always",
        "environment": [
          "BROKER_HOST=broker.example.com",
          "BROKER_PORT=1883",
          "TOPIC_PREFIX=fleet/vehicle-1"
        ]
      }
    }
  ]
}
```

**Key configuration:** Set `network_mode: host` to allow the container to access AutoPi's local network interfaces (CAN bus, GPS socket) directly without additional network setup. Set `restart_policy: always` to ensure the bridge reconnects automatically if there are temporary network issues.

---

### 2. AI / ML Edge Inference

**Use case:** Run machine learning models directly on the device for real-time anomaly detection, predictive maintenance, or signal analysis.

**Description:** This container runs a pre-trained TensorFlow Lite or ONNX model on vehicle sensor data without sending raw data to the cloud, enabling low-latency inference at the edge.

**Configuration:**

```python
{
  "version": "2.0.0",
  "containers": [
    {
      "name": "anomaly-detector",
      "image": "my-registry/anomaly-detector",
      "tag": "v2.1",
      "startup_parameters": {
        "network_mode": "host",
        "restart_policy": "on-failure",
        "environment": [
          "MODEL_PATH=/models/anomaly_v2.tflite",
          "CONFIDENCE_THRESHOLD=0.85"
        ]
      }
    }
  ]
}
```

The container reads vehicle data from a local socket or shared volume where AutoPi writes data, performs inference using the ML model, and optionally publishes results. This approach keeps computation at the edge, reducing latency and bandwidth requirements.

---

### 3. Custom Data Processing Pipeline

**Use case:** Transform and enrich raw vehicle data before sending it to a backend system.

**Description:** This container runs a custom service (Python, Node.js, etc.) that processes raw CAN/OBD-II data—filtering, aggregating, or enriching it—before forwarding to your backend API.

**Configuration:**

```python
{
  "version": "1.2.0",
  "containers": [
    {
      "name": "data-processor",
      "image": "my-registry/data-processor",
      "tag": "1.2",
      "startup_parameters": {
        "network_mode": "host",
        "restart_policy": "always",
        "environment": [
          "UPSTREAM_API=https://api.example.com/ingest",
          "API_KEY=<your-api-key>",
          "FILTER_SIGNALS=rpm,speed,throttle"
        ]
      }
    }
  ]
}
```

---

### 4. Fleet-Wide Simultaneous Deployment

**Use case:** Deploy the same container image across multiple devices in your fleet with consistent configuration.

**Description:** Because releases are associated with a project that can encompass multiple devices, you can efficiently roll out the same container to your entire fleet at once, ensuring consistency across all devices.

**Using the AutoPi Cloud UI:**
 
1. Add all target devices to your project:

   ![Deploying to multiple devices](/img/cloud/device_management/docker/devices_deployment.png)

2. Create a release and specify all target devices. Once created, trigger immediate deployment across all devices:

   ```
   state.sls docker.release
   ```

**Using the REST API:**

Create a release via the API:

```
POST /docker/projects/{project_pk}/releases/
```

Include all target device IDs in the `devices` field of the request body. The release will be distributed and deployed to each device at their next idle window, or immediately if you execute the command above.

---

### 5. End-to-End Example: BLE Data Streaming from a Raspberry Pi Container

**Use case:** Enable wireless data streaming to mobile apps, in-vehicle displays, or head-up units without cloud connectivity.

**Description:** This complete example demonstrates building and deploying a container on an AutoPi TMU CM4 that reads vehicle data from AutoPi and broadcasts it over **Bluetooth Low Energy (BLE)**. This is ideal for in-vehicle dashboards, head-up displays, or mobile app integrations that need real-time wireless access to vehicle data.

#### Data Flow

  Vehicle (CAN/OBD-II)
  →
  AutoPi Core (writes data to local socket/file)
  →
  Docker Container (reads data, advertises over BLE)
  →
  BLE Clients (mobile, app, HUD, display device)

#### Step 1: Write the Dockerfile

The AutoPi TMU CM4 runs on ARM64 architecture. Use an ARM-compatible base image. The example below uses `python:3.11-slim-bookworm` with `bluepy` for BLE communication and a lightweight loop that reads a shared data file written by the AutoPi core.

```dockerfile
# Dockerfile
# Target: ARM64 (Raspberry Pi CM4 / AutoPi TMU CM4)
FROM --platform=linux/arm64 python:3.11-slim-bookworm

# Install system dependencies for BLE (BlueZ) and build tools
RUN apt-get update && apt-get install -y --no-install-recommends \
    bluez \
    bluetooth \
    libglib2.0-dev \
    gcc \
    && rm -rf /var/lib/apt/lists/*

# Install Python dependencies
RUN pip install --no-cache-dir bluepy

# Copy application code
WORKDIR /app
COPY ble_streamer.py .

# Run the BLE streamer on container start
CMD ["python", "ble_streamer.py"]
```

#### Step 2: Write the BLE Streamer Application

Create `ble_streamer.py` in the same directory as your Dockerfile. This script reads vehicle data that AutoPi writes to a shared volume and broadcasts it over BLE as a GATT service, making it accessible to BLE clients.

```python
# ble_streamer.py
import json
import time
import subprocess
import os

# Path to the shared data file written by the AutoPi core
DATA_FILE = "/data/vehicle_state.json"

# BLE advertisement interval in seconds
POLL_INTERVAL = 1.0

def read_vehicle_data():
    """Read the latest vehicle state from the shared data file."""
    if not os.path.exists(DATA_FILE):
        return None
    with open(DATA_FILE, "r") as f:
        return json.load(f)

def advertise_over_ble(data: dict):
    """
    Broadcast a compact JSON payload over BLE using bluetoothctl.
    In production, replace this with a full GATT server implementation
    using a library such as bluezdbus or bleak (server mode).
    """
    payload = json.dumps({
        "rpm": data.get("rpm", 0),
        "speed": data.get("speed", 0),
        "throttle": data.get("throttle", 0),
    })
    # Output to stdout — visible in container logs via AutoPi Cloud's Device → Logs page
    print(f"[BLE] Broadcasting: {payload}", flush=True)

    # Example: trigger a BLE advertisement using hciconfig / hcitool
    # Replace with your GATT server logic as needed
    subprocess.run(
        ["hcitool", "-i", "hci0", "cmd", "0x08", "0x0008", payload.encode().hex()],
        capture_output=True
    )

def main():
    print("BLE vehicle data streamer starting...", flush=True)
    while True:
        data = read_vehicle_data()
        if data:
            advertise_over_ble(data)
        else:
            print("[BLE] Waiting for vehicle data...", flush=True)
        time.sleep(POLL_INTERVAL)

if __name__ == "__main__":
    main()
```

:::note
This example uses `hcitool` for illustration. For a production implementation, use a full GATT server library such as [`bluezdbus`](https://github.com/bluez/bluesky) or [`bleak`](https://github.com/hbldh/bleak) to expose a proper BLE service with named characteristics that a mobile app can subscribe to.
:::

#### Step 3: Build and Push the Image

Build your container image and push it to your registry. Use Docker's `buildx` feature to cross-compile for ARM64 from any host machine (including x86 systems):

```bash
# Enable multi-platform builds (one-time setup)
docker buildx create --use

# Build for ARM64 and push directly to your registry
docker buildx build \
  --platform linux/arm64 \
  -t my-registry/ble-streamer:1.0.0 \
  --push \
  .
```

If building directly on the CM4 device itself or another ARM machine, a standard build works:

```bash
docker build -t my-registry/ble-streamer:1.0.0 .
docker push my-registry/ble-streamer:1.0.0
```

#### Step 4: Create the Registry in AutoPi Cloud

In the AutoPi Cloud, navigate to **Docker → Registries** and create a new registry entry. Point it to your container registry and provide authentication credentials (if required). This enables devices to authenticate and pull the image during deployment.

![Create Docker Registry](/img/guides/docker/create_registry.png)

#### Step 5: Create a Project and Release

In the AutoPi Cloud, navigate to **Docker → Projects**, create a new project, and then add a release with this configuration:

```json
{
  "version": "1.0.0",
  "devices": ["<your-device-id>"],
  "containers": [
    {
      "name": "ble-streamer",
      "image": "my-registry/ble-streamer",
      "tag": "1.0.0",
      "startup_parameters": {
        "privileged": true,
        "network_mode": "host",
        "restart_policy": "always",
        "environment": [
          "DATA_FILE=/data/vehicle_state.json",
          "POLL_INTERVAL=1.0"
        ],
        "volumes": [
          "/var/autopi/data:/data:ro"
        ]
      },
      "purge_data": false
    }
  ]
}
```

**Key configuration notes:**

| Parameter | Value | Reason |
|:---:|:---:|:---:|
| `privileged` | `true` | Required to access BLE hardware via BlueZ on the host system. |
| `network_mode` | `host` | Allows the container to access the host's Bluetooth adapter (`hci0`) and other network interfaces directly. |
| `restart_policy` | `always` | Automatically restarts the BLE streamer if the container exits unexpectedly, maintaining continuous availability. |
| `volumes` | `/var/autopi/data:/data:ro` | Mounts the directory where AutoPi writes vehicle data, accessible as read-only inside the container. |

:::note
**Important:** The exact path AutoPi uses to write shared data depends on your device configuration. Adjust the `volumes` mount path to match your actual data location. Alternatively, create a custom returner or service to write vehicle data to a known location on the host filesystem.
:::

#### Step 6: Apply the Release

Once you save the release, AutoPi Cloud automatically delivers it to the target device. The device applies it at the next idle window. To deploy immediately without waiting, execute this command via the AutoPi Cloud terminal or API:

```
state.sls docker.release
```

After successful deployment, the container will:
1. Start and initialize.
2. Mount the shared vehicle data volume.
3. Initialize the BLE interface.
4. Begin broadcasting vehicle data to BLE clients.

**Verification:** Check **device's logs** to confirm the container started successfully and is broadcasting data. Check out this guide: [AutoPi Logs](https://docs.autopi.io/developer_guides/autopi-logs/). 

---

## Troubleshooting

### Container fails to start

**Problem:** The container exits immediately after deployment.

**Solutions:**
- Check container logs in **device's logs** to identify the error message. Check out this guide to retrieve logs: [AutoPi Logs](https://docs.autopi.io/developer_guides/autopi-logs/).
- Verify the container image and tag exist in your registry and are spelled correctly.
- Confirm the image is built for ARM64 architecture (not x86/x64).
- Check that `network_mode` configuration does not conflict with other running services.

### Image cannot be pulled

**Problem:** Device cannot download the container image from the registry.

**Solutions:**
- Verify the device has network connectivity and can reach the registry URL.
- Confirm the image is publicly accessible, or that authentication credentials are correctly configured in the registry entry.
- Double-check the registry URL, image name, and tag for typos.
- For private registries, ensure the credentials stored in AutoPi Cloud have pull permissions.

### Container keeps restarting

**Problem:** The container starts but immediately exits, causing repeated restart attempts.

**Solutions:**
- Review application logs inside the container to identify the root cause.
- Verify all required environment variables are set correctly in the release configuration.
- Temporarily change `restart_policy` to `on-failure` to prevent infinite restart loops while debugging.
- Check that required dependencies and configuration files are present in the container image.

### Permission issues

**Problem:** Container cannot access required resources or files.

**Solutions:**
- Only set `privileged: true` if the application explicitly requires elevated host-level permissions. This should be a last resort.
- Verify that required volume mount paths exist on the host device filesystem.
- Ensure the container's user (usually root or the image's default user) has permission to access mounted volumes.
- Check the application's documentation for specific file or directory permission requirements.

### Networking problems

**Problem:** Container cannot communicate with hardware interfaces or external services.

**Solutions:**
- Set `network_mode: host` if the container needs direct access to hardware interfaces (CAN bus, GPS sockets, serial ports).
- Check for port number conflicts with other services already running on the device.
- Verify the container's network configuration matches your application requirements.
- Test external connectivity from inside the container using basic tools like `ping` or `curl`.

---

## Next Steps

Now that you understand Docker fundamentals on AutoPi, explore these additional resources:

- **[Setting Up Docker on Your Device](https://docs.autopi.io/developer_guides/setting-up-docker/)** — a complete step-by-step walkthrough with UI screenshots for registry, project, and release creation.
- **[AutoPi Cloud Documentation](https://docs.autopi.io/)** — learn more about device management, logging, and monitoring.
- **[Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)** — industry-standard guidance for building production-ready containers.

For questions or assistance, contact the AutoPi support team at [support@autopi.io](mailto:support@autopi.io).

---

## Dashboards

---
Shared Dashboards allow you to create and manage dashboards that are automatically applied to multiple vehicles based on defined rules. This makes it easy to standardize data visualization across fleets without configuring dashboards individually for each vehicle.

In addition to Shared Dashboards, AutoPi also provides:
* [Vehicle Dashboard](https://docs.autopi.io/cloud/fleet_management/vehicles/vehicle-details/#dashboard).
* [Device Dashboard](https://docs.autopi.io/cloud/device_management/dashboard/).

---

## Dashboards Overview

Dashboards provide a visual representation of real-time and historical data from your vehicles and devices. Data can be displayed using a variety of widget types, including:
* Line chart  
* Area chart  
* Map  
* Heatmap  
* Gauge  
* Bar chart  
* Pie chart  
* State timeline  
* Linear gauge  
* Numeric  

AutoPi supports **three types of dashboards**:

1. **Autogenerated** – automatically created based on the data received from a device.  
2. **Mine** – dashboards manually created by a user.  
3. **Shared** – dashboards created by an administrator and shared automatically with vehicles that match specific criteria.  

![Dashboard types](/img/cloud/fleet_management/configurations/dashboards/dashboard_types.png)

This guide focuses on **Shared Dashboards**.

---

## Creating a Shared Dashboard

### Step 1: Create a New Shared Dashboard

To create a shared dashboard:
1. Navigate to **Configuration → Dashboards**.
2. Click **Create**.

![Create a Shared Dashboard](/img/cloud/fleet_management/configurations/dashboards/create_shared_dashboard.png)

Fill in the following information:

#### Basic Information
- **Name** – choose a clear and descriptive name.
- **Description** (optional) – add details to help differentiate dashboards.
- **Enabled** – Toggle whether the dashboard is active or inactive.

#### Filtering
Filtering determines which vehicles the dashboard is automatically applied to. These filters are hierarchical:
- If you select only **Vehicle Type**, the dashboard is applied to all vehicles of that type (for example, all EVs).
- If you select **Vehicle Type + Make**, it applies only to vehicles of that make and type. 
- If you select **Vehicle Type + Make + Model**, it applies only to that specific model. 

Available filters:
- **Vehicle type** – Battery electric, hybrid electric, plug-in hybrid, or internal combustion engine.
- **Make** – Vehicle manufacturer.
- **Model** – Specific vehicle model.

Once saved, the new shared dashboard will appear in the dashboards table.

:::warning
Shared Dashboards are available only to users with the `account_administrator` permission. If your user does not have this permission, the functionality will not be visible. You can read more about permissions in this guide: [Accounts permissions](https://docs.autopi.io/cloud/accounts/).
:::

---

### Step 2: Add Widgets to the Shared Dashboard

After creating the shared dashboard and defining which vehicles it applies to, you can design its layout by adding widgets.

To make widget creation easier:
* Select the dashboard from the table.
* In the top-left corner, choose a vehicle to use as a data source.
* Select a timeframe.  

Using real vehicle data helps ensure charts and widgets are configured correctly.

:::note
The **Autogenerate** option creates widgets automatically based on data available from the selected vehicle. This is useful when building a dashboard from scratch, as it provides a solid starting point that can later be edited or used as is.
:::

To add a widget manually:
1. Click **Add widget**.
    ![Dashboard types](/img/cloud/fleet_management/configurations/dashboards/add_widget.png)
2. Select the widget type.
    ![Widget types](/img/cloud/fleet_management/configurations/dashboards/widget_type.png)
3. Configure the following fields:
    ![Widget configuration](/img/cloud/fleet_management/configurations/dashboards/configure_widget.png)
   - **Title** – name of the widget.
   - **Visualization** – chart or display type (line chart, map, gauge, etc.).
   - **Field** – logger or signal to display.
   - **Aggregation** – average, minimum, maximum, sum, or raw data.
   - **Unit** – unit displayed on the widget.
   - **Auto scale** – automatically scale values.
   - **Hide gaps** – hide/show gaps where data was not received. 

Save the widget and then save the dashboard changes. The widget is now part of the shared dashboard.

---

## How to Edit Shared Dashboard?
There are several built-in actions that help you manage your **Shared Dashboards** efficiently. These actions allow you to maintain, reuse, or clean up dashboards as your needs evolve.

The available actions are:
- **Edit** – modify the dashboard layout and widgets. 
- **Duplicate** – create a copy of an existing dashboard to reuse or extend it.  
- **Delete** – permanently remove a shared dashboard.  

![Editing a shared dashboard](/img/cloud/fleet_management/configurations/dashboards/dashboard_actions.png)

You can access all of these actions directly from the **Dashboards** table. In the **Actions** column, click the **three-dot menu** next to the desired dashboard to see the available options.

---

## Fault Codes

---

The **Fault Codes** functionality allows you to define custom fault codes for your vehicles and decide how the system should react when those faults occur. You can specify what constitutes a fault, assign a severity level, and choose how you want to be notified, either through alerts in the AutoPi Cloud or via email notifications. This makes Fault Codes a powerful tool for **real-time monitoring of critical vehicle issues**, helping you react quickly and manage your fleet more efficiently.

:::note
The Fault Codes functionality is available only to users with **Account Administrator** permission.
:::

## Fault Codes Table

![Fault Codes](/img/cloud/fleet_management/configurations/fault_codes/fault_codes_view.png)

The Fault Codes table provides an overview of all configured fault codes. For each fault code, the following information is displayed:

* **Code** – the fault code identifier.  
* **Proprietary** – indicates whether the fault code is proprietary.  
* **Type** – the fault code type:
  * OBD2
  * J1939
  * Custom.
* **Description** – a short explanation of the fault code.  
* **Email notify** – indicates whether email notifications are enabled.  
* **Alerts notify** – indicates whether alerts will be created in AutoPi Cloud.  
* **Severity** – The severity level of the alert:
  * Low
  * Medium
  * High
  * Critical.
* **Actions** – available actions, such as deleting the fault code. 

---

## Types of Fault Codes

AutoPi supports three types of fault codes:

* **OBD2**
* **J1939**
* **Custom**

Each type has slightly different configuration requirements, described below.

### Create an OBD2 Fault Code

![Create OBD2 Fault Code](/img/cloud/fleet_management/configurations/fault_codes/create_new_fault.png)

To create an **OBD2 fault code**, fill in the following fields:

* **Type** – automatically set to **OBD2**.
* **Code** – the OBD2 fault code.
* **Description** (optional) – additional details about the fault.
* **Vehicle Alerts** (optional):
  * Enable to create an alert in AutoPi Cloud when the fault occurs.
  * Alert severity – choose the severity level.
* **Email Notifications** (optional):
  * Enable to receive an email when the fault occurs.
  * Email address – specify the recipient email address.
* **Notification channel** (optional) – select a notification channel for fault-related updates. Channels are configured once in [Notification Channels](https://docs.autopi.io/cloud/fleet_management/configurations/notification-channels/) and then reused here.

---

### Create a J1939 Fault Code

![Create J1939 Fault Code](/img/cloud/fleet_management/configurations/fault_codes/create_new_j1939_fault.png)

To create a **J1939 fault code**, provide the following information:

* **Type** – automatically set to **J1939**.
* **SPN** (Suspect Parameter Number) - choose the SPN from the standard options. 
* **FMI** (Failure Mode Identifier) - choose the FMI from the standard options. 
* **Description** (optional) – additional context for the fault.
* **Vehicle Alerts** (optional):
  * Enable to create an alert in AutoPi Cloud.
  * Alert severity – select the severity level.
* **Email Notifications** (optional):
  * Enable to receive email notifications.
  * Email address – specify the recipient email address.
* **Notification channel** (optional) – select a notification channel for fault-related updates. Channels are configured once in [Notification Channels](https://docs.autopi.io/cloud/fleet_management/configurations/notification-channels/) and then reused here.

---

### Create a Custom Fault Code

![Create Custom Fault Code](/img/cloud/fleet_management/configurations/fault_codes/create_new_custom_fault.png)

To create a **Custom fault code**, fill in the following fields:

* **Type** – automatically set to **Custom**. 
* **Code** – the custom fault code identifier.
* **Description** (optional) – description of the fault.
* **Vehicle Alerts** (optional):
  * Enable to create an alert in AutoPi Cloud.
  * Alert severity – select the severity level.
* **Email Notifications** (optional):
  * Enable to receive email notifications.
  * Email address – specify the recipient email address.
* **Notification channel** (optional) – select a notification channel for fault-related updates. Channels are configured once in [Notification Channels](https://docs.autopi.io/cloud/fleet_management/configurations/notification-channels/) and then reused here.

---

## Summary

Once fault codes are configured, AutoPi continuously monitors your vehicles and notifies you whenever a defined fault occurs. Combined with alerts and email notifications, this functionality ensures you stay informed about critical issues in real time allowing you to make faster, better decisions when managing your fleet.

---

## Notification Channels

---

Under configurations you can find Notification Channels. Here you can create a 
notification channel, that you can later apply in different parts of the 
platform, most commonly in Geofences - for example to be notified when your vehicle is leaving and entering a specific geofence. 

You configure each notification channel only once here, and then reuse it across Fleet Management features such as **Geofences**, **Locations**, and **Fault Code** creation.

    

## Default notification channels
When your account has been created, some default Notification Channels have been 
set for you:  
- Low Alert - create low alert under Alerts
- Medium Alert - create medium alert under Alerts
- High Alert - create high alert under Alerts
- Critical Alert - create critical alert under Alerts
- Email - send email to Customer's email; learn more about customers and users here: [Accounts](https://docs.autopi.io/cloud/accounts/#create-customer)

## Creating a Notification Channel

You can edit the default channels or create new ones to match your workflow.

1. Click **Create** in the Notification Channels table.
2. Fill in the channel details:
    - **Name** (required): a clear name for the channel.
    - **Type** (required): choose how notifications are delivered (for example, Alert, Email, Discord webhook, or SMS).
    - **Description** (optional): additional context about when this channel should be used.
3. Click **Create** to save the new channel.

    

After a channel is created, it becomes available as a reusable notification option in:
- [Fleet Geofences](https://docs.autopi.io/cloud/fleet_management/vehicles/geofence/)
- [Locations](https://docs.autopi.io/cloud/fleet_management/locations/)
- [Fault Codes](https://docs.autopi.io/cloud/fleet_management/configurations/fault-codes/)

## Types of notification channels
We currently support several types of notification channels. You can set up one or multiple channels at the same time. This way, you can stay informed in the way that suits you best! Here’s a quick overview:
    * **Alert**: creates an alert in the AutoPi Cloud. You can choose from different severity levels: low, medium, high, or critical.
    * **Email**: sends an email to the specified address. You can also add CC and BCC to include multiple recipients.
    * **Discord**: use a webhook ID and token to receive notifications directly in your Discord server.
    * **SMS**: add a phone number to receive notifications via text message.

---

## Vehicle States

---

Vehicle States and Fleet States give you a structured way to reflect the real-world status of every vehicle in your fleet. By defining and assigning states, your team can immediately understand the situation of any vehicle without needing to dig into logs or historical data.

Once configured, states are visible in two key places:

- **Vehicle Overview** — the Fleet Information widget on the Vehicle Overview tab displays the current Vehicle and Fleet State assigned to a vehicle, giving you a quick snapshot of its status.
- **Vehicle List** — the Vehicle List supports filtering by Vehicle State and Fleet State, making it easy to group and view all vehicles sharing the same status at once.

## Vehicle States

Vehicle States allow you to track and communicate the current status of each vehicle in your fleet. A set of default states is provided out of the box, but you can create fully custom states to match your operational needs.

States support a parent-child hierarchy. For example, you can create a top-level state such as **Maintenance**, and then define more specific child states beneath it, such as **Awaiting Parts** or **In Service** — to provide greater detail. 

![Vehicle States table](/img/cloud/fleet_management/configurations/vehicle_states/vehicle_states_table.png)

## Fleet States

Fleet States offer an additional layer of classification at the fleet level. You can define what each state represents and how it should be used within your organization. A set of default Fleet States is provided, but these can be customized or removed as needed.

![Fleet States table](/img/cloud/fleet_management/configurations/vehicle_states/fleet_states_table.png)

## Creating a Vehicle/Fleet State

To create a new state:

1. Click **Create State**.
2. Fill out the following fields:
   - **Name** — enter a descriptive name for the state (e.g., *Maintenance*, *In Transit*).
   - **Color** — select a color to visually distinguish the state in the Vehicle List.
   - **Parent** — optionally assign a parent state to create a hierarchy of states.
3. Save your changes.

![Create State](/img/cloud/fleet_management/configurations/vehicle_states/create_new_state.png)

---

## Alerts(Fleet_management)

---

The **Fleet Alerts** page is your centralized place for monitoring all active alerts across your entire fleet. No need to check each vehicle one by one - this view shows you everything that requires attention in one place.This guide should help you quickly assess and manage any issues across your fleet using the Fleet Alerts feauture available on [AutoPi cloud](https://my.autopi.io/#/login). 

![Fleet alerts](/img/cloud/fleet_management/alerts/alerts_page.png)

### Getting started with Alerts
At the top of the Fleet Alerts page, you’ll see a summary of **open alerts only**. These represent current issues that need fixing or investigation. Closed alerts are still stored, but the focus here is on what’s actionable right now.

![Open alerts](/img/cloud/fleet_management/alerts/open_alerts.png)

### How to Interact with Alerts: 

Feauture 1: **View More Info**  
To see additional details about an individual alert:
- Click the **arrow icon** on the left of the alert row to expand it.
- This will reveal more technical and contextual information.

![Alert information](/img/cloud/fleet_management/alerts/description_alert.png)

Feature 2: **Go to Vehicle**  
To jump directly to the affected vehicle:
* Click the **chain link icon** next to the vehicle name.
* You’ll be redirected to the **Vehicle Overview** page for that vehicle.

### Alert Severity Levels
Alerts are grouped by severity so you can prioritize your actions:
1. **Critical** – Needs immediate attention  
2. **High** – Important but not urgent  
3. **Medium** – Worth monitoring  
4. **Low** – Informational or minor issues  

### Managing Alerts
Each alert has a **three-dot Actions menu** on the right-hand side. This gives you two main options:

**1. Resolve an alert**
- Marks the alert as resolved.
- Logs **who resolved it** (your username by default, or you can assign it to another team member).
- Allows you to **add a note**, such as:
  - Date of resolution
  - Fix applied
  - Any relevant comments for tracking

> Useful for maintaining accountability and documentation.

![User resolved alert](/img/cloud/fleet_management/alerts/user_resolved.png)

**2. Dismiss an alert**
- Use this if the alert doesn’t need action (e.g., false positive or known condition).
- The alert is closed but recorded in the alert history as “dismissed.”
- You’ll still see **when it occurred and when it was dismissed**, but it won’t clutter the list of active alerts.

### Filters and Columns

You can **filter** alerts based on. 

	
		 State:  
        * **Open** - an alert needs your attention
        * **Dismissed** - alert was marked as not important
        * **Resolved** - usually happens automatically from system
        * **Resolved by user** - user marked the alert as resolved 

         Severity: 
        * **Critical**
        * **High**
        * **Medium**
        * **Low**
	
	

Customize the table view by selecting which **columns** to display.

	
		 Columns:  
        * **Vehicle** - name of the vehicle
        * **Severity** (critical, high, medium, low)
        * **First occurrence** - first time this problem occured on a vehicle
        * **Last occurrence** - last time this problem occured on a vehicle
        * **Count** - number of times this alert has occurred

---

## Diagnostics

---

The **Fleet Diagnostics** page provides a centralized overview of all diagnostic error codes currently reported across your entire fleet. It allows you to quickly identify issues, understand their impact, and monitor how frequently they occur across multiple vehicles.

If you want to view diagnostic information for a **specific vehicle only**, you can do so under **Vehicle → Diagnostics**. You can read more about this functionality here: [Vehicle Diagnostics](https://docs.autopi.io/cloud/fleet_management/vehicles/vehicle-details/#diagnostics).

---

## What You Can See in Fleet Diagnostics

For each diagnostic error code, the Fleet Diagnostics page displays:

* **Error code and description** – a clear explanation of the reported issue. 
* **Vehicle** – the vehicle on which the error occurred. 
  * More detailed information is available on the individual vehicle’s Diagnostics page.  
* **First occurrence** – timestamp of when the error was first reported.  
* **Last occurrence** – timestamp of the most recent occurrence.  
* **Occurrence count** – how many times the error has been reported.  
* **State of the code**:
  * **Active** – the issue is currently present.  
  * **Cleared** – the issue is no longer active.  
  
![Fleet Diagnostics](/img/cloud/fleet_management/diagnostics/diagnostics_table.png)

This information helps you understand not only *what* the issue is, but also *when* it started and *how often* it occurs.

---

## Real-Time Monitoring and Automation

:::note
If you have special vehicles or need to define your own diagnostic logic, you can create **custom Fault Codes** using the Fault Codes functionality.
:::

When Diagnostics are combined with the **Fault Codes** functionality, Fleet Diagnostics becomes a powerful real-time monitoring tool:

* Receive immediate notifications about critical issues via:
  * Cloud alerts - read more here: How to set up cloud alerts.
  * Email notifications - read more here: How to set up email notifications.
* React faster to vehicle problems and reduce downtime.   

![Fault Codes](/img/cloud/fleet_management/diagnostics/fault_codes_table.png)

This enables a more proactive approach to fleet management and issue resolution. To learn more, see our guide: Fault Codes.

---

## Introduction(Cloud)

Welcome to our documentation page for the Fleet Management part of our [AutoPi](https://www.autopi.io) 
platform meant to help you streamline your fleet operations from one place. Our 
goal is to provide you with features that help you track each vehicle or entire 
groups and get all insights you need, simply and effectively.  

Fleet Management is dedicated to fleet owners to efficiently manage their fleets 
of vehicles, no matter the size of the company. Within this part of the platform,
you will find features that are designed to make it easier to get an overview of 
the state of the fleet as well as manage all vehicles in the fleet. 

Its various features are designed to make it easier to:
- **Get an overview of the state of the fleet**
- **Manage all vehicles in the fleet**
- **Track real time vehicle data** 

    

## Get Your Device Today and Get Started!

[![](/img/hardware/autopi_mini/AutoPi_Mini_5_Top_right.png) **AutoPi Mini** Build for fleet volume scaling and ease of install. CAN bus ready with support for legacy protocols. Support wide range of OEM Parameters. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-mini)

[![](/img/hardware/autopi_tmu_cm4/TMU_Floating_Topside_V1_scaled.png) **AutoPi TMU CM4** Based on Raspberry Pi Compute Module 4. Best for custom solutions requiring large computation power and expansion options. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-telematics-unit-cm4-4g-lte-edition)

[![](/img/hardware/autopi_canfd_pro/canfd_pro_trans.png) **AutoPi CAN-FD Pro** Based on Raspberry Pi Compute Module 4. Our most powerful device to date, designed for full speed automotive datalogging of dual CAN-FD channels. See price.](https://shop.autopi.io/products/autopi-can-fd-pro)

[![](/img/shared/autopi_devices_trans.png) **Comparison of all AutoPi devices** Compare our devices and find the best fit for your requirements.](https://www.autopi.io/hardware/compare/)

---

## Locations

---

The **Locations** feature helps you organize your fleet by creating and managing operational areas for your company—such as regional offices, headquarters, distribution centers, or service hubs. You can assign vehicles to specific locations and control user access based on their assigned areas. Users will only see vehicles and manage operations tied to the locations they have access to.

To begin, navigate to the **Locations** tab, where you'll see a world map of your existing locations and a list view for easy navigation. 

![Locations overview](/img/cloud/fleet_management/locations/new_locations_table.png)

---

## Creating a Location

1. Click **Create** and enter the location details:
   - **Location name** (required): An internal identifier for the location
   - **Contact email** (required): The main contact for this location
   - **Phone number, address, and notes** (optional): Additional information to describe the location

2. Configure geofence settings:
   - Enter an address to zoom in on the map
   - Choose a color for the geofence if desired
   - Select the default enter and exit notifications
   - Notification channels are configured once under [Notification Channels](https://docs.autopi.io/cloud/fleet_management/configurations/notification-channels/) and then reused here

3. Draw the geofence:
   - Use the tools on the left side to create and edit the geofence
   - Click on the map to draw a circle or polygon that outlines your desired area
   - Additional tools allow you to edit, drag, remove, or rotate layers

4. Click **Create** to save the location

![Create Location](/img/cloud/fleet_management/locations/create_new_location.png)

---

## Managing Locations

Once created, your location appears in the list. To edit or delete a location, click **Actions** (the three dots) next to the location name. Use the **Search for Location** filter to quickly find specific locations when you have multiple entries. 

### Assigning Vehicles to a Location

* Click on a location from the list to open the **Edit vehicles in location** dialog.
* Search for and select vehicles to assign to this location.
* Enable the vehicles you want to assign to this location. You can enable multiple vehicles at once.
* Click **Confirm**. A confirmation notification will confirm the changes have been saved.

![Location and vehicles](/img/cloud/fleet_management/locations/new_add_vehicles.png)

:::tip
The **Vehicles** column on the Locations list shows the number of vehicles assigned to each location. Click this number to view the vehicles assigned to that location in the Vehicle section.
:::

### Assigning Users to a Location

You can assign users to specific locations to control their access to vehicles and operations in those areas. For detailed instructions on assigning locations to users, see [Assigning Locations to Users](https://docs.autopi.io/cloud/accounts/#assign-locations-to-users).

![Assign locations](/img/cloud/fleet_management/locations/location_access.png)

---

## Using Locations with Templates

Combine Locations with **Templates** to efficiently configure vehicles across your fleet with consistent location assignments.

1. Open the template you want to use for your vehicles.
2. Set the desired **Location** on the template.
3. Apply the template to your selected vehicles or groups.

![Assign Locations to Template](/img/cloud/fleet_management/locations/template_settings.png)

This allows you to maintain consistent location configurations across your entire fleet.

---

## Overview(Fleet_management)

This section provides an overview of your entire fleet, showcasing all vehicles 
associated with your account. With access to real-time data and advanced fleet 
management tools, you can efficiently manage, monitor, and optimize your fleet’s 
operations. 

    

## Fleet Tracking
![Fleet map overview](/img/cloud/fleet_management/overview/Fleet_overview_world_map.png)

The first thing you’ll notice is a world map displaying all your vehicles as icons,
each positioned based on their latest known location and their last online status.
If you set-up geofences and locations, you’ll see them on the map as well. You can
edit the map view from the top right corner and choose what do want to see on the 
map. You can zoom in and out of the map, and each vehicle is marked with a colored
circle that indicates its current state:
- Green: Driving
- Orange: Idling
- Red: Engine off 
- Grey: Offline 

    

When you hover over a vehicle icon, detailed information about the vehicle will 
be shown. This includes the vehicle’s name, model, VIN, license plate, speed over
ground (while driving), distance traveled since the trip began, and the last 
communication timestamp (showing when it was last online). 

If you're zoomed out, you may see an icon showing two cars, indicating that 
multiple vehicles are close together. Hovering over this cluster icon will 
provide details on the number of vehicles in the group, along with their 
respective states, color-coded for quick identification. 

Clicking on a vehicle icon will zoom the map into that vehicle’s precise location. 

    
    

In the map’s right corner, you can choose to check mark options you want to see 
on the map. If you only want to view vehicles, or only geofences or location or 
everything, you have the option to choose your map view.  

In the bottom right corner of the map, you can customize your view by selecting 
which elements to display. You can opt to view only vehicles, geofences, 
locations, tailoring the map to your preferences. 

## Fleet Overview

 

Here you can find widgets that provide statistics and insights into your fleet. 
In “Fleet Total” section you will see the total number of all your vehicles. 
Clicking “Show” will take you to the Vehicle section, where you can get more 
detailed information about each vehicle.

Next to it, you will find widgets for **Driving Now**, **Driven Today** and two 
widgets providing insight on vehicles **Driven in the last 30 days** and 
**Not Driven in the last 30 days**. These insights can help fleet managers 
understand vehicle usage and identify underutilized vehicles. Clicking Show 
within a widget will take you to a vehicle table, offering a detailed view of 
the relevant vehicles. For example, if you want to see which vehicles were not 
driven in the in the last 30 days, simply click on the widget, and you will be 
redirected to the filtered vehicle table displaying those specific vehicles. 

There are also widgets for **Off Location** and **On Location**. Each vehicle can
be assigned to a predefined [location](/cloud/fleet_management/locations.md), 
allowing you to track how many vehicles are outside or inside their assigned 
locations. This information will be useful to get a better overview of your 
vehicle's locations. Clicking show within a widget will take you to a 
filtered vehicle view for more detailed analysis. 

In the **Time and Distance** section, you can view the average time and distance
driven by both individual vehicles and the entire fleet for today and for the 
current month.  

The Location widget will display your top five locations – the ones with the most
vehicles associated to the location. It shows how many vehicles are on and off 
the location. To view all your locations, click on **View Locations**.

---

## Geofence Summary Report

---

The **Geofence Report** provides insights into vehicle activity within predefined geographic areas. It helps fleet managers:
- Track entries and exits from geofenced zones.
- Monitor unauthorized or unexpected stops.
- Evaluate route adherence and optimize routing efficiency.

## List Tab

Use the **List** tab to review reports that have already been generated. This is the main place to open previous reports, export results, and remove reports you no longer need.

![Reports overview](/img/cloud/fleet_management/reports/geofence_reports/reports_list.png)

- Access a list of all generated Geofence Reports. The list includes:
  - Report name (editable during creation).
  - Report type (for example, Geofence Report).
  - Date range (from/to).
  - Creator name.
  - Date and time when the report was generated.
  - Actions: Download as PDF or delete the report.
- Click on a report to open its preview.

## Schedules Tab

Use the **Schedules** tab to manage recurring Geofence Summary Reports. It gives you a clear overview of active schedules and quick access to edit or delete them.

![Schedules overview](/img/cloud/fleet_management/reports/geofence_reports/reports_scheduled_table.png)

- View all scheduled Geofence Reports, including:
  - Report name.
  - Report type (for example, Geofence Report).
  - Frequency and time of day.
  - Last generated date.
  - Schedule creation date.
  - Creator name.
  - Actions: Edit or delete a scheduled report.

## Create/Schedule Tab

Use the **Create/Schedule** tab to configure one-time reports or set up recurring report generation. This tab is where you define report inputs, preview results, and save your configuration.

### Creating a Geofence Summary Report

Complete the form below to create a one-time Geofence Summary Report.

![Create geofence report](/img/cloud/fleet_management/reports/geofence_reports/create_geofence_summary_bob.png)

To create a Geofence Summary Report: 
- From the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) platform, navigate to the **Reports** menu and click 
   **Create/Schedule**.
- Select **Geofence Summary** from the available report templates.
- Complete the report form. creation:
    - **Name:** enter a name for the report.
    - **Vehicles selection:** select the vehicles or groups you want to include in the report.
      You can:
      - select individual vehicles from the **Vehicles** dropdown.
      - use the dropdowns under **Include vehicles from..** and choose a vehicle group, fleet geofences, or locations to include all vehicles from those groups.
    - **Settings:**
      - **Only include specific geofences in report (optional):** limit the report to selected geofences.
      - **Date range:** specify the start and end dates for the report.
    - **Reset:** clears all configurations you’ve made.
    - **Preview:** allows you to see how the report will look before saving.
    - **Save:** saves the report and displays it under **Reports - List**.

### Scheduling a Geofence Summary Report

After creating a Geofence Summary Report, you can schedule it to run at regular intervals (daily, weekly, or monthly). Scheduled reports are automatically generated and displayed under **Reports - Schedules**.

![Create geofence report schedule](/img/cloud/fleet_management/reports/geofence_reports/schedule_geofence_summary_bob.png)

To create a schedule:
- Navigate to the **Reports** menu and click **Create/Schedule**. 
- Select **Geofence Summary** from the available report templates and click **Schedule** next to Create to open the scheduling window.
- Complete the schedule form:
 - **Schedule Name:** Automatically generated based on the frequency, but you can customize it.
 - **Vehicles/Include vehicles from:** Select vehicles or vehicle groups for the scheduled report. Use the same selection flow as in report creation.
- **Settings:**
      - **Only include specific geofences in report (optional):** limit the report to selected geofences.
      - **Report Frequency:** select Daily, Weekly, or Monthly (one option at a time) for report frequency.
      - **Time/Day of Report Generation:** specify the day or time of the report generation.
    - **Reset:** clears all configurations you’ve made.
    - **Preview:** allows you to see how the report will look before saving.
    - **Save:** saves the report and displays it under **Reports - List**.

## How fields in the geofence report are calculated

The fields in the **Geofence Report** are generated using data from GPS locations, accelerometer readings, and other device events. Below is a breakdown of how each field is calculated:

1. **Total vehicles:** Displays the total number of vehicles selected when 
   creating the report.
2. **Total geofences:** Shows the total number of geofences selected during 
   report creation.
3. **Geofences interacted with:** Shows how many of the selected geofences were interacted with by any selected vehicle. This value is a subset of **Total geofences**.
4. **Most time spent in:** Identifies the geofence where a vehicle spent the 
   most time. This is calculated by measuring the duration between vehicle
   **enter** and **exit** events for each geofence.
    - Detailed information, such as total time spent, number of entries, and 
      exits, is available in the report fields below.
5. **Total time in geofences:** The cumulative time each selected vehicle 
   spent inside any selected geofence.
6. **Time inside:** For each geofence, this field shows the total time a vehicle 
   spent within that geofence. It is calculated as the sum of all durations 
   between **entry** and **exit** events.
7. **Enter/Exit:** This field counts how many times a vehicle entered and exited 
   a specific geofence. It is determined based on:
    - **Entry** events: Recorded as `vehicle/geofence/*/enter`.
    - **Exit** events: Recorded as `vehicle/geofence/*/exit`.
    - You can view these events under **Device -> Events** and apply the 
      relevant filters.
8. **Started:** Counts how many times a vehicle started within a specific geofence. 
   This is based on accelerometer data detecting motion events:
    - Filter: `vehicle/motion/shaking`.
9. **Stopped:** Counts how many times a vehicle stopped within a specific geofence.
   This is also based on accelerometer data:
    - Filter: `vehicle/motion/steady`.
10. **Idling time:** Displays the total time a vehicle spent idling within a 
    geofence. It is calculated as follows:
    - **Idling:** The engine RPM is between 0 and a predefined idle RPM threshold
      (configurable per vehicle).
    - Data source: `obd.rpm.value`.
11. **Driving time:** Indicates active driving time within the geofence. This is 
    determined when the engine RPM is higher than the idle threshold.
12. **Parked:** Shows the total time a vehicle was parked in a geofence. It is calculated as:
    - **Parked time** = total time spent in the geofence - (driving time + idling time).
13. **Distance:** Displays the total distance driven within a specific geofence. 
    This is calculated using GPS points logged while the vehicle was inside the geofence.

![Geofence report example](/img/cloud/fleet_management/reports/geofence_reports/geofence_report_example.png)

:::note
As new report types become available, additional features and enhancements will be added to the platform. Stay tuned for updates to make the most of your [AutoPi](https://www.autopi.io) 
[Cloud](https://www.autopi.io/software-platform/cloud-management) Reports.
:::

---

## Introduction(Fleet_management)

---

The Reports feature in the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) platform empowers fleet managers with actionable insights into fleet performance and driver behavior. Reports deliver detailed data on critical events and patterns, enabling informed decision-making to optimize operations and enhance safety. 

## Key Capabilities:

- **Understand vehicle and geofence interactions:** Quickly see how your vehicles interact with geofenced areas.
- **Monitor fleet performance:** Identify where your fleet spends the most time, analyze parking duration, and evaluate route efficiency.
- **Track driver behavior:** Monitor idling times to reduce fuel waste, measure geofence entries and exits, and review distance traveled.
- **Measure utilization:** Analyze vehicle usage patterns to optimize fleet operations and reduce operational costs.

Reports can be accessed directly through the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) or downloaded as PDF files for offline use.

## List Tab

Use the **List** tab to review reports that have already been generated. This is the main place to open previous reports, export results, and remove reports you no longer need.

![Reports overview](/img/cloud/fleet_management/reports/geofence_reports/reports_list.png)

- Access a list of all generated reports. The list includes:
  - Report name (editable during creation).
  - Report type (for example, Geofence Report or Utilization Report).
  - Date range (from/to).
  - Creator name.
  - Date and time when the report was generated.
  - Actions: Download as PDF or delete the report.
- Click on a report to open its preview.

## Schedules Tab

Use the **Schedules** tab to manage recurring reports. It gives you a clear overview of active schedules and quick access to edit or delete them.

![Schedules overview](/img/cloud/fleet_management/reports/geofence_reports/reports_scheduled_table.png)

- View all scheduled reports, including:
  - Report name.
  - Report type (for example, Geofence Report or Utilization Report).
  - Frequency and time of day.
  - Last generated date.
  - Schedule creation date.
  - Creator name.
  - Actions: Edit or delete a scheduled report.

## Available Report Types

- [Geofence Summary Report](https://docs.autopi.io/cloud/fleet_management/reports/geofence-summary-reports/) — Available
- [Utilization Report](https://docs.autopi.io/cloud/fleet_management/reports/utilization-reports/) — Available
- Location Compliance — Coming soon
- Connected Vehicles — Coming soon
- Maintenance — Coming soon
- Fleet Utilization — Coming soon

:::note
As new report types become available, additional features and enhancements will 
be added to the platform. Stay tuned for updates to make the most of your [AutoPi](https://www.autopi.io) 
[Cloud](https://www.autopi.io/software-platform/cloud-management) Reports.
:::

---

## Utilization report

---

The **Utilization Report** provides insights into how your vehicles or fleet are being used over a selected period. It helps you understand activity levels, idle time, and overall utilization to optimize operations and improve efficiency.

## Viewing the Utilization Report

By default, working hours are set to **08:00 – 16:00**.

The utilization report provides an overview of your vehicle or fleet for the selected time period, including:

* Active time 
* Total time  
* Inactive time 
* Inactive time (%)

The report also highlights:
* The total number of vehicles included.  
* A breakdown per individual vehicle. 

**Example of the Utilization Report:**
![Example of Utilization Report](/img/cloud/fleet_management/reports/geofence_reports/utilization_report/example_utilization_report.png)

This makes it easy to compare utilization across vehicles and identify opportunities to improve efficiency.

---

## List Tab

Use the **List** tab to review utilization reports that have already been generated. This is the main place to open previous reports, export results, and remove reports you no longer need.

![Reports overview](/img/cloud/fleet_management/reports/geofence_reports/reports_list.png)

- Access a list of all generated Utilization Reports. The list includes:
  - Report name (editable during creation).
  - Report type (for example, Utilization Report).
  - Date range (from/to).
  - Creator name.
  - Date and time when the report was generated.
  - Actions: Download as PDF or delete the report.
- Click on a report to open its preview.

## Schedules Tab

Use the **Schedules** tab to manage recurring Utilization Reports. It gives you a clear overview of active schedules and quick access to edit or delete them.

![Schedules overview](/img/cloud/fleet_management/reports/geofence_reports/reports_scheduled_table.png)

- View all scheduled Utilization Reports, including:
  - Report name.
  - Report type (for example, Utilization Report).
  - Frequency and time of day.
  - Last generated date.
  - Schedule creation date.
  - Creator name.
  - Actions: Edit or delete a scheduled report.

## Create/Schedule Tab

Use the **Create/Schedule** tab to configure one-time reports or set up recurring report generation. This tab is where you define report inputs, preview results, and save your configuration.

### Creating a Utilization Report

Complete the form below to create a one-time Utilization Report.

![Create Utilization report](/img/cloud/fleet_management/reports/geofence_reports/create_utilization_report.png)

To create a Utilization Report:
- From the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) platform, navigate to the **Reports** menu and click **Create/Schedule**.
- Select **Utilization** from the available report templates.
- Complete the report form:
  - **Name:** enter a name for the report.
  - **Vehicles selection:** select the vehicles or groups you want to include in the report.
    You can:
    - Select individual vehicles from the **Vehicles** dropdown.
    - Use the dropdowns under **Include vehicles from..** and choose a vehicle group, fleet geofences, or locations to include all vehicles from those groups.
  - **Settings:**
    - **Working hours (optional):** define the time range considered as working hours for utilization calculations. The default is 08:00 – 16:00. Click Set as default to apply these working hours to future reports.
    - **Date range:** specify the start and end dates for the report.
  - **Reset:** clears all configurations you've made.
  - **Preview:** allows you to see how the report will look before saving.
  - **Save:** saves the report and displays it under **Reports - List**.

### Scheduling a Utilization Report

After creating a Utilization Report, you can schedule it to run at regular intervals (daily, weekly, or monthly). Scheduled reports are automatically generated and displayed under **Reports - Schedules**.

![Schedule Utilization Report](/img/cloud/fleet_management/reports/geofence_reports/schedule_utilization_report.png)

To create a schedule:
- Navigate to the **Reports** menu and click **Create/Schedule**.
- Select **Utilization** from the available report templates and click **Schedule** next to **Create** to open the scheduling window.
- Complete the schedule form:
  - **Schedule Name:** automatically generated based on the frequency, but you can customize it.
  - **Vehicles/Groups:** select vehicles or vehicle groups for the scheduled report. Use the same selection flow as in report creation.
  - **Settings:**
    - **Report Frequency:** select Daily, Weekly, or Monthly (one option at a time).
    - **Time/Day of Report Generation:** select the specific day or time for report generation based on the chosen frequency.
    - **Email to users (optional):** enter email addresses that should receive the report. The report will be available in **Reports → List** and a copy will also be sent to the specified email addresses.
    - **Working hours (optional):** define working hours for utilization calculations. The default is **08:00 – 16:00**. Click **Set as default** to apply these working hours to future reports.
  - **Reset:** clears all configurations you've made.
  - **Preview:** allows you to see how the report will look before saving.
  - **Save:** saves the scheduled report and displays it under **Reports - Schedules**.

:::note
As new report types become available, additional features and enhancements will be added to the platform. Stay tuned for updates to make the most of your [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) Reports.
:::

---

## Geofences(Vehicles)

## Overview

Geofences are virtual boundaries on a map that define areas of interest for your fleet. They enable you to monitor vehicle movements in real time and automatically respond to location-based events. With geofences, you can:

* **Monitor deliveries** by tracking when vehicles enter or exit delivery zones
* **Enforce restricted areas** by preventing vehicles from entering out-of-country regions or unauthorized locations, and receive immediate alerts
* **Improve safety** by receiving instant notifications when a vehicle crosses a boundary
* **Automate workflows** by triggering actions (email notifications, webhook requests, or cloud alerts) based on geofence events

Geofences integrate seamlessly with other AutoPi Cloud features. Use **Templates** to apply geofences across your entire fleet at scale, **Triggers** to automate cloud-side responses when vehicles enter or exit designated areas, and **Event Reactors** to execute real-time actions directly on the device — such as playing an audible alert to immediately notify the driver.

---

## Accessing Geofences

Navigate to the **Vehicles** section in the Fleet Management tab. Select a vehicle, then click the **Geofences** tab to view the world map and any created geofences.

![Geofence tab](/img/cloud/fleet_management/vehicles/geofences/geofence_tab.png)

## Creating a Geofence

Follow these steps to create a new geofence:

![Create New Geofence](/img/cloud/fleet_management/vehicles/geofences/create_new_geofence.png)

**Step 1: Enter Geofence Details**

Click **Create** to open the configuration panel with three tabs: **Details**, **Groups**, and **Vehicles**. Start with the Details tab:
- **Name**: assign a descriptive name for internal identification and reporting.
- **Description** (optional): add context about the geofence's purpose (e.g., "Downtown delivery zone" or "Restricted border area").
- **Color**: choose a color to represent the geofence on the map for easy visual identification. 

**Step 2: Configure Notifications**

In the **Default Notification** section:
- Select one or more notification channels to receive alerts when vehicles enter or exit the geofence.
- Note: notification channels are configured once in [Notification Channels](https://docs.autopi.io/cloud/fleet_management/configurations/notification-channels/) and then reused here.
- Notifications will be sent through your chosen channels when geofence events occur.

**Step 3: Draw the Geofence Boundary**

On the map:
- Zoom to the area where you want to define the boundary.
- Use the drawing tools on the left sidebar to create either a **circle** or **polygon** boundary.
- Additional tools allow you to edit, drag, remove, or rotate layers as needed.

**Step 4: Add Vehicle Groups (Optional)**

In the **Groups+Locations** tab:

![Vehicle Groups Tab](/img/cloud/fleet_management/vehicles/geofences/create_geofence_groups.png)

- If you've created vehicle groups, add them to the geofence to automatically apply the geofence to all vehicles in those groups (see [Vehicle Groups](https://docs.autopi.io/cloud/fleet_management/vehicles/fleet-groups/)).
- If you've created location, add it to the geofence to automatically apply the geofence to all vehicles in that location (see [Locations](https://docs.autopi.io/cloud/fleet_management/locations/)).
- Use the search filter to find specific groups or locations.
- Select groups/locations by checking the boxes next to them.
- Once groups/locations are selected, use the **Actions** menu (top right) to bulk edit notifications, enable/disable groups, or reset notification channels.
- Check-marked groups/locations will have the geofence applied to all their vehicles.

**Step 5: Add Individual Vehicles**

In the **Vehicles** tab:

![Vehicles Tab](/img/cloud/fleet_management/vehicles/geofences/create_geofence_vehicles.png)

- If you prefer to add vehicles individually or haven't created vehicle groups/locations, enable specific vehicles here.
- Search by vehicle name or VIN.
- Click the preview icon next to a vehicle name to confirm you're selecting the correct vehicle.
- Enable vehicles by checking their boxes.

**Step 6: Save the Geofence**

Click **Create** to save. You can modify geofence details, add more vehicles, or adjust groups at any time after creation. A confirmation message will appear when the geofence is successfully created.

---

## How Fleet Geofences Work

Once a geofence is created and vehicles are assigned, the AutoPi Cloud continuously monitors vehicle positions and triggers events when geofence states change.

### Understanding Geofence Events

When a vehicle enters or exits a geofence, the AutoPi device logs its position. The system checks if the geofence state has changed. If **3 consecutive positions** confirm the state change, an event is triggered:

* `vehicle/geofence/GEOFENCE_NAME/enter` — vehicle entered the geofence.
* `vehicle/geofence/GEOFENCE_NAME/exit` — vehicle exited the geofence.

These events are sent to the AutoPi Cloud, where they can be used for monitoring, notifications, and automation.

### Monitoring Geofence Events

You can view and filter all geofence events in the **Device → [Events](https://docs.autopi.io/cloud/device_management/events/)** tab:
1. Navigate to your device and go to the **Events** tab.
2. Use the filter option to search for specific geofence events.
3. Filter by geofence name (e.g., `vehicle/geofence/Downtown Zone/enter`) to see events for a specific geofence.
4. Filter by event type (enter/exit) to focus on the events you need.

This allows you to verify that geofence events are being captured correctly and can be used for triggers, reactors, and automation.

### Reacting On-Device with Event Reactors

In addition to cloud-side automation, geofence events can be handled directly on the AutoPi device using **Event Reactors**. An Event Reactor listens for a specific event emitted by the device and executes a defined action immediately — without requiring a round-trip to the cloud. This makes it ideal for time-sensitive responses such as alerting a driver the moment a geofence boundary is crossed.

A practical example is playing an audible beep on the device when a vehicle enters a restricted area. As the alert sounds inside the vehicle, the driver is immediately made aware of the boundary violation and can take corrective action.

**Setting up a Reactor for Geofence Events:**

1. Navigate to **Services → Event Reactor** in the device configuration.
2. Click **Create** to define a new reactor.
3. Set the **event** to match the geofence event pattern, for example:
    * `vehicle/geofence/*/enter` — reacts to any geofence entry event.
    * `vehicle/geofence/Restricted Zone/enter` — reacts to entry into a specific named geofence.
4. Define the **action** to execute on the device when the event occurs — for example, triggering a beep alert.
5. Save the reactor.

Once active, the reactor will respond to geofence events in real time, directly on the AutoPi device, providing an immediate, driver-facing feedback mechanism to complement your cloud-side monitoring and alerts.

---

## Integrating Geofences with Templates

Use **[Templates](https://docs.autopi.io/cloud/device_management/templates/)** to automatically apply geofences to multiple vehicles at once, ensuring consistent geofence coverage across your fleet without manual configuration for each device.

### How It Works

When a fleet geofence is configured and a template is assigned to a device:
1. The geofence rules are applied to that device as part of the template configuration.
2. Any new device subsequently assigned to the template will have the geofence applied automatically. 
3. This eliminates the need to manually add geofences to each new vehicle.

This approach is ideal for scaling across large fleets, where you need consistent geofence coverage without repeating configuration for each individual vehicle.

### How to Add Geofences to a Template

Follow these steps to add geofences to a template:

1. Navigate to **Templates** in the Fleet Management tab
2. Either click on an existing template from the table or create a new template
3. Click on **Settings**
4. In the geofences field, select or configure the geofences you want to apply to this template
5. Save your changes

  ![Geofences in the Templates](/img/cloud/fleet_management/vehicles/geofences/template_geofences.png)

Once saved, all devices assigned to this template will automatically have the geofences applied.

### Best Practice

Create templates for different geofence scenarios (e.g., "Delivery Zones," "Restricted Areas") and assign them to vehicle groups. New vehicles added to those groups will automatically inherit the geofence configurations.

---

## Automating Actions with Geofence Events and Triggers

Use **[Triggers](https://docs.autopi.io/cloud/device_management/a-guide-to-triggers/)** to automatically respond to geofence events. Triggers listen for specific geofence events (enter or exit) and perform defined actions such as sending notifications, firing webhooks, or creating alerts.

### Common Use Cases

* **Delivery Confirmation**: send an email notification when a vehicle enters a delivery zone.
* **Unauthorized Access Alert**: send an immediate alert when a vehicle enters a restricted area.
* **Webhook Integration**: fire a webhook request when a vehicle exits a dispatch center to update your logistics system.
* **Route Monitoring**: send an alert on the AutoPi Cloud when a vehicle deviates from planned geofence boundaries.

### Setting Up a Trigger for Geofence Events

1. Navigate to **Device → Events** to confirm that geofence events are being received and captured correctly. 
2. Go to **Triggers** and click **Create**.
3. Set the event condition to match one of the following patterns:
    * `vehicle/geofence/*/enter` — triggers on entry into any geofence.
    * `vehicle/geofence/*/exit` — triggers on exit from any geofence.
    * Or use a specific geofence name instead of `*` (e.g., `vehicle/geofence/Downtown Zone/enter`) to target a particular geofence.
4. Define the action to perform when the event occurs:
    * Send email notification.
    * Send alert on AutoPi Cloud.
    * Fire a webhook request to an external system.
5. Save the trigger.

  ![Trigger based on Geofence Enter](/img/cloud/fleet_management/vehicles/geofences/trigger_geofence_enter.png)

### Example: Restricted Area Violation Alert

To receive immediate alerts when a vehicle enters a restricted area:
1. Create a geofence for the restricted area (e.g., "Out of Country Zone").
2. Create a trigger with event condition: `vehicle/geofence/Out of Country Zone/enter`.
3. Set the action to send an alert on the AutoPi Cloud or email notification.
4. When a vehicle enters the restricted geofence, you'll be notified instantly, allowing you to react quickly. 

---

## Use Case: Restricted Areas

Geofences are particularly useful for enforcing areas where vehicles should never travel. Create geofences around regions you want to prevent vehicles from entering, then set up triggers to notify you immediately when a vehicle violates these boundaries.

### Examples

* **Out-of-Country Boundaries**: define geofences around neighboring countries to prevent drivers from crossing international borders.
* **Off-Limits Zones**: restrict vehicles from entering competitor facilities, dangerous areas, or construction zones.
* **Authorized Service Areas**: ensure service vehicles only operate within assigned regions.

By combining geofences with triggers, you gain real-time visibility and can take immediate action to redirect vehicles or investigate unauthorized movement.

---

## Groups

## What Are Groups?

The **Groups** section in the Vehicles tab lets you organize multiple vehicles
into reusable sets. Groups make fleet operations faster and more consistent,
because you can apply configurations and workflows to a full set of vehicles
instead of selecting each vehicle one by one.

Common use cases include applying geofences, configuring templates, and creating
reports for a specific segment of your fleet.

![Vehicle groups](/img/cloud/fleet_management/vehicles/groups/new_groups.png)

## Create a Vehicle Group

1. Go to **Vehicles -> Groups**.
2. Click **Create**.
3. Enter a clear group name (for example, `Office Parking` or `Service Fleet`).
4. Use the search field to find and select the vehicles you want to include.
5. Click **Confirm** to save.

The new group will appear in the Groups list and can be reused across other
fleet features.

## Edit or Delete a Group

1. Open **Vehicles -> Groups**.
2. Click the group you want to update.
3. Add or remove vehicles as needed, then save your changes.
4. Delete the group if it is no longer needed.

![Vehicle group creation](/img/cloud/fleet_management/vehicles/groups/create_group.png)

---

## Use Groups with Other Features

Groups are designed to work across multiple AutoPi Cloud workflows.

### 1. Templates

You can configure a group in a template so that devices added through that
template are already associated with the same group. This adds another layer of
fleet identification and keeps device organization consistent.

To assign a group to a template:

1. Navigate to **Device Management -> Templates**.
2. Select an existing template from the list, or click **Create** to set up a new one.
3. Open the template's **Settings** tab.
4. Locate the **Vehicle Group** field and select the group you want to associate with this template.

Any device subsequently added to the template will automatically inherit this group assignment.

![Vehicle group in the Template](/img/cloud/fleet_management/vehicles/groups/template_groups.png)

Read the main guide: [Templates](/cloud/device_management/templates.md)

### 2. Fleet Geofences

When creating a fleet geofence, you can select one or more groups instead of
adding vehicles individually. All vehicles in the selected group will be
included in the geofence setup.

![Vehicle group in the Fleet Geofence](/img/cloud/fleet_management/vehicles/groups/geofence_group.png)

Read the main guide: [Fleet Geofences](/cloud/fleet_management/vehicles/geofence.md)

### 3. Reports

When creating a one-time report or scheduling a recurring report, you can select
a full group of vehicles instead of choosing vehicles one by one.

![Vehicle group in the Report Creation](/img/cloud/fleet_management/vehicles/groups/report_group.png)

Read the main guide: [Geofence Summary Report](/cloud/fleet_management/reports/geofence_report.md)

---

## Vehicles List

---

In the Vehicle section you can see all your vehicles, paired with a map showing 
their latest known position and geofences. In this section, we'll focus on the List tab. The vehicle list displays all 
your vehicles, along with their designated names and connection. 

![Vehicles list](/img/cloud/fleet_management/vehicles/list/vehicles_list.png)

## Vehicle Filters
Between the world map and the list, you'll find filtering options, which are 
useful when managing many vehicles. You can search for vehicles by entering any 
identifying information. There are also filters options for things like Open
Alerts, Last Communication or others. These filters help provide a clearer 
overview of your fleet. 

![Vehicles list filters](/img/cloud/fleet_management/vehicles/list/vehicles_list_filters.png)

## Vehicle Columns
The vehicle columns display all the necessary information about your vehicle like for 
example the location and geofence that have been assigned to it. However, you can choose what is shown in the table based on your preferences. 

![Vehicles list columns](/img/cloud/fleet_management/vehicles/list/vehicles_list_columns.png)

## Import/ Export your vehicles
Import/ Export fuction is available for easier overview of your fleet, helping you downloading CSV file in few clicks. This button lets you easily manage your fleet — you can either import a CSV file to add or edit all your vehicles at once or export a CSV file of your current vehicle list.

![Vehicles list import/export](/img/cloud/fleet_management/vehicles/list/vehicles_list_import.png)

## Vehicle actions
Actions icon lets you request last know location of your vehicle, or edit vehicle information or delete your vehicle. After clicking on a vehicle from the table, you will get redirected to [Vehicle Details page](https://docs.autopi.io/cloud/fleet_management/vehicles/vehicle-details/).

![Vehicles list actions](/img/cloud/fleet_management/vehicles/list/vehicles_list_actions.png)

---

## Automatic Exports

---

# Automatic Exporting
When enabled for a device, it will automatically trigger exports when a trip ends, and when an export is finished, it will send notifications (mail and/or JSON Http request)

:::tip
Contact [sales@autopi.io](mailto:support@autopi.io) to get more information.
:::

## Endpoints Overview

* `GET tasks/` 
Returns all tasks for the current customer
* `GET tasks/{task_id}/result/` Downloads the exported data from the task
* `GET tasks/{task_id}/remove_result/` Removed the exported data
* `GET logbook/trips/?device=device_id` Returns all trips for the specific device. (device querystring can be omitted, to show all trips for customer)

## How to Enable the Automatic Trip Export Functionality

The setting should be enabled per device, and this is done in Device > Advanced Settings > Trip > Auto Export
This can also be managed automatically for the entire fleet by using a template.

## Overview - Step by Step

1. The device sends an event that causes the server to trigger the trip_end event.
   This can be configured in the advanced settings.
   By default trips are started on an `vehicle/engine/running` event and stopped on `vehicle/engine/not_running|stopped` event.

2. This trip_end event causes a trip export to be scheduled, and will execute the export after the configured trip reopen limit, which by default is set to 10 minutes (600 seconds). This is because we need to make sure that all data from the device has been uploaded properly, before the export is executed.
   The minimum time it will wait to do the trip export after a trip ends, is 10 minutes.
   This means that even if the trip reopen limit is set to 1 second, the export will not run untill after 10 minutes.

   It also means that if a trip is reopened a number of times, it can execute multiple exports, each one overwriting the last.
   It will not schedule a new export if another is already running.
   
   Read more about how trips works [here](/cloud/fleet_management/vehicles/trips/).

3. When a trip export is scheduled, you can see the status with the tasks endpoint `tasks/`
   Where you can also see the ID and the trip ID of the trip being exported.
   
   It will only ever create one task per trip, ie. the list of tasks is one-to-one with trips.

   An export of a trip with the default set of logging should take only a few seconds, it of course depends on how long the trip is, and how much data is logged, as that will change the export time taken considerably. 
   But we are still talking seconds or minutes as it should for example, be able to export 10000 logged datapoints ever 400ms or so. 
   So a trip with 1mio datapoints should take roughly 40 seconds.

4. When the trip export finishes, it will send a signal to any listening triggers, which can be configured to send an email and/or a JSON payload. They are configured on the triggers page on the frontend on the `Triggers` page.
   The trigger type must be set to `signal` type, and it must target the signal `trip_export_finished`.

5. The exported data package can be downloaded by calling the `tasks/ID/result/` endpoint, which will return the file `TRIP_ID.json.gz` containing the exported data. After you have downloaded the exported data, you must remove the exported result by calling the endpoint `tasks/ID/clear_result/`
   This is done to prevent the system from re-broadcasting that the export is ready for download, as this is done once a day for all exports older than 2 hours, the reason for this is that if the webhook request is somehow missed, it will still get picked up later.

## Authentication

It's possible to access the API with a pre-generated API token, so that you will not have to authenticate and cache the JWT token as used when logging in to the frontend.
To use this new API token, simply set the following header on the request.

~~~http
Authorization: APIToken TOKEN
~~~

## Data Structure
The trip + any uploaded data is exported as json lines - this means that every line has a valid json object, see more here: http://jsonlines.org/

The data is sorted in ascending order.
The exported file is gzipped, so it must be unpacked before it can be interpreted as json.

The structure is as follows.
The first item is the trip object, and the next item(s) is all the data logged during that trip.

Example:

~~~json
{"id": "TRIP_UUID", "start_time_utc": "2020-01-01T08:16:52.962918Z", "end_time_utc": "2020-01-01T08:22:00.942395Z", "start_position_lat":  "56.144...", .... }

{"@vid": VEHICLE_ID, "@uid": "DEVICE_UNIT_ID", "@ts": "2020-01-01T08:16:52.962918Z", "@tag": "vehicle/engine/running", "@t": "event.vehicle.engine", "@rec": "2020-01-01T08:17:56.128398Z"}

{"obd.rpm.unit": "revolutions_per_minute", "@vid": VEHICLE_ID, "@uid": "DEVICE_UNIT_ID", "obd.rpm.value": 830.5, "@ts": "2020-01-01T08:16:53.001449Z", "@t": "obd.rpm", "@rec": "2020-01-01T08:17:56.128138Z"}

{"@vid": VEHICLE_ID, "@uid": "DEVICE_UNIT_ID", "@ts": "2020-01-01T08:16:53.107849Z", "@t": "obd.coolant_temp", "obd.coolant_temp.value": 19, "obd.coolant_temp.unit": "degC", "@rec": "2020-01-01T08:17:56.128149Z"}
~~~

## Manually Executing Trip Export Task

After a while the trip export will no longer be present on the server, and if a new export is needed, you can re-run the export for an old trip, depending on the data retention conditions for the specific environment, using the `tasks` endpoing like so.

`POST tasks/`
~~~json
{
    "task": "core.tasks.es_trip_export",
    "args": [],
    "kwargs": {
        "trip_id": "TRIP_ID"
    }
}
~~~

This will return a new task object, and using the task id you can retrieve the result using the above mentioned `tasks/ID/result/` endpoint, when the task has completed.

## Manually Retrieving Trip Export Task Results

To retrieve the exported data, you can retrieve a list of the tasks, and get the task ids from there.

`GET tasks/`
~~~json
[{
    "id": 100,
    "created_at": "2020-01-27T17:30:42.460311Z",
    "task": "core.tasks.es_trip_export",
    "args": [],
    "kwargs": {
        "trip_id": "00000000-0000-0000-0000-000000000000"
    },
    "state": "SUCCESS"
}]
~~~

In the response for each task you can see the task ID, and which trip ID it was executed for.

Now you can use the task ID to retrieve the result, in this case: 100

`GET tasks/100/result/`

---

## Introduction(Vehicles)

---

The Trips section provides in-depth information about the vehicle's trips. 
Trips are automatically detected based on the events sent from the device, by default the 
[engine events](/cloud/device_management/events/vehicle.md#engine-events) are used, these can be customized in the 
[advanced settings](/cloud/device_management/advanced_settings/autopi_tmu_cm4/trip.md#event).

This will display the trip route on a map along with the starting and ending addresses, duration, and distance travelled. 
Additionally, you can review **events** that occurred during each trip, such as 'engine running/stopped' and 'position moving/standstill' and **dashboard** widgets can display data from a specific trip — including position, speed, battery level, total odometer, and more. You can easily customize your dashboard to show the metrics that matter most to you. If you’re unsure how to set it up, check out our guides on configuring widgets for a personalized view of your data on AutoPi TMU CM4 or on AutoPi mini.

You also have an option to **filter** trips based on the desired date range and an option to **categorize trips** as either personal or business for better differentiation of your fleet operations. Another feature is **Export trips** that allows you to export trip data to Excel/CSV for easier handling. 

![Trip example](/img/cloud/fleet_management/vehicles/trips/intro/trip_demo_example_1.png)

:::tip
You can check the events page on [my.autopi.io](https://my.autopi.io) to see all events logged from your device. When troubleshooting it is one of the first places to check if you are unsure why something happened. By looking at the events you can usually get a really good idea about why the device did something.
:::

## Trip Generation

When the server receives the start|stop trip events it will do the following.

#### On Start Trip Event (Default: `vehicle/engine/running`)
   * If closed trip exists, the end time will be checked:
     * If older than N minutes (default: 10), a new trip will be created, with the start_time set to the timestamp of the event.
     * If not older than N minutes, it will not create a new trip.
   * OR: If open trip exists, the start time will be checked:
     * If older than N minutes, a new trip will be created.
     * If not older than N minutes, it will ignore the event, and just keep using the trip from before.

#### On Stop Trip Event (Default: `vehicle/engine/not_running`|`vehicle/engine/stopped`)
   * Check if a trip is currently in progress using the timestamp of the event.
     * If it can find one, it will close it.
     * If it can't find one, the event will be ignored.

This means that a typical trip generation lifecycle can look like this

1. Trip is created
2. Data is logged
3. Trip is closed
4. Trip is reopened if new event is within 10 minutes of the last trip close event.
5. More data is logged
6. Trip is closed

:::tip
For EV's it's possible to set up new events so that the trip generation works as expected.
See more here: [Setup power cycle for an electric vehicle](/getting_started/electric_vehicles/power-cycle-for-electric-vehicles/)
:::

:::note
For [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini), the start/stop trip events are `trip/start` and `trip/stop`
:::

## How to Export Trips
Our Trips page gives you a complete overview of all trips taken by your vehicle or fleet. You’ll see key details like distance traveled, start and end locations, routes, and even event data — all displayed through various widgets on your dashboard.

### Getting started with API
For an even deeper dive into your data — whether you want raw data or aggregated insights — you can export trip data using our REST API. Here are steps you need to follow, but visit this guide for more detailed step by step guide: Getting started with API
1. Authenticate: head over to our API documentation portal, where you can authenticate by setting your token. You can use two different tokens for flexibility or send requests manually using tools like Postman.
2. Explore the Endpoints: once you’re authenticated, you’re ready to start exploring! 
3. Export Your Data: with full API access, you can now pull all the trip data you need — whether it’s a personal vehicle or your entire fleet.

### Retrieving list of trips and pulling of data
To get full trip data, you’ll first need to retrieve the list of trips, then pull the specific data you need for each trip’s duration:
1. You can access trip data from either the API Endpoint or AutoPi Cloud:
    - Trips endpoint provides start/stop times and trip summaries, check out Logbook - trips list.
    - Trips page, gives you an opportunity for the trips to be exported to excel/csv format as mentioned above.
2.  Use these endpoints to pull the data: Logbook storage read list and Logbook storage raw list  

Be sure to follow this guide on how to authenticate and use our REST API to get everything set up smoothly: Getting started with API.

:::note
The reason that there is no single endpoint way to retrieve all data for a specific trip is because
there can be a lot of data for trips, and our system can query and filter very large amounts of data
very very fast, but the downside is that it is not really geared towards downloading large amounts
of data in one go.
:::

:::tip
If you have our AutoPi TMU CM4 device, you can also set up automatic exporting of trips for your vehicle or fleet. 
For business customers we also support automatic exporting of trips which will call a webhook on
an external system signalling that an export can be downloaded. Read more about Automatic Exports.
:::

---

## Vehicle Details

The **Vehicle Details** section of AutoPi Cloud centralizes all key information about your vehicles in one place. It provides general vehicle data, real-time widget displays, trip history, active alerts, and diagnostic codes — giving you the tools you need to efficiently manage your fleet and maintain operational performance.

![Vehicle name](/img/cloud/fleet_management/vehicles/vehicle_details/vehicle_name.png)

### Overview
The **Overview** section presents a summary of key vehicle information through a series of widgets. Here you can find details about the vehicle itself, the fleet it belongs to, active alerts, assigned geofences, and location data. It also displays cumulative statistics on time driven and total distance traveled.

![Vehicles overview](/img/cloud/fleet_management/vehicles/vehicle_details/vehicles_overview.png)

---

### Dashboard
The **Dashboard** section offers a visual representation of real-time vehicle data. Data can be displayed in a variety of widget formats to suit your monitoring needs:

* Line chart
* Area chart
* Map
* Gauge
* Bar chart
* Pie chart
* State timeline
* Linear gauge
* Numeric

You can filter data by date range to track metrics such as vehicle position, speed, RPM, and more. Widgets are fully customizable — build your own to surface the data that matters most, or use the **Auto Generate** feature to have the platform automatically create a dashboard based on the latest data received from the vehicle.

The platform supports **multiple dashboards**, so you can create and organize as many as needed. Dashboards are grouped into three categories:

1. **Autogenerated** — automatically created based on data received from the device
2. **Mine** — dashboards you have created manually
3. **Shared** — dashboards shared by an admin user within your organization

:::note
Users with Admin permissions can create dashboards and push them to specific vehicles based on vehicle type or Make/Model. You can read more here: [Shared Dashboards](https://docs.autopi.io/cloud/fleet_management/configurations/dashboards/#creating-a-shared-dashboard).
:::

![Vehicles dashboard](/img/cloud/fleet_management/vehicles/vehicle_details/vehicles_multiple_dashboards.png)

#### Create New Dashboard 
To create a new Vehicle dashboard:

1. Navigate to **Vehicle> Dashboard**.
2. Click **Create dashboard**.
3. Enter:
   - **Name**: A clear dashboard name.
   - **Description** (optional): A short description of its purpose.
4. Click **Create**.

![Create New Device Dashboard](/img/cloud/device_management/dashboard/create_new_device_dashboard.png)

#### Adding Widgets to the Dashboard

Use real vehicle data when possible to validate widget configuration.

:::note
The **Autogenerate** option creates widgets automatically from available device data. This is a practical starting point when creating a dashboard from scratch.
:::

To add a widget manually:

1. Navigate to the **Dashboard** and click **Actions**.
2. Click **Add widget**.
3. Select a widget type.
   ![Widget types](/img/cloud/fleet_management/configurations/dashboards/widget_type.png)
4. Configure the widget:
   ![Widget configuration](/img/cloud/fleet_management/configurations/dashboards/configure_widget.png)
   - **Title**: Widget display name.
   - **Visualization**: Chart or display type (line chart, map, gauge, and so on).
   - **Field**: Logger or signal to display.
   - **Aggregation**: Average, minimum, maximum, sum, or raw data.
   - **Unit**: Unit shown in the widget.
   - **Auto scale**: Scales values automatically to fit the visualization.
   - **Hide gaps**: Shows or hides periods with no data.
5. Click **Save** in the widget editor, then save the dashboard.

#### Widget Controls

Each widget has the following controls in the top-right corner:

| Icon | Action |
|:------:|:--------:|
| Circle (refresh) | Refresh the data displayed in the widget |
| Two-dot (edit) | Open the widget editor |
| Download | Download the data for this widget only |
| X (delete) | Remove the widget from the dashboard |

---

### Trips
Next to Dashboard you’ll find the **Trips** section. This section provides detailed
information about the vehicle’s trips, displaying the trip route on a map along 
with the starting and ending addresses, duration, and distance traveled. You can 
also categorize trips as personal or business and, if necessary, export trip data.  

![Vehicles widgets](/img/cloud/fleet_management/vehicles/vehicle_details/vehicle_trips.jpg)

Above the map, you have filtering options for the trips, choose a week, last month
or a custom range you would like to view, and it will show you a list of all the 
trips that have been taken by this vehicle during the filtered time. Clicking on 
one of the trips will show you a route on the map, the distance it travelled and 
how long the trip took.  

You can further filter the trip view based on the date or number of months, as 
well as by distance or duration of the trips. Next to the filtering options, you 
will see overall data of this vehicle’s trips, including the total number of 
trips made, total distance driven, total duration, and average distance and duration.

---

### Alerts
The **Alerts** tab displays all active alerts associated with the vehicle. The table lists each alert's severity level, occurrence count, and description, giving you a clear view of any issues requiring attention. Alerts can be dismissed or resolved directly from this view.

![Vehicles alerts](/img/cloud/fleet_management/vehicles/vehicle_details/vehicles_alerts.png)

### Diagnostics
The **Diagnostics** tab is the final section of the Vehicle view. It lists all diagnostic error codes currently reported by the vehicle, providing structured insight into any detected issues.

For each diagnostic code, the following information is available:

* The error code and its description
* Timestamps for the first and last occurrence
* A count of how many times the error has been recorded

This gives you a clear picture of not only what the issue is, but also when it first appeared and how frequently it recurs. When used alongside the **Fault Codes** functionality, the Diagnostics tab becomes a powerful real-time monitoring tool. Critical issues can trigger immediate notifications via cloud alerts or email, allowing your team to respond promptly. You can also configure a custom **Trigger** to automate actions based on any specific diagnostic code.

![Vehicle diagnostics](/img/cloud/fleet_management/vehicles/vehicle_details/vehicle_details_diagnostics.png)

---

## Introduction(2)

This section is all about the [Cloud](https://www.autopi.io/software-platform/cloud-management) system. It goes over details, such as the different configuration
options that can be set, the events that can be seen from the device. More complex functionalities
are also explored in this section.

## What is the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management)?

The [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) is a system created to more easily manage your [AutoPi](https://www.autopi.io) device. The [Cloud](https://www.autopi.io/software-platform/cloud-management) is divided into several sections:

- Device management 
- Fleet management 
- API

  

### Device Management
This is an area that shows the current state of your devices and allows you to easily change that
state to whatever is needed. For example, there is a section of advanced settings that are
available that change various functionalities of the device like WiFi, hotspot, accelerometer
and power settings. It is also possible to setup the device to send data back to your own servers.
This way data can be kept private if needed. It possible to manage and maintain multiple devices at the same type, by applying templates to groups of devices.

### Fleet Management
The [Cloud](https://www.autopi.io/software-platform/cloud-management) also allows you to view data that has been recorded from your vehicle. There is a dashboard that
shows past OBD-II data like RPM, speed and fuel level. The device also sends back information about
[trips](/cloud/fleet_management/vehicles/trips/), which are also viewable. The [Cloud](https://www.autopi.io/software-platform/cloud-management) also keeps track of the
[events](/cloud/device_management/events/index.md) that were triggered on your device. In the events page, you are
able to view all events and filter them by date or tag.

### [Cloud](https://www.autopi.io/software-platform/cloud-management) API
The [API](/getting_started/api/) gives you acccess to all the same functionalities you see in the [Cloud](https://www.autopi.io/software-platform/cloud-management). Through the API it is possible to extend the features to your own systems or APP solution and thereby build on top of the platform. 

## Get Your Device Today and Get Started!

  

[![](/img/hardware/autopi_mini/AutoPi_Mini_5_Top_right.png) **AutoPi Mini** Build for fleet volume scaling and ease of install. CAN bus ready with support for legacy protocols. Support wide range of OEM Parameters. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-mini)

[![](/img/hardware/autopi_tmu_cm4/TMU_Floating_Topside_V1_scaled.png) **AutoPi TMU CM4** Based on Raspberry Pi Compute Module 4. Best for custom solutions requiring large computation power and expansion options. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-telematics-unit-cm4-4g-lte-edition)

[![](/img/hardware/autopi_canfd_pro/canfd_pro_trans.png) **AutoPi CAN-FD Pro** Based on Raspberry Pi Compute Module 4. Our most powerful device to date, designed for full speed automotive datalogging of dual CAN-FD channels. See price.](https://shop.autopi.io/products/autopi-can-fd-pro)

[![](/img/shared/autopi_devices_trans.png) **Comparison of all AutoPi devices** Compare our devices and find the best fit for your requirements.](https://www.autopi.io/hardware/compare/)

---

## Automatic OBD Logger Pausing

---

Automatic OBD Logger Pausing is a feature that enables the [AutoPi](https://www.autopi.io) device to automatically pause any OBD loggers when it
detects that the vehicle has stopped shaking (which also likely means that the vehicle has stopped moving). This
feature is useful in situations where the vehicle that the AutoPi is plugged into has a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus protection. Such
vehicles usually detect [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus traffic when the vehicle is locked and in turn trigger the alarm of the vehicle - this
is done to try and protect the vehicle from being fiddled with externally through the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. Examples of such
vehicles are the BMW i3, some Mini Coopers and some Porche models.

:::note
In fact, not only the loggers are being paused, but in general the device is not allowed to send any [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) frames on the
[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus of the vehicle. This means that if you attempt to manually send a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) frame with a command such as `obd.send`
or `obd.query` you will receive an error.

Passively listening (also known as sniffing) on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus is still allowed though.
:::

## How Does it Work?

The Automatic OBD Logger Pausing feature works by using the data from the accelerometer integrated into the AutoPi. The
accelerometer will detect motion and trigger events based on the motion detected. The three events that
are being triggered are:

- `vehicle/motion/steady`
- `vehicle/motion/shaking`
- `vehicle/motion/jolting`

Using these events (and the `vehicle/motor` or `vehicle/engine` events as helpers), the AutoPi is able to determine when
it's a good time to pause and unpause the loggers to avoid setting off the alarm of the vehicle. 

:::note
Keep in mind that the `vehicle/motion/jolting` event is not used to determine the behavior of the Automatic OBD Logger
Pausing feature.
:::

## How to Set It Up?

To enable the Automatic OBD Logger Pausing functionality, you will need to ensure the following advanced settings are
set on your device:

- `OBD > Automatic Logger Pausing` must be set to `True` (Enabled)
- `Accelerometer > Motion Events > Enabled` must be set to `True` (Enabled)

You can confirm that the setup has been made successfully if you confirm the following two changes in your device's
services:

1. Navigate to the workers of the Accelerometer Manager (Services > acc_manager > Workers) - there you should see an
   `xyz_logger` worker. If you open it up, you should be able to see that the trigger in the Workflow is
   `motion_event` - this enables the `vehicle/motion/*` events.
2. Navigate to the reactors of the Event Reactor (Services > event_reactor > Reactors) - there you should see two
   new reactors - `enable_obd_on_motion_shaking` and `disable_obd_on_motion_steady_or_trip_end` - these reactors are
   responsible for enabling and disabling the OBD logging.

## Troubleshooting

Sometimes, you might notice that even though you have enabled the Automatic OBD Logger Pausing feature, the AutoPi is
still sending [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Frames on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. This is usually caused by your vehicle being too easy to shake which in turn
triggers a `vehicle/motion/shaking` event much more easily (this is the event that reactivates the OBD loggers).
Depending on the vehicle type that you are using, the driving behavior, road conditions and more the device might think
that the vehicle is being driven while in fact it isn't or vice versa.

For this reason, we have made it possible for you to change and fine-tune the way that those motion events are being
triggered. You can find the fine-tuning settings in the advanced settings of your device under Accelerometer > Motion
Events. We suggest that you focus primarily on the Debounce Delay and Shake settings, because the
`vehicle/motion/jolting` event is not used to reactivate the OBD loggers - only the `vehicle/motion/shaking` event is.

---

## CAN Bus Configuration

---

This page describes what to do if you've tried autodetecting the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus, and this has not worked.
To be more exact, we'll reiterate on how to use the auto-detect feature, how the feature works and
how to do what it does manually, how to check whether the vehicle supports passive [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus 
monitoring.

<!-- ## [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Concepts

### WIP, the Same Concept On the Cloud Means a Different Thing On the Device

General concepts:
- Protocol - a numbered set of configurations, which specify a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) interface, default baudrate, 
extended header flag, data length, data decoding information and others.
- Baudrate - data transmission speed
- Autodetection - a process that is invoked manually or automatically, which helps find the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus
configuration used by your vehicle

Cloud portal concepts:
- [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus - a collection of configurations including a protocol and baudrate that get translated to
device configurations
- Default bus
- Autodetected bus
- Vehicle

Core concepts:
- Baudrate
- [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Interface/Channel
- Header Length -->

## Common Causes of Failures and How to Troubleshoot
Under normal circumstances, the device will boot for the first time and will try to autodetect the
protocol automatically, then send the results back to us, where we create a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus for your device,
flagged as autodetected.

![Autodetect bus](/img/cloud/obd_ii/can_bus_configuration/autodetected_bus.png)

Sometimes, this will not happen. This can be because of multiple reasons:
- The device is in an incorrect state
- Internet connectivity issues
- The vehicle does not support OBD-II
- The vehicle supports OBD-II, but the ECUs are not on
- The vehicle supports OBD-II, the ECUs are on, but they are not active
- The vehicle uses a configuration, which is not checked by the autodetect
- A combination of 2 or more of the above 

### The Device is in an Incorrect State
Whenever an [AutoPi](https://www.autopi.io) device is powered on, sleep timers are created, which will turn the device off in a few
minutes. Check the status of the LEDs on the side of the device to make sure the device has not gone to sleep.
Both the green and blue LEDs should be lit constant and bright. If the blue LED is breathing (varying in its 
bringtness from dim to bright), it's sleeping. The easiest way to get it to turn back on is to disconnect it
from the OBD-II port, and reconnect. Wait until both LEDs are solid, then move on to further steps.

:::note
You can learn more about the power cycle on the [Power Management Documentation](/core/power_management/index.md).
:::

### Internet Connectivity Issues
These can make it seem like the autodetect is not working. Unless you're connecting to the device through 
its Wireless Access Point and running commands from its local terminal, you should test the connectivity
before checking for any of the further issues. Try running the following command from the terminal in the
[Cloud](https://www.autopi.io/software-platform/cloud-management) portal:
```python 
test.ping
```

Note that just because you see some data in the dashboard, doesn't mean that 
there's a good enough connection for commands to be received by the device, and for it to be able to send
the command results back. If you get a response that looks something like the screenshot below, you may
move on further. Otherwise, check out the [4G Troubleshooting Guide](/getting_started/autopi_tmu_cm4/4g_internet_setup_troubleshooting.md).

![True response](/img/cloud/obd_ii/can_bus_configuration/test_true.png)

### The Vehicle Supports OBD-II, but the ECUs are Not Running
This is the most probable explanation. Most ECUs will not be running while the vehicle is off, therefore,
if you're trying to run the autodetect with the engine turned off, you're almost sure to not succeed.
The fix for this is to turn the ignition on.

### The Vehicle Does Not Support OBD-II
This is the simplest explination of why autodetect is not working. In the section 
"[How Bus Autodetection Works](#how-bus-autodetection-works)", we explain that the feature relies on
responses to a specific OBD-II query that should be supported by all OBD-II compliant vehicles.

If this seems to be the case, all is not lost yet. It is likely that the vehicle supports another protocol
like J1939, UDS or something proprietary to that manufacturer. Check out the section
on non-OBD-II queries (COMING SOON) and [Passive CAN Traffic](#passive-can-traffic).

### The Vehicle Supports OBD-II, the ECUs are On, but They are Not Active
This is the most complicated case. There's multiple ways this issue can present itself:
1. The bus is autodetected, but the vehicle is periodically not responding to queries that have worked before
2. Manufacturer-made OBD-II scanners work, however, the [AutoPi](https://www.autopi.io) can not read the same data
3. The manufacturer claims to support OBD-II, however, whichever configuration you try, no data can be read
4. Others not mentioned

In this case, there's a few things you can try:
- If you've got an OBD-II adapter that's able to read data, you can connect both the adapter and the [AutoPi](https://www.autopi.io) to
the vehicle's bus and see what the adapter does. One common case is that it sends some [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) frames, 
which activate the ECUs and they start to respond afterwards. You can then set up workflows that send these same
frames at startup to active the ECUs. It can also be the case that the vehicle does not support OBD-II and 
this can help you find out what protocol it is actually using.
- Browse the internet to see if anyone has already tried reverse engineering the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus on your vehicle. Sometimes,
what works on one car from the manufacturer will work for another.
- Contact the manufacturer to find out how the ECUs expect to be communicated with.
- Try and reverse engineer the bus yourself. This can be a tedious and time consuming task. Depending on your 
preferred workflow, you may prefer to [ssh into the device](/developer_guides/how_to_ssh_to_your_device.md) and use the Linux 
[can-utils command line utility](https://manpages.debian.org/testing/can-utils/index.html). The most notable commands
in this are *candump* and *cansend*. To change the configuration of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) connection, you can use the 
[socketcan.up and socketcan.down](/core/commands/socketcan.md) commands. 

### The Vehicle Supports OBD-II, but the Vehicle Uses a Configuration, Which is Not Checked by the Autodetect
If you take a look at the [how bus autodetection works](#passive-can-traffic) section, you'll learn that the
device checks a pre-defined list of configurations. It's possible that your vehicle uses one that is not in this list.
Check the [Finding configuration manually](#finding-configuration-manually) section to see further steps.

## How Bus Autodetection Works 
The easiest way to run autodetection is through the [Cloud](https://www.autopi.io/software-platform/cloud-management) portal from the Vehicles Editor. This will do 2 things.
First it will try to find the correct configuration for [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) connectivity (see 
[Finding Configuration Manually](#finding-configuration-manually) for an explanation). Second, it will try to find
the supported OBD-2 PIDs and create them in your Library.

### Automatic Autodetection Flow

When first installing a device, an autodetect will be run automatically for cars, which would normally 
support the OBD-II protocol. Expressed programmatically, this set of conditions must be met for automatic 
bus autodetection to happen:

- The device is associated to a vehicle
- The vehicle is of "Internal Combustion Engine" (ICE) type
- The vehicle has a car model
- The vehicle does not already have an auto-detected bus, which supports one or more standard OBD-II PIDs

If all these conditions are met, the device will follow this flow when booting:
1. The device downloads configurations from our backend
    1. The backend checks the conditions listed above
    1. The backend adds an `obd.commands` command to the "startup modules" in the configuration
1. The device executes the startup modules, one of which is the `obd.commands` command
1. `obd.commands` runs a `0100` PID query with a predefined list of configurations
1. If none of the configurations returns a result, raise an `Unable to autodetect OBD protocol` error
1. If we see a response, run the rest of the `obd.commands` functionality which queries for supported PIDs,
using the just found configuration.  
1. The device sets its currently used protocol to the autodetected protocol, and updates its internal 
'supported PID database'
1. The device returns the protocol and supported commands to the backend through the cloud returner
1. The backend uses this to create a bus for the device's currently assigned vehicle, creates OBD-II 
PIDs in your library and adds the most common ones to the bus

### Protocol Autodetection Flow
When autodetection is invoked, it will first try to find the correct interface and baudrate, then the 
set of supported PIDs. To find the interface and baudrate, the device goes through the following flow:
1. Destroy the current connection if one exists
2. Set up a new connection with a set of configurations from a predefined list.
3. Send an OBD-II `0100` request
4. If we don't get a response, go back to step 1 and try again until we either see a response, or we run 
out of configurations to try.
5. If we get a response, that's the valid protol. 

## Finding Configuration Manually
Protocol determines which bus (HSCAN or MSCAN) and what bitrate is being used:
- 31 - HSCAN (can0), 11-bit
- 32 - HSCAN (can0), 29-bit
- 51 - MSCAN (can1), 11-bit
- 52 - MSCAN (can1), 29-bit

The most common baudrates are 125000, 250000 and 500000.

Go through all combinations of these: protocol 31 and baudrate 125000, protocol 31 and baudrate 250000, etc. 
Once you find a combination that works, note down the protocol number, interface, the header length and the 
baudrate. You can then create the bus in the [Cloud](https://www.autopi.io/software-platform/cloud-management) Portal, and set up loggers for it. 

Note that if you run the `obd.protocol` command, you will see many more than the 4 protocols listed above. 
Some of these are legacy and  are no longer supported by the hardware. However, some add message decoding 
information to the queries, which can have a difference whether a response is received or not. It's worth 
trying some of these if the 4 listed above do not work.

### OBD-II
If you have reason to think the vehicle should support OBD-II, but autodetect is unable to find the protocol,
you may try and find it manually. What this essentially entails is trying to retrieve the OBD-II commands PID
(`0100`) from the vehicle with the configurations listed above. This can be one with the `obd.commands` query:

```bash
$ obd.commands protocol=32 baudrate=500000
```
```yaml
# Configuration invalid
: error: No data received when trying to verify connectivity of protocol '<class 'can_obd_conn.HSC_ISO_11898_11bit_500k'>'

# Configuration valid
_stamp: '2000-01-01T10:10:10.100000'
protocol:
  autodetected: false
  baudrate: 500000
  ecus:                   
  - 2
  id: '32'
  name: HS CAN (ISO 11898, 29bit, 500kbps, var DLC)
supported:                                            
  ABSOLUTE_LOAD: Absolute load value (PID 0x0143)
  ACCELERATOR_POS_D: Accelerator pedal position D (PID 0x0149)
  ...
```

### Passive [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Traffic
:::important
From Core sofware version 1.24.0, the obd.monitor command will show both 11-bit header and 29-bit header messages, no
matter if the selected protocol is 11-bit or 29-bit. When setting up [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Signal loggers, the bus' default protocol must
be of the same header length as the messages being received. 
:::

Many vehicles nowadays also have ECUs broadcasting data on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. To find out if this is the case, you
can follow the same idea as with OBD-II, except you're trying to listen to any data on the bus:

```bash
$ obd.monitor duration=5 verify=False protocol=32 baudrate=500000
```

```yaml
# Configuration invalid:
: error: No data received from vehicle within timeout

# Configuration valid:
_stamp: '2000-01-01T10:10:15.100000'
_type: raw
values:
- _stamp: '2000-01-01T10:10:10.100000'
  value: 17fc007b03918511aabbccdd
- _stamp: '2000-01-01T10:10:11.100000'
  value: 07fc007b127abbfd12412381
- ...
```

<!-- ## Stage 5: Acceptance; AKA: Giving Up
The notion of "giving up" often carries a negative connotation, frequently associated with failure, defeat, or a lack of willpower. However, there's an underrated glory in giving up when it leads to a reevaluation of priorities, the lifting of unnecessary burdens, or the freeing up of energy and resources for more meaningful pursuits. Sometimes, giving up is a courageous act of self-awareness, acknowledging that a path we've started down isn't serving us—or anyone else—well. In such cases, the decision to step back can lead to new opportunities, renewed focus, and the kind of growth that stubborn persistence might never have afforded us. -->

---

## Create a Valid Can Dump

---

The following is a guide to obtain a Valid [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) (Controller Area Network) dump.

The first step involves capturing a valid [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) dump from
the vehicle you are working with. This dump contains all the data traffic 
exchanged between various ECUs (Electronic Control Units) within the vehicle. 
It is essential to ensure that the captured data accurately reflects the 
operational state and configuration of the vehicle’s [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus.

Tools such as candump or other diagnostic software compatible with the vehicle's 
[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) system are typically used to retrieve this data.

## Set Up a Virtual [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Interface on the Device:

Next, you need to configure a virtual [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) (vcan) interface on the device where 
the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) loop will be tested. A virtual [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) allows for emulation of a physical 
[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) interface, enabling testing and simulation without needing actual [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) 
hardware. This step is especially useful during development or in situations 
where physical hardware is not available.

The setup can be done using Linux utilities like ip link to create a virtual [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) 
interface, followed by configuring its bitrate and bringing the interface up.

To set up the interface use the command ip link set vcan0 type vcan bitrate “num”
– Replace num with the desired bitrate value, matching the data in the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus dump.

## Load CAN Dump Data Into Virtual CAN:

After configuring the virtual [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) interface, the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) dump previously captured 
needs to be loaded into the system. Use canplayer to replay the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) traffic from 
the dump file over the virtual interface, simulating the behavior of the vehicle's
[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus on your device.

Canplayer is a command line tool where canplayer invokes the application
the following are the valid input parameter:

- `-I` followed by the path of your [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) dump
- `-l (num)` num being number of times you want the file repeated `-i` for infinite
- `-t` ignore timestamps
- `-g<ms>` gap in milliseconds, default 1
- `-s<s>` skips gaps in timestamp (s = seconds)
- `-x` disable local loopback of sent [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) frames
- `-v` verbose – print sent [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) frames

---

## Create CAN Signal Loggers

---

# Create [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Signal Loggers

[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals play a crucial role in vehicle communication, differing from PIDs in their use and structure. While PIDs (Parameter IDs) are standardized codes used across different vehicles for obtaining specific data points (like engine RPM, temperature), [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) (Controller Area Network) signals are more direct, low-level messages that devices within the vehicle use to communicate with each other. Understanding these differences is key to effectively logging and analyzing vehicle data.

**Step 1: Start with a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Signal**

Before you can log anything, you need a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal to monitor. [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals are not standardized like PIDs, meaning they can vary significantly between different vehicle makes and models. To create a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal, you must first identify the signal's properties, including its ID, format, and the data it carries.

Identification and Documentation: Use vehicle documentation or tools to identify the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal. This may involve using a DBC file or capturing and analyzing traffic on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) network to find the signals relevant to your needs.

Creation: Once identified, you can create a representation of this signal in [CAN Signals](/cloud/obd-ii/#can-messages-and-can-signals)

**Step 2: Navigate to Your Device's Logger Section**

With your [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal defined, the next step involves setting up the environment to log this signal.
- Access: Log into your device's management interface and navigate to the 'Loggers' section.
![Loggers overview](/img/cloud/obd_ii/create_can_signal_loggers/logger_overview.png)

  
- New Logger: Look for an option to create a new logger.
![Logger overview create](/img/cloud/obd_ii/create_can_signal_loggers/logger_overview_create.png)

**Step 3: Configure the Logger**

The creation of a logger involves specifying which signals to log and other parameters:

- Signal Selection: In the modal window that appears upon choosing to create a new logger, select the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal you created earlier from the dropdown menu.

- Bus Selection: Specify the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus on which your signal is present. Vehicles often have multiple [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) buses for different systems (e.g., powertrain, chassis). Ensure you select the correct one for your signal.

- Name Override: You can specify a different name for your logger here, otherwise its name remains the same as the Signals.
![Create logger](/img/cloud/obd_ii/create_can_signal_loggers/create_can_logger.png)

**Step 4: Create the Logger**

Finally, you're ready to create the logger:

Finalize: Review your selections to ensure everything is correct, then click the "Create" button to finalize the creation of your [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal logger.

Confirmation: You should receive a confirmation that your logger has been created successfully. Congratulations, you've set up a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal logger!

Congratulations! You have now created a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal logger.

This process allows you to monitor and record data from specific [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals on your vehicle, providing valuable insights into its operation. Unlike working with PIDs, which often require working through a vehicle's OBD-II interface and are limited to predefined parameters, logging [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals gives you access to a broader range of data directly from the vehicle's internal networks. This approach can unveil more detailed information and support advanced diagnostics and customization projects.

---

## Create PID Loggers

---

As explained in the [introduction](index.md), PIDs are used to request and receive
data from the vehicle. It can be real-time data, such as RPM, Speed, Fuel Level and so on, but it
can also be in the form of Diagnostic Trouble Codes (DTCs) and other troubleshooting data useful to
vehicle technicians.

In this guide, we will take a deeper look at how PIDs are structured and will also create a custom
PID Logger for our [AutoPi](https://www.autopi.io) device.

## Dissecting a PID

#### Request
Let's take a deeper look at the PID request that was presented in the introduction.

```
# PID request
7DF # 02 01 0C 00 00 00 00 00
```

Let's start with the general structure of the message. Firstly, we have the header (`7DF`). The
header is a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) identifier which defines who is sending the message and if it is a request or a
response. In this case, `7DF` is the header used by external test equipment to make requests towards
ECUs in the vehicle. The hashtag symbol (#) simply separates the header from the body of the
request.

Now, let's shift our focus on the body of the PID. The first byte of the body shows the length
(in bytes) of the rest of the body. In this case, we only have two relevant bytes, so the length is
`02`. The next byte defines which diagnostic service should be queried, while the third byte defines
exactly which value is being queried. Mode `01` is the current data diagnostic service, while `0C`
queries for the RPM value stored in that diagnostic service - i.e. the current value.

The rest of the body isn't going to be read by the ECU, so it is left empty.

#### Response
The response from the ECU will look very similar with a few differences:

```
# response from ECU
7E8 # 04 41 0C 0F A0 00 00 00
```

In this case the header is `7E8` which is the header used when ECUs send responses towards external
test equipments (i.e. requests made with the `7DF` header). Again, the header is separated from the
body with a hash sign and the first byte of the body defines the length of the data.

However, the second byte changes a bit - it is the same as the query's second byte, except that
0x40 is added to the value. The value after that is identical to the code sent with the request
(`0C` for RPM), while the rest of the body is the actual value returned. Usually, all you need to
do is to transform the hexadecimal value to a decimal value, but that's not always the case.
Sometimes there's extra calculations that need to be done in order to get the value, for example
in this case - the total value needs to be divided by 4, making the result:

```
0F A0 in hex is 4000 in decimal
4000 / 4 = 1000 RPM
```

### Requesting PIDs
You can send a PID request on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus manually using one of two commands:
[`obd.send`](/core/commands/obd.md#obdsend) or [`obd.query`](/core/commands/obd.md#obdquery). Here
are examples of how to use both of them to send the aforementioned PID.

```
$ obd.query MY_RPM header=7DF mode=01 pid=0C

$ obd.send '7DF#010C' auto_format=True expect_response=True
```

The `obd.query` command is relatively simple - you need to provide some arbitrary name for the PID
(*MY_RPM*). The `header` argument is the header of the PID. `mode` is the diagnostic service that's
being queried and the `pid` argument is the exact value you want to query. If you compare the
command to what was presented above, you will find many of the bytes are overlapping.

The `obd.send` command does exactly the same, but in a different format. You must specify the full
PID to be sent in a string. Note that the length of the body is omitted. If the `auto_format`
argument is set to `True` it will automatically calculate the length byte and prepend it to the
body. You can also skip this argument and add the length byte and empty bytes yourself. The
`expect_response` argument will make sure that you receive a response back from the vehicle, if one
was provided. If you skip adding the `expect_response` argument, you will only send the PID on the
[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus.

## Creating a PID Logger
Let's now create a PID Logger for your vehicle. Firstly, we will create the PID itself, so that it
is present in your Library. Next, we will use the PID from the Library to create a PID for your
[AutoPi](https://www.autopi.io) device.

### Creating the PID
Let's create the RPM PID that we've examined in the previous section. Firstly, we will need to open
the OBD Library > My Library page. On that page, you will see a '+ Create' button. One
of the options should be PID - select that one. The following pop-out window should show up:

![Create a PID window](/img/cloud/obd_ii/create_pid_loggers/create_pid_window.jpg)

Let's go through the different fields that are available in this view:

**Name**: This is an arbitrary name you can give to your PID. This name will be used to create
data points for this PID logger, hence will be the name you use to create widgets on your Dashboard.

**Description**: Some description for your own readability.

**Mode and Code**: The mode (diagnostic service) and code together form the PID.

**Header**: This defines the header of the PID.

**Bytes**: This defines the expected length of the PID response.

**Enhanced PID**: This menu allows you to set some more specific details about how the PID should
be sent on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus and how the response should be found. See [Enhanced PID](#enhanced-pid) below.

**Formula**: This is where any parsing formulas can be inputted. Any valid python code can be
written in this field and will be evaluated during the execution of a PID Logger.

**Unit**: You can specify the measurement units in this field.

**Min and Max**: These two fields define what are the minimum and maximum values that this PID can
produce.

**Vehicle bus(es)**: In this dropdown menu, you are able to select the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) busses on which this PID
is valid.

What means for a PID to be valid in this case? It means that if this PID was sent on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus of
a vehicle, the vehicle would recognize it and return a valid response. So now the question is, how
can we test the PID? On the right hand side of the window, there is a "Run in Terminal" button which
allows you to run the PID if your device is online and plugged into your vehicle. Remember to have
your engine running while you execute the command.

Once you've confirmed that the PID returns valid data that you can use, you can click the Save
button and move on to the next section.

### Enhanced PID

![Enhanced PID drowdown](/img/cloud/obd_ii/create_pid_loggers/enhanced_pid_dropdown.png)

**Frames**: how many frames the message is expected to consist of

**Strict**: enforce frame and byte count

**CAN Extended Address**: CAN Extended Address byte. Note that this does not refer to 29-bit headers, 
but to an ELM327 specification. 

Before working with the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Flow Control Enhanced PID settings, it is highly recommended that you understand how the 
`can_flow_control_` prefixed parameters work on the obd.query command. This is explained in
[non-OBD2 queries](using_the_can_bus_commands.md#non-obd2-queries). The Enhanced PID
section essentially allows you to enrich your loggers with the same functionality. The filter and
mask correspond to the `can_flow_control_filter` parameter's 2 comma seperated values in that order. The
same applies to the Transmitter ID and Receiver ID.

### Creating the Logger
Now that we have a PID registered in our library, we can finally add a logger to our device which
will report data. Remember that in order to be able to register a PID as a logger on the device,
the device's vehicle bus needs to be added to the PID (look at vehicle busses in the last section).

:::tip
If you're using your [AutoPi](https://www.autopi.io) with an internal combustion engine vehicle, you should see some default
loggers setup for you already.
:::

Open up the Device > Loggers page. You will see a page with a '+ Create' button on the
right-hand side. Click on that button and select the PID option. A new window should show up that
looks like the following screenshot:

![Create PID Logger Window](/img/cloud/obd_ii/create_pid_loggers/create_new_logger.png)

Let's look through the fields available:

**PID**: This is the PID that you would like to use. Select it from the dropdown menu. If the PID
you want to assign doesn't appear in the list, remember that you need to add your vehicle's bus
to the supported vehicle busses when editing the PID itself.

**Interval**: How often should the PID be queried (in seconds)?

**Advanced**: If you are familiar with [AutoPi services](index.md), you might
recognize these options - the advanced options are going to be set on the pid_logger worker
responsible for querying the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus.
  - **Converter**: The converter that should be used to convert the response from the PID Logger.
  - **Filter**: The filter that should be used to identify if the response should be filtered out.
  Default is `alternating_readout` which filters out consecutive repeating values.
  - **Trigger**: The trigger function to be used if any events should be triggered based on this
  PID Logger. Default for RPM is `rpm_engine_event`.
  - **Returner**: Which returner should be used to store the data.

Once you save the PID Logger, you will see it appear in the Loggers page. Once the settings have
been synchronized to your device, your device will start sending PID requests on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus using
the provided parameters and you should start receiving data.

If for some reason, you aren't getting any data back from the logger, you can take a look at the
log files for some clues about what's going wrong. Take a look [here](/developer_guides/autopi_logs.md) for
more information on how to view those logs.

You can also take a look at the obd_manager workers(Device > Services > obd_manager > Workers).
There, you can notice that a new worker was created: pid_logger_10sec. If you view that worker
you'll see that the parameters setup for the PID are also available there. We discourage you to
make changes directly on the worker, as the worker is auto-generated based on what parameters are
provided to the PID and the PID Logger. Instead, make the necessary changes on the PID and PID
Logger.

## Conclusion
In this guide we talked more in-depth about PIDs and PID Loggers. We setup a custom PID that was
then used to create a PID Logger and got a very small insight into the automated processes that
exist in the [AutoPi](https://www.autopi.io) ecosystem.

:::tip
However if you want to learn more about how to set up a widgets for your dashboard using a PID loggers, you can read more in this guide: [Adding widgets to your Dashboard](https://docs.autopi.io/getting_started/autopi_tmu_cm4/create-loggers-cm4/#step-4-link-your-loggers-to-your-dashboard). 
:::

---

## Debug Raw PID Queries

---

If you want to investigate the raw request and response messages of PID queries, keep reading. If
you are unsure of what a PID is you can start by reading
[this wikipedia page](https://en.wikipedia.org/wiki/OBD-II_PIDs).

First step is to enable debug logging on your [AutoPi](https://www.autopi.io) device:

* On [my.autopi.io](https://my.autopi.io) go to **Device > Advanced Settings**
* Next choose **System** and go to section **Logging** > **Level**
* Choose value `debug` and press *Save* (the minion process must be restarted for the change to
  take effect)

:::note
Debug log level or below is only recommended when needed for debugging scenarios as it consumes a
lot of system resources. For normal operation use **warning** or **info** log level.
:::

Now that debug logging is enabled we are able to see all raw data transmitted and received between
the STN-chip (the chip responsible for communication with the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus of the vehicle) and the
Raspberry Pi.

When logged on to the system [via SSH](/developer_guides/how_to_ssh_to_your_device.md) it is possible to
follow the traffic live with the following shell command:

```bash
sudo tail -f /var/log/salt/minion | grep obd
```

In the example log output below we will look at the PID query for **speed**. In order to see this
log output on your device it is required to have a *PID Logger* setup for PID **speed**. Take a
look at the ['Community Library'](/cloud/obd_library/community_library.mdx)
guide on more information about how to set those up.

```
2020-05-19 11:16:56,874 [obd.obd          :269 ][DEBUG   ][2152] Querying command: 010D: Vehicle Speed
2020-05-19 11:16:56,875 [obd.interfaces.elm327:1027][DEBUG   ][2152] Write: '010D\r'
2020-05-19 11:16:56,909 [obd.interfaces.elm327:1082][DEBUG   ][2152] Read: b'7E8 03 41 0D 33 \r\r>'
2020-05-19 11:16:56,913 [salt.loaded.ext.engines.obd_manager:157 ][DEBUG   ][2152] Got query result: 51 kph
```

The raw request message sent from the Raspberry Pi to the STN/vehicle is:

```
2020-05-19 11:16:56,875 [obd.interfaces.elm327:1027][DEBUG   ][2152] Write: '010D\r'
```

And the raw response message sent from the STN/vehicle to the Raspberry Pi is:

```
2020-05-19 11:16:56,909 [obd.interfaces.elm327:1082][DEBUG   ][2152] Read: b'7E8 03 41 0D 33 \r\r>'
```

If a PID is queried that is not supported by the vehicle a `NO DATA` response is found instead.

---

## Introduction(3)

---

:::caution
Working with the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus is on your own risk. Playback and sending commands to the vehicle can be
used to control functions in the vehicle affecting the behavior of the vehicle. We recommend that
you **NEVER** do testing on a vehicle in motion and that you have the parking brake enabled while you
test.
:::

Most, if not all, vehicles have an OBD-II port. It is a port that allows technicians to communicate
with the vehicle, diagnose problems and so on. Using this port with the [AutoPi](https://www.autopi.io) you are able to get
real time data from the vehicle and display that data on your [Cloud](https://www.autopi.io/software-platform/cloud-management) dashboard. In this guide, we
will explore the basics of OBD-II communication: we will explore the two main ways vehicles
communicate on their [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus and in further guides we will talk about how they can be used to
log data (create the so-called loggers) through an [AutoPi](https://www.autopi.io) device.

## PIDs (Parameter IDs)
Parameter IDs or PIDs are specific codes that can be used to request data from the vehicle. An
external device (usually known as external test equipment device) can send a PID request on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro)
bus and an ECU (Electronic Control Unit) in the vehicle will send a PID response containing the
data that was requested in hexadecimal format. Here is an example PID request:

```
7DF # 02 01 0C 00 00 00 00 00
```

This PID, when sent to the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus of a vehicle that implements the OBD-II standard, will request
the current RPM value (Revolutions Per Minute). We won't spend time trying to completely understand
what this PID means, that is done in one of the following guides.

However, the general structure of a PID is the following. There is a header that defines who sent
the PID. The hashtag symbol (#) separates the header from the payload. The payload holds data that
is to be interpreted by the receiver of this PID request.

:::tip
The OBD-II standard is followed strictly only by vehicles that have an internal combustion engine
(ICE vehicles). Some ICE vehicles might have some extended functionality on top of the standard
defaults.

On the other hand, hybrid and electric vehicles don't always follow that standard. In fact, in our
experience those types of vehicles have an entirely different set of PIDs available. This means
that it is much more difficult to find out how to communicate on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus of a non-ICE vehicle
as they are usually different than what the OBD-II standard defines.
:::

After the PID has been sent on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus, an ECU on the vehicle will see the request and respond
with another PID:

```
# request, same as above
7DF # 02 01 0C 00 00 00 00 00

# response from ECU
7E8 # 04 41 0C 0F A0 00 00 00
```

The response will hold the information that was requested - the current RPM value. If we take a
look at the 4th and 5th bytes of the response body (`0F A0`), convert them to decimal values and
follow the formula `VALUE / 4` we will find out that the current RPM is 1000.

Each PID has to be interpreted differently. Some PIDs have formulas, others just need to be
converted from hex form to decimal. Now, let's move on to explaining the other way vehicles
communicate on their [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) busses.

## [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Messages and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Signals
[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages look very similar to how PIDs are represented. They also have a header (also known as
identifier) and a payload (body) separated by a hash sign. However, the difference between [CAN](https://www.autopi.io/hardware/autopi-canfd-pro)
messages and PIDs is that [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages are continuously sent on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus of a vehicle without
the need to make a specific request.

The body of a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message is constructed from the so-called [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals. A simple way to understand
[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals is by looking at an example [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message:

```
256 # 94 19 00 30 00 92 00 C7
```

As you can see, it is not much different than the PID presented above. However, this is a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro)
message and so the structure is different - for example, the first byte of a PID usually tells the
receiver how long the response body is, while for [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages that is not the case. Instead, there
is a DBC file, usually created by the manufacturers of the vehicle, that defines the structure of
[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals. We will take a look at those in a different guide.

## Loggers for Your Device

With your [AutoPi](https://www.autopi.io) device you are able to setup loggers that will communicate on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus and extract data for you to view on demand in the [Cloud](https://www.autopi.io/software-platform/cloud-management)'s dashboard.
You can setup loggers with PIDs or with [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages, depending on what your vehicle's type of communication is.

In the following couple of guides we will explore how you can create [PID Loggers](/cloud/obd-ii/create_pid_loggers.md)
and [CAN Signal Loggers](/cloud/obd-ii/create_can_signal_loggers.md).

## Conclusion
To finalize this introduction, we now know there are two major types of communication that can
happen on a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus - there's the PIDs and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages. PIDs are less chatty on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus, they follow the
request-response model. The ECUs in a vehicle will only report data if they are asked about it.

On the other hand, we also have vehicles that communicate with [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages. The ECUs in those
types of vehicles will continuously communicate on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus, reporting the latest available data.
This makes the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus of vehicles that communicate in this manner much more chatty, usually
dumping large amounts of data at a time.

---

## Log Raw CAN Messages

---

It is possible to listen for raw [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) data on the OBD port. There are a couple of
ways that this can be accomplished - a slower python implementation and a faster, C implementation.
In this guide we will explore these two options and show the differences between the two. Later on
we will also explore how you can make sense of this raw data after it has been recorded.

It is important to note that the monitoring tools can only be used as a part of an
[OBD service](/core/services/obd_manager.md) workflow. We won't get into details about how
you can create a service worker in this guide, however we do have the
[Create Service Workers](/cloud/device_management/services/create_custom_workers.md) guide which you can take a look at
for more details on how to create a worker and setup its workflow.

## Reading Raw [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Data

Firstly, we will explore how to read the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages that are visible on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. These
messages will be raw, meaning that they will simply be binary data that is structured in a
specific way. Later on we will also explore how we can make sense of this raw [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) data by
transforming it into more readable format using DBC files that can automatically be generated
for your vehicle.

### `obd.monitor`
The first and simplest way to monitor [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) data is with the
[`obd.monitor`](/core/services/core-services-obd-manager/#monitor) handler.
This handler will continuously listen on the OBD port looking for any data. This data
will then be transported down the workflow and there you will be able to use the different
hooks to transform the data and finally return the data to the [Cloud](https://www.autopi.io/software-platform/cloud-management), or save it to a file.

For greater performance read on to the `obd.export` handler. The image below shows an example
setup for an `obd.monitor` worker.

![obd_monitor_worker](/img/cloud/obd_ii/log_raw_can_messages/obd_monitor_worker.png)

### `obd.export`
[`obd.export`](/core/services/core-services-obd-manager/#export) is basically
`obd.monitor` on steroids. It is much faster than it's python counterpart and doesn't clog up the
[AutoPi](https://www.autopi.io)'s resources as much. It starts up a separate process that does the monitoring,
instead of running as a part of the salt-minion process.

This however means that the external process will have to attach to the OBD serial port
(`/dev/serial0`), which means that it won't be possible to use `obd` commands to read [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) data.
This is because the `obd.export` handler needs to be sure to catch all [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages and it won't
release the lock on the device.

This handler is also a bit different than other handlers, as it does not pass any meaningful
data down the workflow, instead it saves the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages to external files, which can then be
read by `obd.import`. The files are located in `/opt/autopi/obd/export/protocol_N` where `N` is
the protocol number for your vehicle. In that directory you will be able to see a number of log
files which contain the raw data that has been recorded by the handler. An example setup for a
workflow can be seen below.

![obd_export_worker](/img/cloud/obd_ii/log_raw_can_messages/obd_export_worker.png)

### `obd.import`
In order to actually be able to use the recorded data by `obd.export` within the [AutoPi](https://www.autopi.io) Core system,
we need to somehow import it. This is where
[`obd.import`](/core/services/core-services-obd-manager/#import) comes in -
it reads the data that was written to the log files by `obd.export` and passes it down the workflow.
It is simply a workflow enabler, meaning that after you read the data, you can transform it in any
way you'd like, execute any triggers and use a returner to save the data on the [Cloud](https://www.autopi.io/software-platform/cloud-management) or a local
file, just like with `obd.monitor`.

![obd_import_worker](/img/cloud/obd_ii/log_raw_can_messages/obd_import_worker.png)

## Making Sense of Raw [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Data

A key converter that can be used in the workflows described above is the
[CAN converter](/core/services/core-services-obd-manager/#can). It is able
to read the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) database file that you have for your vehicle's protocol and transform the binary
data that has been passed to it into a more sensible format. Both `obd.monitor` and `obd.import`
use the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) converter in the workflows to sanitize the data.

It is important to note however, that the DBC ([CAN](https://www.autopi.io/hardware/autopi-canfd-pro) database) file would only be available if you have
setup [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) loggers for your device. In the [AutoPi Cloud](https://my.autopi.io) navigate to 
Device > Loggers where you'll be able to see all the loggers you currently have. They need to
be of type [CAN](https://www.autopi.io/hardware/autopi-canfd-pro). There are a few guides that you can take a look at to get them up an running:

1. [How to setup power cycle for an electric vehicle](/getting_started/electric_vehicles/power-cycle-for-electric-vehicles/)

2. [How to import custom DBC files](/cloud/obd_library/car-explorer-library-manual/#importing-library-items-from-files)

---

## Using the CAN Bus Commands

---

:::caution
Working with the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus is on your own risk. Playback and sending commands to the vehicle can be
used to control functions in the vehicle affecting the behavior of the vehicle. We recommend that
you NEVER do testing on a vehicle in motion and that you have the parking brake enabled while you
test.
:::

In this guide, we will explore how you can communicate and interact with your vehicle's [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus.
Typically, there are two types of [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) busses.

One type responds to requests for data, that is to say, it almost acts like an HTTP server - it
receives a request for a specific data point (let's say speed or RPM) and it sends the requested
data back. This type of [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus is usually handled with PIDs.

The second type sends all the vehicle's data on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. This means that there is going to be
large amounts of data being streamed. We call this type of data [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Messages. Within those [CAN](https://www.autopi.io/hardware/autopi-canfd-pro)
messages are the so-called [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals. Each signal usually represents a specific data point, like
speed or RPM.

##  Sending PID's

Let's start off with the [`obd.query`](/core/commands/core-commands-obd/#obdquery) command. This command is
used to query the first type of [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) busses. Let's take a look at an example:

```console
obd.query test mode=01 pid=0C
```

:::note
You may need to add the ``force=True`` parameter to make sure the ECU in the vehicle accepts the
command. 
:::

This command can be run from [my.autopi.io](https:/my.autopi.io) or
[local.autopi.io](http://local.auotpi.io)'s web consoles. Let's try to explain each element of the
command. Firstly, `obd.query` - that is simply the command that we're attempting to execute. Next is
`test`. This is the name that the PID will use. It makes no difference to the comand's execution
what the name is going to be, but if you end up setting up a logger, the name will be used to save
that data on your account, so you can later reference it using the name to create a widget.

Next, there is the `mode=01` and `pid=0C` pieces of the puzzle. These are the specifications of
which data point you'd like to query for. In this case, we are asking the ECU of the vehicle to
respond with the current RPM. You can see a full list of standard PID's
[here](https://en.wikipedia.org/wiki/OBD-II_PIDs). Your vehicle may be able to support more or less
PID's than shown on Wikipedia. 

:::tip
If you'd like to run this command directly
from the device (through [SSH](/developer_guides/how_to_ssh_to_your_device.md) or similar), you will need to
prepend the `autopi` keyword, like so:

```console
autopi obd.query test mode=01 pid=0C
```
:::

## The [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Interface
The CAN interface is somewhat different than just sending standard PID's. It relies more on
parcing the full data stream on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. This is far more advanced, but it also opens up to a
whole new level of fun. 

### Setting the Protocol

The [AutoPi](https://www.autopi.io) is able to support a wide range of protocols. When you insert it into your vehicle it
will try to autodetect the protocol used by the vehicle. It is not always going to be the case that
the same protocol is used for all [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) traffic. In fact, [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) traffic may flow on more than one
protocol in your vehicle. Switching the protocol on the [AutoPi](https://www.autopi.io) makes it listen for traffic on
different electrical pins. You can check the current protocol settings using this command:

```
obd.protocol
```

This will give you a list of all the protocols you can set. Changing the protocol can be done with
this command:

```
obd.protocol set=<num>
```

Where `<num>` is the protocol number.

### Dumping/Reading Data From the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus

The new interface opens up for dumping data from the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus on the protocol selected. This can be
done using the [`obd.dump`](/core/commands/core-commands-obd/#obddump) command. Using the command is very easy:

```
obd.dump duration=5
```

Optional parameters:
* `duration=<seconds>`: How many seconds to record data. Default is `2` seconds.
* `file=<path>`: Write data to a file instead of displaying it on the screen.

This will dump a list of messages recorded within 5 seconds of starting the execution of the
command. Those messages might not make much sense at first glance, but that's okay. Usually, DBC
files are used to parse those messages into human readable data.

### Playback of a Recorded File

A file recorded with the ``obd.dump`` command can be played/replayed to the vehicle using the
[`obd.play`](/core/commands/core-commands-obd/#obdplay) command. Here's an example usage:

```
obd.play file=<path>
```

The will playback the entire file on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. 

Optional parameters:
* `slice=<T|B>`: Slice the list of messages before sending on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. Based one the divide
  and conquer algorithm. Multiple slice characters can be specified in continuation of each other.
  * `T`: Top half of remaining result.
  * `B`: Bottom half of remaining result.
* `filter=<expression>`: Filter out messages before sending on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. Multiple filters can
  be specified if separated using comma characters.
  * `+[id][#][data]`: Include only messages matching string.
  * `-[id][#][data]`: Exclude messages matching string.
  * `+duplicate`: Include only messages where duplicates exist.
  * `-duplicate`: Exclude messages where duplicates exist.
  * `+mutate`: Include only messages where data mutates.
  * `-mutate`: Exclude messages where data mutates.
* `group=<id|msg>`: How to group the result of sent messages. This only affects the display
  values returned from this command. Default is `id`.
* `test=<true|false>`: Run command in test-only (dry-run) mode. No data will be sent on [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus.
  Default is `false`.

All the filter parameters can be used to find the specific commands that you are seeking. With
filters you can remove data that you know is not relevant for finding your specific command (like
data that appears a lot). With the slice parameter you can use the "divide and conquer" technique
to find the specific command. 

### Sending a Single Message

The `obd.dump` and the `obd.play` commands is typically used for finding a single specific
command you want to send to the car. This can be lock/unlock or something else controlling your
vehicle. 

When you have the specific command, you can send it directly using the
[`obd.send`](/core/commands/core-commands-obd/#obdsend) command. Here's an example:

```
obd.send 2101#280000000003E800 expect_response=True auto_format=True
```

The first part before the # is the ECU number (the header) and the last part is the data payload.
You may need to remove the `expect_response` if the ECU doesn't respond on the message you've
send.

### Non-OBD2 Queries
Sometimes a vehicle supports non-OBD-2 queries. An example of this is manufacturer proprietary
protocols. When this is the case, you need to enrich the queries with [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Flow Control parameters.

Let's look at an example of a proprietary query, where the request data is `1AA # 02 00 01 00 00 00 00 00`, 
and the response is `2AA # 02 XX XX 00 00 00 00 00`, where the `XX` bytes are the data bytes. For 
the sake of having the example complete, let's assume that this queries for the speed in kph. If 
we try to do this query as we might with any other OBD-2 PID, we won't get a response. This is 
because the device does not know how the message looks like. This might seem pointless if these 
request-response messages are the only traffic on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus, however, imagine if there are hundreads
of [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) frames being sent on the bus every second. How is the device to know which [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) frame is the
response? We need to specify this manually.  

If you take a look at the [obd.query](/core/commands/core-commands-obd/#obdquery) command, you'll notice several
arguments dedicated to can flow control. The 2 relevant ones are **`can_flow_control_filter`** and
**`can_flow_control_id_pair`**. 

**`can_flow_control_filter`** - filters out all non-query related can frames from the traffic. Although you
might get an expected response without specifying this parameter, you should still add it. The format for
it is `can_flow_control_filter=<Pattern>,<Mask>`. In the current example, that would look like this:
`can_flow_control_filter=2AA,7FF`.

**`can_flow_control_id_pair`** - pairs the query request header (Transmitter ID) to the response header (Receiver ID)
in format `can_flow_control_id_pair=<Transmitter ID>,<Receiver ID>`. In this example, it would be: `can_flow_control_id_pair=1AA,2AA`.

All this taken into account, the command would look like this:
```
$ obd.query PROPRIETARY_SPEED header=1AA mode=00 pid=01 can_flow_control_filter=2AA,7FF can_flow_control_id_pair=1AA,2AA force=True
_stamp: '2023-08-28T12:22:31.253543'
_type: proprietary_speed
value: 2aa0200430000000000
```

Next, we'll need to extract the speed data with a formula. In this case, all the data bytes correspond to
the data we're looking for, so we can use the simple formula of `bytes_to_int(message.data)`:

```
$ obd.query PROPRIETARY_SPEED header=1AA mode=00 pid=01 can_flow_control_filter=2AA,7FF can_flow_control_id_pair=1AA,2AA force=True formula='bytes_to_int(message.data)'
_stamp: '2023-08-28T12:22:35.052518'
_type: proprietary_speed
value: 67
```

:::tip
There are a few quirks to keep in mind when working with these and with [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus in general:
- As long as the vehicle's bus is autodetected, the `obd.query` command will try to verify that the
protocol is still valid by sending a known valid OBD-2 message onto the bus and waiting for a reply. If
the vehicle does not support standard OBD-2, this will cause the command to fail. To prevent this, either
ensure the vehicle supports OBD-2, or create a new bus, which does not have the 'autodetected' flag.
- The selected protocol's header length must match the header length of the sent/received messages. For
example, you can not specify `protocol=7`, which has a 29-bit header length, and then query for an 11-bit
message. You will not get the expected result. Keep in mind that there will always be a protocol selected,
even when one is not specified in the command. When the command is being run through the logger, this will
be the `default` protocol.
:::

:::note
For those closely familiar with [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) flow control, it might seem confusing that these parameters have
the can\_flow\_control\_ prefix, as [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) flow control usually refers to multi-frame messages. The naming is
related to how older versions of the [AutoPi](https://www.autopi.io) communicated on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus.
:::

## Using the [Cloud](https://www.autopi.io/software-platform/cloud-management) [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Analyzer
All the above commands are how the interface to the vehicle works. We have combined all of this in
an interactive [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Analyzer, which is accessible from the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) in
Device > [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Analyzer. If you don't see that menu link, you need to make sure that you've
installed the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Analyzer add-on from the Add-ons page.

The [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Analyzer makes working with your car much simpler. To find your specific command follow
these steps:

1. Configure your [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus interface. On the account page under "Vehicles" you can autodetect the
most common [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus. If you need to work with a special [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus, make sure you have the right baud
rate configured.

2. Select the Bus you want to use and press record. The device will make a "beep" sound when the
recording begins and another one when the recording ends. Make sure that the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) command you want
to record is happening between the two sounds (like door unlock or window control).

3. The recording is now stored on the device and you can play it back immediately using the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro)
player on the right-hand side of the screen.

4. You will see that a lot of data is returned from the bus, so to find the specific command for
your function, we recommend using the filters on the right-hand side. Typically, a lot of the data
is repetetive, so you can start out by removing all the duplicates.

5. With the filters, narrow down the results to as few as possible. Then you can replay the
commands one by one and see if you can find the command controlling the function you are looking
for.

6. When you have found your command you can always resend it by using the `obd.send` command
described above.

---

## Community Library

---

This guide will give an overview of the OBD My Library feature, which is a way to discover the
available PID's in your car, both hidden and public/default OBD-II, and sharing them with the
community.

We will go over the following topics in this guide.
* How and when the car reports the supported PIDS.
* How to find PID's in the Community Library.
* How to add a PID to your library.
* How to create (and share) proprietary PID's.
* Troubleshooting if no PID's are reported from the device.

![Community library overview](/img/cloud/obd_library/community_library/updated_overview.png) 

## How And When The Device Reports The Supported PID's
When the device connects to the server, it will check the for the following:

* Is it updated to the most recent version?
* If the active vehicle has no autodetected busses associated.
* OR if the autodetected bus has no PID's associated.
* That the engine has been started since the update. It will only be able to detect the supported
  commands when it is connected to the bus and the engine is running.

You can see what busses are registered in Accounts > Devices > Select Device > Vehicles Editor > [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Busses.

Then the device will know to report the supported PID's. After the device has reported to the [Cloud](https://www.autopi.io/software-platform/cloud-management)
with the supported PID's, they will show up in the "My Library" tab in the "OBD Library" section.

![My library overview](/img/cloud/obd_library/community_library/my_library_overview.png) 

## How to Find And Use PID's
You can also browse the community library, where all PID's are available and searchable.
The filters will default to the model, make and year of the vehicle configured on your active
device. The PID's that are shown here are all the PID's that are reported as supported by the makes
and models of the [AutoPi](https://www.autopi.io) users. Please note that the number of PID's visible here will go up once
devices are updated and reports the supported PID's or if people create and share proprietary PID's.

If you change the filter to only include the type "Proprietary", it will only show the PID's that
are created by other [AutoPi](https://www.autopi.io) users, and who has chosen to share it with the community. In time these
proprietary PID's are very likely where you will find the most interesting PID's for your vehicle.

## How to Add a PID to Your Library
When you find a PID you'd like to try, you can view it, and in the right side, there is a preview
of the command needed to execute the PID on your car. But the PID may be associated to a specific
bus that your car does not have, so unless you are filtering on your specific car make and model,
it will most likely not work, at least not without some changes.

By clicking the **Add to library** button, the PID will be associated to the bus on your active
vehicle. If no bus exists that matches the bus info in the selected PID, it will be created. As
mentioned above, unless you filter on your specific make and model, even if the PID is supported by
your vehicle, you may need to do some fiddling before it will work, which can be done by running
the PID directly in the terminal. Keep in mind that the engine may need to be running for it to
respond to PID's.

Now the PID should be available in **My Library**.

After adding the PID, it is available in the **Logging** section, so you can now set up a logger
that runs every N interval, and logs data by executing the specific PID.

![Creating a new logger](/img/cloud/obd_library/community_library/create_new_pid_logger.png)

## How to Create And Share Proprietary PID's
To create a new PID, click the "Create" button in "My Library".

![Creating a PID](/img/cloud/obd_library/library/create_new_pid_rpm.png)

You will now need to fill out the following fields:

**Name**  
A slug with the name of your PID - it must be unique as it is used by the device when sending the
logged value to the [Cloud](https://www.autopi.io/software-platform/cloud-management) (if used in a logger).

**Description**  
If you want to share the PID, a proper description is really nice, and if not, it's still very
useful to describe or maybe add a link to where the PID originates from.

**Mode and Code**  
These two values together is the PID.

**Header**  
The default *7DF* value means a Request message. The default should be used unless you need
another for some proprietary magic.

**Bytes**  
This is the expected length of the response.

**Formula**  
The formula is executed on the device, and takes a byte array from one or more response messages,
and translates it to the actual value, like temperature, speed etc.

You may notice that none of the standard PID's has a formula specified. This is because all the
default PID's are identified by their name, and the code that translates the byte response to a
value, is already embedded in the [library (py-obd)](https://github.com/autopi-io/py-obd) we use
for communicating with the car. This is only the case for the standard PIDS.

The formula is plain python with some added helper functions:
* bytes_to_int
* bytes_to_hex
* twos_comp

[More info here](https://github.com/autopi-io/py-obd/blob/master/obd/utils.py#L109).
So to convert a temperature response one would write the following formula:

```
bytes_to_int(message.data[2:])-40
```

**NOTE: Remember to use the data attribute on the message object**
The above example is the short "formula" way to write the following
[decoder function](https://github.com/autopi-io/py-obd/blob/master/obd/decoders.py#L110)
You can also find more examples in the above link.

:::tip
For prototyping, you can execute the PID on your device by using the terminal, then copy the byte
response into a python terminal, insert the above helper functions, to be able to test the parsing
directly in the terminal.
:::

**Unit, Min and Max**  
Select a unit that matches your data or write your own.
Like the name, this unit is used when the device stores the response value of the PID, for easier
parsing and displaying of the value in the dashboard widgets.
Min and max are also used when storing and displaying the data.

**Bus**  
To use a PID, you need to associate it to one of the busses on your vehicle. It may be as simple as
associating it to the auto detected one, but you may also want to create a custom one. This can be
done in the Accounts > Devices > Select Device > Vehicles Editor > [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Busses. You don't have to 
associate the PID with a bus straight away.

Now click save, and your new PID is created, and can be found in **My Library**.
If you want to share the PID, it needs to be associated to at least one bus, when you have done
that, and saved the PID, you can now click the **Share with community**, after which the PID will
be discoverable in the **Community Library**, and other users can find it. You can also verify that
it looks correct, and has the right make and model by searching for the PID.

## Troubleshooting if No PID's are Visible
If your PID's aren't listed in **My Library**, check the following things.
* That your device is updated to the most recent version.
* That the device has been online since the update.
* That the engine has been running for a little while since the update.
* That the vehicle associated to your device, has the correct make and model specified.
* That you have no errors in the log on the device.

See [this guide](/developer_guides/autopi_logs.md) if you are unsure how to get the logs from the device.

---

## My Library

---

In this page we go through the Library section of our Cloud. Below is a screenshot of an example
Library that is already filled with some PIDs and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages. Open the screenshot in a
new tab to get a better overview of the whole page.

![Full library screenshot](/img/cloud/obd_library/library/updated/library_overview.png)

We will start off this guide by going through some of the basic actions that you can do in the
library page, including a section on how to use the Community Library to find new PIDs and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro)
messages. Then, we will move on to the process of creating a PID, testing it out and sharing it
with the community. We'll repeat the process but for [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages and their [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals instead.
Lastly, we will show you some quick steps for importing a DBC file.

## Basic Actions

There are a few buttons that will allow you to accomplish different tasks in the library. The main
element is the table filled with PIDs and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages. You are able to delete a single entry in
the table by clicking on the trash icon to the far right of each item in the list. You can also
select multiple items and then execute a specific action from the '*Actions*' dropdown menu on the
bottom-right of the page. You are also able to filter the items that are shown using the filters
at the top of the page. You are also able to copy PIDs and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages from the community library.
You are also able to create new PIDs and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages and can also import external DBC files into
your library which you can later on share with the rest of the community. We are going to review
these actions in the following sections.

:::tip
If you're unsure of the difference between *PIDs* and *CAN message signals*, you can take a look
at our [OBD-II introduction](/cloud/obd-ii/index.md) guide, which goes into more details about
that.
:::

## Community Library

The community library tab will show you a list of PIDs or [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages available for the vehicle
that's assigned to your currently active device. If there is no vehicle assigned at the moment, no
filters will be applied, so you will need to add them manually for the vehicle you're interested in.

:::caution
Only the [my.autopi.io](https://my.autopi.io) environment has a populated community library. If you
are a business customer, you won't see any of the community shared library on your dedicated
server.
:::

![Community library screenshot](/img/cloud/obd_library/community_library/updated_overview.png)

:::note
There is a slight difference between the two types - *OBD-II PID* and *Proprietary PID*. Items that
are created with the *OBD-II PID* type are PIDs that are a part of the OBD-II standard which is
used by most internal combustion engine (ICE) vehicles. On the other hand *Proprietary PID*s are
PIDs that are usually used by vehicle's that don't follow the OBD-II standard, for example electric
vehicles or more advanced ICE vehicles.
:::

After applying the filters for the vehicle you're interested in, you will be presented with a list
of search results. You can browse through them and if you find one that you would like to use or
experiment with you can add it to your library. By clicking on the item you're interested in, a
pop-out window similar to the one below will show up:

![Community library view window](/img/cloud/obd_library/library/viewing_pid_absolute_load.png)

On that window, you can see details such as the exact parameters for the PID like the **header**,
**mode** and PID **code** that it uses, the **formula** that parses the raw bytes into human
readable format and more (for a description of these fields, read the following section). Finally,
if you'd like to use this PID, you can click on the green '*Add to library*' button and a copy of
this PID will show up in your personal library. From there, you can edit it if it needs to be
changed.

## Creating PIDs

Let's now go through the process of creating a PID in your own library. We will use the standard
OBD-II RPM PID as an example. Below is the raw PID that would be send on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus of a vehicle:

```
7DF # 02 01 0C 00 00 00 00 00
```

Let's try to dissect this PID a little bit. Just as a reminder, PIDs are sent in hexadecimal format.
The most noticeable element is the hash sign (`#`). This sign separates the PID's header from the
PID's body. The header in this case is `7DF`. Next, the first byte of the PID body shows the data
length, in this case, we only have two bytes that need to be read, so the body length is `02`. Next,
the mode is `01` and the code is `0C`. These two values are predefined by the OBD-II standard. More
detailed information can be found in [this guide](/cloud/obd-ii/create_pid_loggers.md).

Now, let's shift our focus on the next task - we need to create the PID in the system. Firstly, we
will need to go back to our own library and find the '*+ Create*' button (which should be located
at the top-right section of the page). Clicking on that button will show a dropdown menu with two
options, PID and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) - select the PID one. This will bring up the following window (the fields in
the screenshot are already filled up, so that it's easier for me to describe them after):

![Creating a PID](/img/cloud/obd_library/library/create_new_pid_rpm.png)

Let's go through the fields that are available and how to fit the raw PID we see above into the
PID form.

>**Name:** Short name of the PID that's being created.
>
>**Description:** Optional description of the PID. This can be very useful if plan to share the PID
>with the rest of the community.
>
>**Mode:** This is the mode that the PID is working in. We will type `01` in this field as described
>above.
>
>**Code:** The hexadecimal representation of the requested PID. In this case, the code is `0C` and
>so we will specify that.
>
>**Header:** The header used to request the PID. `7DF` is the standard header value for external
>OBD-II test equipment, so this is the one we'll use.
>
>**Bytes:** This is the expected length of the response. If strict mode is enabled (can be selected
>by opening the Extended PID options) the device will ensure that the response is exactly 8 bytes
>long and if it isn't it'll raise an exception.
>
>**Formula:** This is the formula that will be used to attempt to parse the raw response from the
>vehicle into (usually) numerical data.
>
>**Unit:** The unit of the data (more examples: km/h, percentage, liters, etc.)
>
>**Min:** The minimum value that this PID can return.
>
>**Max:** The maximum value that this PID can return.
>
>**Vehicle Bus(es):** A list of [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) busses that support this PID. If a vehicle is able to recognize
>this PID and return data back, it is recommended that you add the bus of that vehicle to the list.

### Testing The PID
What does it mean for a PID to be supported by a vehicle? It means that if this PID was sent on the
[CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus of a vehicle, the vehicle would recognize it and return a valid response. So now the
question is, how can we test the PID? On the right hand side of the window, there is a '*Run in
Terminal*' button which allows you to run the PID if your device is online and plugged into your
vehicle. Remember to have your engine running while you execute the command. You are also able
to send a PID on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus using the [`obd.query`](/core/commands/obd.md#obdquery) and
[`obd.send`](/core/commands/obd.md#obdsend) [AutoPi](https://www.autopi.io) commands.

### Community Sharing
You're also able to share the PID after you've created it and assigned at least one vehicle bus.
Once you save the PID, you can re-open it and a new section will show up on the right-hand side
called '*Community Sharing*'. You need to select (tick) the '*Share with community*' checkbox.

## Creating [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Messages

Let's try to also create a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message in our Library. It is a bit different comparing it to
creating a PID because, as it is mentioned in the [OBD-II introduction guide](/cloud/obd-ii/index.md),
PIDs are a simple request sent on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus, that the vehicle accepts and then returns data
specific for the PID requested. [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages, on the other hand, are continuously broadcasted on
the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus and do not require any requests to be made. However, to be able to make any sense of
the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages, we need to specify which bytes within a message corresponds to which data point
from the vehicle.

To start creating a new [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message, you will need to click the '*+ Create*' button on the top-right
section of the page. From the dropdown that shows up from clicking on the button, select [CAN](https://www.autopi.io/hardware/autopi-canfd-pro). This
will bring up the following window (again, it is pre-filled for the purposes of this guide):

![Creating a CAN message](/img/cloud/obd_library/library/editing_can_message.png)

>**Name:** Short name of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message that's being created.
>
>**Description:** An optional description for this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message.
>
>**Header:** The hexadecimal representation of the header that this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message is recognized by.
>
>**Bytes:** How long is the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message?
>
>**Sender:** The name of the transmitting node of this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message - usually defined inside a DBC
>file, but can be any short string.
>
>**CAN Signals:** This is a list of [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals that can be found inside a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message. Each [CAN](https://www.autopi.io/hardware/autopi-canfd-pro)
>signal has the same form fields:
>
>* **Name:** Short name of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal.
>
>* **Description:** An optional description of this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal.
>
>* **Endian:** The endianness of this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal - which is the most significant byte. 
>
>* **Sign:** Defines if the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal should be treated as a signed or unsigned number.
>
>* **Start:** Defines the starting bit of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal.
>
>* **Length:** How long the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal is.
>
>* **Factor:** Used to calculate the real value off of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal. Formula: `VALUE = (RAW_VALUE * FACTOR) + OFFSET`
>
>* **Offset:** Used to calculate the real value off of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal.
>
>* **Unit:** The unit of the value returned.
>
>* **Min:** The minimum value possible for this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal.
>
>* **Max:** The maximum value possible for this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal.
>
>* **Receivers:** The name of the receiving node of this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message - usually defined inside a DBC
>file, but can be any short string.
>
>**Vehicle bus(es):** A list of [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) busses that support this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message. If a vehicle continuously
>writes this [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message on its [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus, it is recommended that you add the bus of that vehicle to
>the list.

### Testing the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Message

It is a bit more difficult to test [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages. You will need to create [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Signal Loggers for your
device in order to see if they are able to generate the data you're looking for. Another option you
can try is to use the [`obd.dump`](/core/commands/obd.md#obddump) command to dump all [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) frames
recorded on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus and compare the frames received to the definitions that you've made - they
should match on the header at least.

### Community Sharing

The process of sharing a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message is exactly the same as the process for sharing a PID. After
you assign a bus to the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message, you will have the option to share it with the community on the
right-hand side of the Edit [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Message window. You will need to select (tick) the '*Share with
community* checkbox.

## Importing Library Items From Files
The Library supports importing both [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages and signals through DBC files, as well as PIDs through
JSON files. As an example, let's use this simple DBC file:
```
VERSION "1.0"

BO_ 938 FRONT_LEFT: 4 IO
  SG_ LEFT_SEAT_TEMP: 0|8@1+ (1,0) [0|0] "c" ECU1
  SG_ LEFT_BACK_TEMP: 8|16@1+ (1,0) [0|0] "c" ECU1

BO_ 937 FRONT_RIGHT: 4 IO
  SG_ RIGHT_SEAT_TEMP: 0|8@1+ (1,0) [0|0] "c" ECU1
  SG_ RIGHT_BACK_TEMP: 8|16@1+ (1,0) [0|0] "c" ECU1

CM_ SG_ 1 LEFT_SEAT_TEMP "Temperature of the front left seat";
```

### First Import
When you first select a file for import, you will be presented with options looking like this:
  ![File options](/img/cloud/obd_library/library/file_options.png) 

Here you can select whether the file's contents are [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages & signals or PIDs. You can also set a
namespace, which will prefix all the imported items with the selected Name string. This can help when you need to
manage multiple files, which have conflicting signal or PID names. Once you've set these options, the file will be 
sent for validation. Once that's done, you'll be able to review all the messages and signals that will be imported.
You can also ignore messages and signals, which you'd like to not be imported. For this example, we're ignoring the left
seat's temperature.

  ![Imported and validated messages](/img/cloud/obd_library/library/imported_messages.png) 
  ![Imported and validated signals](/img/cloud/obd_library/library/imported_signals.png) 

### Adding Signals to Existing Messages
Once you've selected what to create and what to ignore, click on the upload button and the messages will be created. If
you now try to import the same file with the same options, you'll see that front right seat, which we imported with all
its signals, is unchanged. Front left, however, is shown as changed, since we ignored one of its signals. Now we have the
option to update the Front Left message by creating the Left Seat Temperature signal.

  ![Library view](/img/cloud/obd_library/library/post_import_messages.png) 
  ![Library view](/img/cloud/obd_library/library/post_import_signals.png) 

### Updating Message and Signal Properties
To update a value, all you need to do is change it in the imported file and import it again with the same options. For this
example, we're changing the unit of the Right Seat Temperature from Celsius to Fahrenheit. 

```
Before: SG_ RIGHT_SEAT_TEMP: 0|8@1+ (1,0) [0|0] "c" ECU1
After:  SG_ RIGHT_SEAT_TEMP: 0|8@1+ (1,0) [0|0] "f" ECU1
```

After uploading the file and validating, the signal shows as changed and the changed property's new and old values can be seen.

  ![Library view](/img/cloud/obd_library/library/updating_a_signal.png) 

:::note
Setting a message's Option to 'Ignore' will force 'Ignore' to all its child signals.
:::

### Deleting Signals
You can delete signals by removing them from the DBC file, then importing the file. In this example, we're deleting the Right Seat's
Backrest's Temperature. 
```
Before:
BO_ 937 FRONT_RIGHT: 4 IO
  SG_ RIGHT_SEAT_TEMP: 0|8@1+ (1,0) [0|0] "f" ECU1
  SG_ RIGHT_BACK_TEMP: 8|16@1+ (1,0) [0|0] "c" ECU1

After:
BO_ 937 FRONT_RIGHT: 4 IO
  SG_ RIGHT_SEAT_TEMP: 0|8@1+ (1,0) [0|0] "f" ECU1
```

  ![Library view](/img/cloud/obd_library/library/deleting_a_signal.png) 

### Working With PIDs

Unlike [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages and signals, there's no industry standard file format for PIDs. Therefore, there's a custom JSON based format 
that you need to follow. This is an example PID JSON file:

```json
[
	{
		"fields": {
			"type": "PTY",
			"header": "700",
			"mode": "220",
			"code": "0103",
			"bytes": null,
			"frames": null,
			"strict": false,
			"formula": "bytes_to_int(messages[0].data[-3:])",
			"unit": "km",
			"min": null,
			"max": null,
			"datatype": null,
			"parent": null,
			"name": "TractorLighting",
			"description": "Tractor's light emission",
			"hash": "",
			"initial_hash": null,
			"can_extended_address": null,
			"can_flow_control": {
				"filter": {
					"pattern": "708",
					"mask": "7FF"
				},
				"id_pair": {
					"receiver_id": "700",
					"transmitter_id": "708"
				}
			},
			"can_messages": []
		}
	},
	{
		"fields": {
			"type": "PTY",
            ...
        }
	}
]
```

## Legacy Importer

  ![Library view](/img/cloud/obd_library/library/import_file_button.png) 

Depending on what version you are using, you might see multiple "Import" buttons in the library. This is
because there are 2 versions of the importer: the new and the legacy. The legacy importer was able to

DBC files describe the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) network traffic of a vehicle. It specifies what modules are within it,
what [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages they can send, the messages' signals and details about how to parse them. In this
section we are going to review how you can import these files in your Library, how to keep them up 
to date, how to improve their readability and how you can share them with the rest of the community.

1. Go to **OBD Library** > **My Library** and click on the Import button:
  ![Import button](/img/cloud/obd_library/library/updated/library_import.png) 
2. Select DBC from the dropdown menu that shows up and select the file from your filesystem.
3. A list of the imported CAN signals will show up in your library.
  ![Library view](/img/cloud/obd_library/library/updated/library_imported.png) 

## Adding Descriptions for Better Readability

Some signal names can be very self explanatory. However others might be harder to understand. You
can add descriptions to those messages to make it easier to recognize them in the future or for
other fellow users, if you decide to share those signals with the community.

To add a description for a signal, click on the signal you want to edit. A [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message editing
window (like the one from the previous section) will pop out. In this window you'll be able to see
the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message at the top with all [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals associated with it in a list below. The [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal
that you clicked on will be already expanded and highlighted in yellow.

![Editing a CAN message](/img/cloud/obd_library/library/editing_can_message.png)

Edit the description field of the signal and click Save. You can also associate that [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message
with a vehicle [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus. You should see the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal update with the new description.

---

## Acc

## `acc.connection`

Manages current connection.

**OPTIONAL ARGUMENTS**

  - **`close`** (bool): Close connection? Default value is `False`. 

**EXAMPLES**

  - `acc.connection`
  - `acc.connection close=True`

----
## `acc.context`

:::warning
**DEPRECATED**
Use 'manage context' instead.
:::
Gets current context.

----
## `acc.dump`

Dumps raw XYZ readings to screen or file.

**OPTIONAL ARGUMENTS**

  - **`duration`** (int): How many seconds to record data? Default value is `1`.
  - **`file`** (str): Write data to a file with the given name.
  - **`range`** (int): Maximum number of g-forces being measured. Default value is `8`.
  - **`rate`** (float): How many Hz (samples per second)? Default value is `12.5`.
  - **`decimals`** (int): How many decimals to calculate? Default value is `4`.
  - **`timestamp`** (bool): Add timestamp to each sample? Default value is `True`.
  - **`sound`** (bool): Play sound when starting and stopping recording? Default value is `True`.
  - **`interrupt_driven`** (bool): Await hardware data ready signal before reading a sample? Default value is `True`.

----
## `acc.help`

Shows this help information.

----
## `acc.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `acc.manage hook list`
  - `acc.manage hook call query_handler xyz`
  - `acc.manage worker list *`
  - `acc.manage worker show *`
  - `acc.manage worker start *`
  - `acc.manage worker pause *`
  - `acc.manage worker resume *`
  - `acc.manage worker kill *`
  - `acc.manage reactor list`
  - `acc.manage reactor show *`
  - `acc.manage run handler="query" args="[\"xyz\"]" returner="cloud"`

----
## `acc.query`

Queries a given accelerometer command.

For additional help run: `acc.query help`

**EXAMPLES**

  - `acc.query status`
  - `acc.query xyz`
  - `acc.query active value=False`
  - `acc.query range value=4`
  - `acc.query data_rate value=12.5`
  - `acc.query offset x=0.1 y=-0.1 z=0`

---

## Audio(Commands)

## `audio.aplay`

Play a given audio file using the `aplay` command.

**ARGUMENTS**

    - **`audio_file`** (str): Local path of the audio file to play.

**OPTIONAL ARGUMENTS**

  - **`duration`** (int): Interrupt playback after amount of seconds.

----
## `audio.espeak`

Speak a given text using the `espeak` command.

:::note
Unfortunately 'espeak' command is not always reliable - sometimes it fails for uncertain reasons.
:::

**ARGUMENTS**

  - **`text`** (str): Text to speak out.

**OPTIONAL ARGUMENTS**

  - **`volume`** (int): Set volumen of the playback. Default value is `100`.
  - **`language`** (str): The language to speak in. Default value is `en-gb`.
  - **`pitch`** (int): The pitch of the voice. Default value is `50`.
  - **`speed`** (int): Rate of speech. Default value is `175`.
  - **`word_gap`** (int): Time gap between words spoken. Default value is `10`.
  - **`timeout`** (int): Timeout in seconds of the command to finish. Default value is `10`.

----
## `audio.help`

Shows this help information.

----
## `audio.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `audio.manage hook list`
  - `audio.manage hook call query_handler play`
  - `audio.manage worker list *`
  - `audio.manage worker show *`
  - `audio.manage worker start *`
  - `audio.manage worker pause *`
  - `audio.manage worker resume *`
  - `audio.manage worker kill *`
  - `audio.manage reactor list`
  - `audio.manage reactor show *`
  - `audio.manage run handler="play" args="[\"sound.wav\"]"`

----
## `audio.play`

Plays a specific audio file.

**ARGUMENTS**

  - **`audio_file`** (str): Local path of the audio file to play.

**OPTIONAL ARGUMENTS**

  - **`force`** (bool): Force even though another playback is in progress? Default is `False`.
  - **`loops`** (int): How many repetitions of playback? Default is `0`.
  - **`volume`** (int): Set volumen of the playback.

----
## `audio.queue`

Queues an audio file.

**ARGUMENTS**

  - **`audio_file`** (str): Local path of the audio file to play.

----
## `audio.speak`

Alias for `audio.espeak`.

----
## `audio.stop`

Stops playback of the current audio.

----
## `audio.volume`

Set volumen of the playback.

**OPTIONAL ARGUMENTS**

  - **`value`** (int): The volume to set.

---

## Avrdude

## `avrdude.flash`

Flash hex file to MCU.

WARNING: Only use this command with caution as it can misconfigure the MCU and leave it in an unusable state.

**ARGUMENTS**

  - **`hex_file`** (str): Path of hex file.

**OPTIONAL ARGUMENTS**

  - **`part_id`** (str): Part ID. Default is `t88`.
  - **`prog_id`** (str): ID of programmer. Default is `autopi`.
  - **`raise_on_error`** (bool): Raise an error upon failure. Default is `True`.
  - **`no_write`** (bool): No actual write to MCU. Default is `True`.

----
## `avrdude.fuse`

Get or set fuse value of MCU.

WARNING: Only use this command with caution as it can misconfigure the MCU and leave it in an unusable state.

**ARGUMENTS**

  - **`name`** (str): Name of the fuse.

**OPTIONAL ARGUMENTS**

  - **`part_id`** (str): Part ID. Default is `t88`.
  - **`prog_id`** (str): ID of programmer. Default is `autopi`.
  - **`value`** (str): Fuse byte value to write.

----
## `avrdude.help`

Shows this help information.

---

## Ble

## `ble.context`

:::warning
**DEPRECATED**
Use 'manage context' instead.
:::
Gets current context.

----
## `ble.flash_firmware`

Flashes new firmware to the BlueNRG device.

----
## `ble.help`

Shows this help information.

----
## `ble.interface`

Manages the interface to the BlueNRG device.

----
## `ble.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `ble.manage hook list`
  - `ble.manage hook call query_handler ACI_HAL_GET_FW_BUILD_NUMBER`
  - `ble.manage worker list *`
  - `ble.manage worker show *`
  - `ble.manage worker start *`
  - `ble.manage worker pause *`
  - `ble.manage worker resume *`
  - `ble.manage worker kill *`
  - `ble.manage reactor list`
  - `ble.manage reactor show *`
  - `ble.manage run handler="query" args="[\"ACI_HAL_GET_FW_BUILD_NUMBER\"]"`

----
## `ble.mode`

Manages the low-level modes of the BlueNRG device.

----
## `ble.query`

Queries a given BlueNRG ACI command.

---

## Bluetooth(Commands)

## `bluetooth.help`

Shows this help information.

----
## `bluetooth.scan`

Return list of BLE devices in the proximity.

**OPTIONAL ARGUMENTS**

  - **`hci`** (int) Interface number for scan: Default is 0.
  - **`sensitivity`** (int): Default is -128 dbm.
  - **`timeout`** (int): Default is 4 seconds.
  - **`verbose`** (bool): Default is True.
  - **`sort_by`** (str): Default is `rssi`.

---

## Can

## `can.autodetect`

Attempts to autodetect the protocol.

----
## `can.connection`

Manages the current CAN connection.

**OPTIONAL ARGUMENTS**

  - **`autodetect`** (str): Attempt autodetection of the bus protocol. One or more of the following values can be specified; `passive`, `obd` and/or `j1939`.

----
## `can.dump`

Stores messages from the CAN bus to a file until a limit or duration is reached.

**ARGUMENTS**

  - **`file`** (str): Write data to a file with the given name. Supported file extensions are `.asc`, `.blf`, `.csv`, `.db` and `.log`.

**OPTIONAL ARGUMENTS**

  - **`duration`** (int): How many seconds to record data? Default value is `1`.
  - **`limit`** (int): The maximum number of messages to read.
  - **`receive_timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.
  - **`skip_error_frames`** (bool): Skip any reply message marked as an error frame. Default value is `False`.
  - **`keep_listening`** (bool): Continue listening for messages in the background? Default value is `False`.
  - **`buffer_size`** (int): The limit of messages that the internal queue can hold. If the value is less than or equal to zero, the queue size is infinite. Default value is `0`.

**OPTIONAL ARGUMENTS FOR ASC AND BLF FILES**

  - **`channel`** (int): The default value to use when a message does not have a channel set. Default value is `1`.

**OPTIONAL ARGUMENTS FOR CSV FILE**

  - **`append`** (bool): Append messages to an existing file where no header line is written or truncate and start with a newly written header line? Default value is `False`.

**OPTIONAL ARGUMENTS FOR DB FILE (SQLITE)**

  - **`table_name`** (str): The name of the table to store messages in. Default value is `messages`.

**OPTIONAL ARGUMENTS FOR LOG FILE**

  - **`channel`** (str): The default value to use when a message does not have a channel set. Default value is `vcan0`.
  - **`append`** (bool): Append messages to any existing file or truncate it?  Default value is `False`.

----
## `can.filter`

Manages the CAN filters.

:::note
For now it is only possible to view the active filters.
:::

----
## `can.help`

Shows this help information.

----
## `can.j1939_query`

Queries a J1939 PGN on the CAN bus.

**ARGUMENTS**

  - **`pgn`** (int): Number of the PGN to query.

**OPTIONAL ARGUMENTS, J1939 QUERY SPECIFIC**

  - **`priority`** (int): The priority to use for the request message. Default value is `6`.
  - **`destination_address`** (int): The destination address of the request message. Default value is `0`.
  - **`source_address`** (int): The source address of the request message. Default value is `249` (Service Tool).
  - **`auto_filter`** (bool): Ensure to apply filtering to only include reply message for the specific PGN. Default value is `True`.
  - **`auto_filter_mask`** (int): The bitmask to use when the filter is applied. Default value is `0x00FFFF00`.
  - **`auto_tp`** (bool): Automatically enable Transport Protocol (TP) for multi-frame messages. Default value is `True`.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`name`** (str): Name of the command. (E.g. `VehicleSpeed` or `SeatTemperature`)
  - **`output`** (str): Select `obj`, `dict` or `str` as the output data type of the reply messages. Ignored if formula argument is given. Default value is `str`. 
  - **`formula`** (str): Python code that decodes the raw byte data to a value. 
  - **`conn`** (str): Name of the CAN interface to use.
  - **`bus`** (str): Name of the bus instance to use. Default value is `default_query_j1939`.
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

**OPTIONAL ARGUMENTS, QUERY GENERAL**

  - **`pass_filters`** (list): List of pass filters to use for receiving reply frames. 
  - **`ensure_filtering`** (bool): Ensure that reply messages not matching the filters are excluded. Default value is `True`.
  - **`flow_control`** (list): List of flow control ID resolvers to enable. Options are `obd` and `custom`.
  - **`custom_flow_control_id_mappings`** (dict): ID mappings to use for custom flow control.
  - **`replies`** (int): The amount of reply messages to wait for within a timeout.
  - **`skip_error_frames`** (bool): Skip any reply message marked as an error frame. Default value is `True`.
  - **`skip_remote_frames`** (bool): Skip any reply message marked as a remote frame. Default value is `True`.
  - **`strict`** (bool): Raise an error when no reply messages are received or if the amount of expected reply messages is not met within the timeout. Default value is `True`.
  - **`timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.

----
## `can.manage`

Facilitates runtime management of the underlying service instance.

----
## `can.monitor`

Monitors messages on the CAN bus until a limit and/or duration is reached.

**OPTIONAL ARGUMENTS**

  - **`duration`** (int): How many seconds to record data? Default value is `1`.
  - **`limit`** (int): The maximum number of messages to read.
  - **`receive_timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.
  - **`skip_error_frames`** (bool): Skip any reply message marked as an error frame. Default value is `False`.
  - **`keep_listening`** (bool): Continue listening for messages in the background? Default value is `False`.
  - **`buffer_size`** (int): The limit of messages that the internal queue can hold. If the value is less than or equal to zero, the queue size is infinite. Default value is `0`.
  - **`output`** (str): Select `obj`, `dict` or `str` as the output data type of the reply messages. Default value is `str`.

----
## `can.obd_query`

Queries an OBD-II PID on the CAN bus.

**ARGUMENTS**

  - **`name`** (str): Name of the command.

**OPTIONAL ARGUMENTS, OBD-II QUERY SPECIFIC**

  - **`mode`** (str): Service section of the PID.
  - **`pid`** (str): Code section of the PID.
  - **`bytes`** (int): Byte size of individual returned frame(s). Default value is `0`.
  - **`frames`** (int): Expected frame count to be returned?
  - **`strict_lengths`** (bool): Enforce strict validation of specified `bytes` and/or `frames`. Default value is `False`.
  - **`decoder`** (str): Specific decoder to be used to process the response.
  - **`unit`** (str): Unit of the result.
  - **`auto_filter`** (bool): Ensure to apply filtering to only include OBD-II reply messages. Default value is `True`.
  - **`auto_format`** (bool): Ensure that the PID request message always has a fixed data length of 8 bytes (zero padding). Default value is `True`.
  - **`id`** (int): Use a custom CAN arbitration ID for the PID request message. 
  - **`is_ext_id`** (bool): Enforce to use extended CAN arbitration ID or not (29 or 11 bit) for the PID request message.
  - **`extended_address`** (int): Extended address value that will be set as the first data byte.
  - **`zero_padding`** (int): Number of zero padding bytes to add to data. Defaults to `8` when `auto_format` is set to `True`.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`formula`** (str): Python code that decodes the raw byte data to a value.
  - **`conn`** (str): Name of the CAN interface to use.
  - **`bus`** (str): Name of the bus instance to use. Default value is `default_query_obd`.
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

**OPTIONAL ARGUMENTS, QUERY GENERAL**

  - **`pass_filters`** (list): List of pass filters to use for receiving reply frames. 
  - **`ensure_filtering`** (bool): Ensure that reply messages not matching the filters are excluded. Default value is `True`.
  - **`flow_control`** (list): List of flow control ID resolvers to enable. Options are `obd` and `custom`.
  - **`custom_flow_control_id_mappings`** (dict): ID mappings to use for custom flow control.
  - **`replies`** (int): The amount of reply messages to wait for within a timeout.
  - **`skip_error_frames`** (bool): Skip any reply message marked as an error frame. Default value is `True`.
  - **`skip_remote_frames`** (bool): Skip any reply message marked as a remote frame. Default value is `True`.
  - **`strict`** (bool): Raise an error when no reply messages are received or if the amount of expected reply messages is not met within the timeout. Default value is `True`.
  - **`timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.

----
## `can.play`

Sends all messages from one or more dump files on the CAN bus.

**ARGUMENTS**

  - **`*files`** (str): Specify one or more dump files for playback.

**OPTIONAL ARGUMENTS**

  - **`ignore_timestamps`** (bool): Ignore the timestamps of the messages and use the `min_gap` parameter as the time between messages instead. Default value is `False`.
  - **`min_gap`** (float): Minimum time between sent messages in seconds. Default value is `0.0001`.
  - **`skip_gaps_gt`** (float): Skip periods of inactivity greater than this (in seconds). Default value is `86400`.
  - **`include_error_frames`** (bool): Also send messages marked as error frames? Default value is `True`.

----
## `can.query`

Queries by sending one or more request messages on the CAN bus and then waits for one or more reply messages.

**ARGUMENTS**

  - **`*messages`** (can.Message|str): CAN request messages to send.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`name`** (str): Name of the command (e.g. `VehicleSpeed` or `SeatTemperature`).
  - **`output`** (str): Select `obj`, `dict` or `str` as the output data type of the reply messages. Default value is `str`.
  - **`formula`** (str): Python code that decodes the raw byte data to a value.
  - **`conn`** (str): Name of the CAN interface to use.
  - **`bus`** (str): Name of the bus instance to use. Default value is `default_query`.
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

**OPTIONAL ARGUMENTS, QUERY GENERAL**

  - **`pass_filters`** (list): List of pass filters to use for receiving reply frames. 
  - **`ensure_filtering`** (bool): Ensure that reply messages not matching the filters are excluded. Default value is `True`.
  - **`flow_control`** (list): List of flow control ID resolvers to enable. Options are `obd` and `custom`.
  - **`custom_flow_control_id_mappings`** (dict): ID mappings to use for custom flow control.
  - **`replies`** (int): The amount of reply messages to wait for within a timeout.
  - **`skip_error_frames`** (bool): Skip any reply message marked as an error frame. Default value is `True`.
  - **`skip_remote_frames`** (bool): Skip any reply message marked as a remote frame. Default value is `True`.
  - **`strict`** (bool): Raise an error when no reply messages are received or if the amount of expected reply messages is not met within the timeout. Default value is `True`.
  - **`timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.

----
## `can.send`

Sends one or more messages on the CAN bus.

**ARGUMENTS**

  - **`*messages`** (str): CAN messages to send.

----
## `can.write_stack`

Stores stack to stack file

---

## Can Decoder

## `can_decoder.decode_handler`

Handler for decoding files containing raw CAN data.

**ARGUMENTS**

  - **`decoder_name`** (str): The callname of the decoder.

**OPTIONAL ARGUMENTS**

  - **`input_directory`** (str): The path from which input files are read.
  - **`output_format`** (str): The path where output files are written to.
  - **`decoder`** (str): The decoder type to be used. Currently supported types are `STANDARD` and `ASAMMDF`.

---

## Certificate

## `certificate.`

Internal certificate generation helper.

---

## Clock

## `clock.help`

Shows this help information.

----
## `clock.ntp`

Enable or disable network time synchronization.

**OPTIONAL ARGUMENTS**

  - **`enable`** (bool): Default is `True`.

----
## `clock.set`

Set system time.

**ARGUMENTS**

  - **`value`** (str): Time string to set.

**OPTIONAL ARGUMENTS**

  - **`adjust_system_clock`** (bool): Default is `False`.

----
## `clock.status`

Show current time settings.

---

## Cloud

## `cloud.cache`

Queries/calls a given cache function.

----
## `cloud.help`

Shows this help information.

----
## `cloud.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `cloud.manage hook list`
  - `cloud.manage hook call status_handler`
  - `cloud.manage worker list *`
  - `cloud.manage worker show *`
  - `cloud.manage worker start *`
  - `cloud.manage worker pause *`
  - `cloud.manage worker resume *`
  - `cloud.manage worker kill *`
  - `cloud.manage reactor list`
  - `cloud.manage reactor show *`
  - `cloud.manage run handler="cache" args="[\"list_queues\"]"`

----
## `cloud.status`

Gets current status.

----
## `cloud.upload`

Uploads cached data to cloud.

----
## `cloud.upload_batch`

:::warning
**DEPRECATED**
This will no longer upload anything.
:::

Uploads next batch of logged data to the cloud server.

---

## Crypto

## `crypto.generate_key`

Generates a new key in the Secure Element

**ARGUMENTS**

  - **`keyid`** (str/int): key`s id

----
## `crypto.help`

Shows this help information.

----
## `crypto.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `reactor.manage hook list`
  - `reactor.manage worker list *`
  - `reactor.manage worker show *`
  - `reactor.manage worker start *`
  - `reactor.manage worker pause *`
  - `reactor.manage worker resume *`
  - `reactor.manage worker kill *`
  - `reactor.manage reactor list`
  - `reactor.manage reactor show *`

----
## `crypto.query`

Queries a given SPM command.

**ARGUMENTS**

  - **`cmd`** (str): The SPM command to query.

----
## `crypto.sign_string`

Signs a given string using the Secure Element

**ARGUMENTS**

  - **`data`** (str): String to be signed
  - **`keyid`** (str/int): key`s id

---

## Cryptoauth

## `cryptoauth.help`

Shows this help information.

----
## `cryptoauth.query`

---

## Dac

## `dac.test`

Tests MCP4725 DAC.

**OPTIONAL ARGUMENTS**

  - **`port`** (int): Default is `1`.
  - **`address`** (int): Default is `96`.

---

## Disk Housekeeper

## `disk_housekeeper.disk_clean_handler`

Handler for deleting old files when disk is running full.

---

## Doip(Commands)

## `doip.context`

Gets current context.

----
## `doip.help`

Shows this help information.

----
## `doip.interface`

Manages the DoIP interface.

**EXAMPLES**

  - `doip.interface`
  - `doip.interface help`
  - `doip.interface activate`
  - `doip.interface activate pin_setup=alt`
  - `doip.interface deactivate`
  - `doip.interface connect`
  - `doip.interface disconnect`
  - `doip.interface reconnect`

----
## `doip.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `doip.manage hook list`
  - `doip.manage hook call uds_handler change_session 1`
  - `doip.manage worker list *`
  - `doip.manage worker show *`
  - `doip.manage worker start *`
  - `doip.manage worker pause *`
  - `doip.manage worker resume *`
  - `doip.manage worker kill *`
  - `doip.manage reactor list`
  - `doip.manage reactor show *`
  - `doip.manage run handler="uds" args="[\"change_session\", 1]"`

----
## `doip.uds`

Queries using the UDS client. The UDS client works synchronously and can handle a single request/response at a time.

**EXAMPLES**

  - `doip.uds help`
  - `doip.uds help change_session`
  - `doip.uds change_session 1`

---

## Ec2X

## `ec2x.`

:::note Important The EC2X commands listed in this documentation are only compatible with the EC2X series of modems and require a board version of 6.0 or below. Ensure that your hardware meets these requirements before attempting to use these commands. ::

----
## `ec2x.cell_location`

Get location by triangulation (QuecLocator).

----
## `ec2x.cell_signal`

Signal quality report indicates the received signal strength and the channel bit error rate.

----
## `ec2x.connection`

Manages current connection.

**OPTIONAL ARGUMENTS**

  - **`close`** (bool): Close serial connection? Default value is `False`.

**EXAMPLES**

  - `ec2x.connection`
  - `ec2x.connection close=True`

----
## `ec2x.context`

:::warning
**DEPRECATED**
Use 'manage context' instead.
:::
Gets current context.

----
## `ec2x.data_usage`

Check how many bytes are sent to and received by the module.

----
## `ec2x.delete_file`

Deletes a single file or all the files in the specified storage.

----
## `ec2x.delete_sms`

Delete messages from message storage.

It is possible to list possible for deleting if no indexes are passed and the `delete_all` kwarg is not passed (or set to `False`).

Keyword argumnets:

- index (int): The index of the message to be deleted. Default None.
- delete_all (bool): Set this boolean to true if all messages stored in the modem should be deleted. Default `False`.
- confirm (bool): A confirm flag when deleting messages. Default `False`.

----
## `ec2x.download`

Low-level function to download files.

----
## `ec2x.download_file`

----
## `ec2x.error_format_config`

Controls the format of error result codes: `ERROR`, error numbers or
verbose messages as `+CME ERROR: <err>` and `+CMS ERROR: <err>`.

----
## `ec2x.firmware_rev`

Revision identification of software release.

----
## `ec2x.gnss`

The command is used to turn on GNSS function. Currently `<mode>` only supports
turning on GNSS in Stand-alone Solution. When `<fixcount>` is 0, GNSS will fix
position continuously, and it can be turned off via `AT+QGPSEND`. When `<fixcount>`
is non-zero and reaches the specified value, GNSS will be turned off automatically.

When GNSS is turned on and `<fixcount>` is 0, GNSS fixes position continuously.
In this case, GNSS can be turned off compulsorily via this command. When
`<fixcount>` is non-zero, GNSS will be turned off automatically when the
parameter reaches the specified value, and thus the command can be ignored.

**OPTIONAL ARGUMENTS**

  - **`enable`** (bool):
  - **`mode`** (int): Default value is `1`.
  - **`fix_max_time`** (int): Default value is `30`.
  - **`fix_max_dist`** (int): Default value is `50`.
  - **`fix_count`** (int): Default value is `0`.
  - **`fix_rate`** (int): Default value is `1`.

----
## `ec2x.gnss_assist`

This command can be used to enable gpsOneXTRA Assistance function, and the
function can be activated after restarting the module.

----
## `ec2x.gnss_assist_data`

Query the status or specify gpsOneXTRA data file.

----
## `ec2x.gnss_assist_data_reset`

Delete assistance data to operate cold start, hot start and warm start of GNSS. The command
can only be executed when GNSS is turned off. After deleting the assistance data via this
command, cold start of GNSS can be enforced via AT+QGPS. Hot/warm start can also be performed
if the corresponding conditions are satisfied.

- `0` = Delete all assistance data except gpsOneXTRA data. Enforce cold start after starting GNSS.
- `1` = Do not delete any data. Perform hot start if the conditions are permitted after starting GNSS.
- `2` = Delete some related data. Perform warm start if the conditions are permitted after starting GNSS.
- `3` = Delete the gpsOneXTRA assistance data injected into GNSS engine.

----
## `ec2x.gnss_assist_time`

This command can be used to inject gpsOneXTRA time to GNSS engine. Before using it,
customers must enable gpsOneXTRA Assistance function via AT+QGPSXTRA=1 command.
After activating the function, the GNSS engine will ask for gpsOneXTRA time and
assistance data file. Before injecting gpsOneXTRA data file, gpsOneXTRA time must
be injected first via this command.

----
## `ec2x.gnss_auto_start`

Enable/disable GNSS to run automatically after the module is powered on.
Configuration parameter will be automatically saved to NVRAM. The default value is 0.

----
## `ec2x.gnss_config`

Configure supported GNSS constellation.

:::note
Requires restart of EC2x module to take effect.
:::

Supported GNSS constellation (GPS is always on):

- `0` = GLONASS off/BeiDou off/Galileo off
- `1` = GLONASS on/BeiDou on/Galileo on
- `2` = GLONASS on/BeiDou on/Galileo off
- `3` = GLONASS on/BeiDou off/Galileo on
- `4` = GLONASS on/BeiDou off/Galileo off
- `5` = GLONASS off/BeiDou on/Galileo on
- `6` = GLONASS off/BeiDou off/Galileo on

----
## `ec2x.gnss_fix_frequency`

Gets or sets the fix frequency of the GNSS engine.

:::note
When changing the fix frequency, the GNSS engine needs to be restarted
:::
for changes to take effect.

The fix frequency of the GNSS engine corresponds to how often will the position
(latitude and longitude) update. Possible values (Hz):

- None (default): returns the current fix_frequency of the GNSS engine
- 1
- 2
- 5
- 10

----
## `ec2x.gnss_location`

Acquire positioning information on request.

Mode controls latitude and longitude display format:

- `0` = ddmm.mmmm N/S,dddmm.mmmm E/W
- `1` = ddmm.mmmmmm N/S,dddmm.mmmmmm E/W
- `2` = (-)dd.ddddd,(-)ddd.ddddd

----
## `ec2x.gnss_nmea_fix_stats`

----
## `ec2x.gnss_nmea_gga`

Get NMEA GGA data parsed into dict.

----
## `ec2x.gnss_nmea_gsa`

Get NMEA GSA data parsed into dict.

----
## `ec2x.gnss_nmea_gsv`

Get list where entries are grouped by all available satellites in NMEA GSV data.

----
## `ec2x.gnss_nmea_gsv_ext`

Enable/disable output of extended GSV information. Elevation/Azimuth/SNR (C/No) will
be displayed as decimals when extended information is enabled, otherwise they will be
displayed as integers. The configuration parameter will be automatically saved to NVRAM.

----
## `ec2x.gnss_nmea_output_beidou`

Configure output type of BeiDou NMEA sentences.

:::note
Requires restart of EC2x module to take effect.
:::

Configure output type of BeiDou NMEA sentences via ORed, and the configuration parameter will be automatically saved to NVRAM.
The default value is 0.

- `0` = Disable
- `1` = GSA
- `2` = GSV

----
## `ec2x.gnss_nmea_output_galileo`

Configure output type of Galileo NMEA sentences.

:::note
Requires restart of EC2x module to take effect.
:::

Configure output type of Galileo NMEA sentences by ORed, and the configuration parameter will be automatically saved to NVRAM.
The default value is 0.

- `0` = Disable
- `1` = GSV

----
## `ec2x.gnss_nmea_output_glonass`

Configure output type of GLONASS NMEA sentences.

:::note
Requires restart of EC2x module to take effect.
:::

Configure output type of GLONASS NMEA sentences by ORed, and the configuration parameter will be automatically saved to NVRAM.
The default value is 0.

- `0` = Disable
- `1` = GSV
- `2` = GSA
- `4` = GNS

----
## `ec2x.gnss_nmea_output_gps`

Configure output type of GPS NMEA sentences.

:::note
Requires restart of EC2x module to take effect.
:::

Output type of GPS NMEA sentences by ORed, and the configuration parameter will be automatically saved to NVRAM.
The default value is 31 which means that all the five types of sentences will be output.

- `0` = Disable
- `1` = GGA (Essential fix data which provide 3D location and accuracy data)
- `2` = RMC (Recommended minimum data for GPS)
- `4` = GSV (Detailed satellite data)
- `8` = GSA (Overall satellite data)
- `16` = VTG (Vector track and speed over the ground)

----
## `ec2x.gnss_nmea_port`

Configure the output port of NMEA sentences, and the configuration parameter will be automatically saved to NVRAM.

Port options:

- `none` = Close NMEA sentence output
- `usbnmea` = Output via USB NMEA port
- `uartdebug` = Output via UART debug port

----
## `ec2x.gnss_nmea_raw`

Acquire NMEA sentence(s) data on request.

Available types:

- `GGA` (Fix information)
- `RMC` (Recommended minimum data for GPS)
- `GSV` (Detailed satellite data)
- `GSA` (Overall satellite data)
- `VTG` (Vector track an speed over the ground)
- `GNS`

----
## `ec2x.gnss_nmea_req`

Enables/disables acquisition of NMEA sentences on request via commands.

----
## `ec2x.gnss_nmea_sat_stats`

Get list of summarized information about each satellite currently in view.

----
## `ec2x.help`

Shows this help information.

----
## `ec2x.imei`

Returns the International Mobile Equipment Identity (IMEI).

----
## `ec2x.list_files`

lists the information of a single file or all files in the required storage medium.

----
## `ec2x.list_sms`

List all messages from message storage.

:::note
In order to use this function, you need to first execute `ec2x.sms_format_config value=1`
:::
to set the correct format of the SMS messages.

----
## `ec2x.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `ec2x.manage hook list`
  - `ec2x.manage hook call exec_handler ATI`
  - `ec2x.manage worker list *`
  - `ec2x.manage worker show *`
  - `ec2x.manage worker start *`
  - `ec2x.manage worker pause *`
  - `ec2x.manage worker resume *`
  - `ec2x.manage worker kill *`
  - `ec2x.manage reactor list`
  - `ec2x.manage reactor show *`
  - `ec2x.manage run handler="exec" args="[\"ATI\"]" returner="cloud"`

----
## `ec2x.modem_functionality`

Get or set the modem`s functionality level. There are three values that can be selected:

1. `minimum` - minimal functionality level
2. `full` - full functionality level
3. `disable` - disable all communication going in and from the modem

Parameters:

- value (string): Default None. If the functionality level on the modem should be changed, this
parameter needs to be set to one of the three available values: [`minimum`, `full`, `disable`]
- reset (boolean): Default False. This parameter is ignored if value == None. If set to a truthy
value, the modem will be completely restarted with the execution of this function

----
## `ec2x.network_registration_status`

Gets the network registration status from the modem. There are five possible results:

1. `not-registered-not-searching`: Modem isn`t registered to a network. The modem isn`t searching for a new network.
2. `not-registered-searching`: Modem isn`t registered to a network, but searching for one.
3. `registration-denied`: Registration has been denied.
4. `registered-home`: Modem is registered to a home network.
5. `registered-roaming`: Modem is registered to a roaming network.

----
## `ec2x.operator_selection`

This command returns the current operators and their status, and allows setting automatic or
manual network selection. There are three actions that can be achieved through this function.

The Search action returns a set of five parameters each representing an operator present in the
network. This list can later be used to attempt connecting to a specific operator.

The Read action returns the current mode and the currently selected operator. If no operator is
selected, `<format>`, `<operator>` and `<access_tech>` are omitted.

The Write action forces an attempt to select and register the GSM/UMTS network operator. If the
selected operator is not available, no other operator shall be selected (except when using `<mode>`=4).

Parameters:

- search (bool): Default False. Whether the search action should be executed. Search action attempts to
retrieve all currently available operators in the area. This can take a long time. If this
argument is provided, all other parameters will be ignored.
- mode (string): Default None. What mode should the operator selection be put in.
- op_format (string): Default None. In what format is the operator name written in.
- operator (string): Default None. The operator name to attempt a connection with.
- access_tech (string): Default None. The access technology that should be used.

----
## `ec2x.power`

Low-level function to run power command.

----
## `ec2x.power_off`

Used to shut down the entire EC2x module. The module will restart automatically.
A 30-second wait is included after power off to allow the module time to recover before receiving any new command requests.

----
## `ec2x.product_info`

Display product identification information.

----
## `ec2x.query`

Low-level function to execute AT commands.

----
## `ec2x.ri_other_config`

Specifies the RI (Ring Indicator) behavior when other URCs are presented.

**OPTIONAL ARGUMENTS**

  - **`value`** (str):
  - **`pulse_duration`** (int): Default value is `120`.
  - **`pulse_count`** (int): Default value is `1`.

----
## `ec2x.ri_signal_config`

Specifies the RI (Ring Indicator) signal output carrier.

**OPTIONAL ARGUMENTS**

  - **`value`** (str):

----
## `ec2x.ri_sms_config`

Specifies the RI (Ring Indicator) behavior when incoming SMS URCs are presented.

**OPTIONAL ARGUMENTS**

  - **`value`** (str):
  - **`pulse_duration`** (int): Default value is `120`.
  - **`pulse_count`** (int): Default value is `1`.

----
## `ec2x.roaming`

Retrieves the current roaming configuration. If value parameter is set, it`ll set the roaming service to that value.

Possible values:

- False - (bool) Roaming is disabled
- True - (bool) Roaming is enabled
- `auto` - (string) Roaming is set to Auto mode

----
## `ec2x.sms_format_config`

Gets or sets the SMS format configuration.

Possible values:

- 0: PDU mode - entire TP data units used (hex responses). This is the default value.
- 1: Text mode - headers and body of the message given as separate parameters.

----
## `ec2x.sync_time`

Synchronize system time with network time.

----
## `ec2x.time`

Obtain the latest time synchronized through network

Query network time mode:

- `0` = Query the latest time that has been synchronized through network
- `1` = Query the current GMT time calculated from the latest time that has been synchronized through network
- `2` = Query the current LOCAL time calculated from the latest time that has been synchronized through network

----
## `ec2x.upload`

Low-level function to upload files.

----
## `ec2x.upload_file`

----
## `ec2x.urc_port_config`

Configure the output port of URC (Unsolicited Result Code).

Port options:

- `usbat` (USB AT port)
- `usbmodem` (USB modem port)
- `uart1` (Main UART)

---

## File Sync

## `file_sync.help`

Shows this help information.

----
## `file_sync.process_jobs_async`

Process the file synchronization jobs asynchronously.

----
## `file_sync.s3_sync`

Run an AWS S3 sync process.

---

## Fileutil

## `fileutil.grep`

Match lines in a text file.

**ARGUMENTS**

  - **`pattern`** (str): Regex pattern to match.
  - **`file`** (str): File to search in.

**OPTIONAL ARGUMENTS**

  - **`tail_lines`** (int): How many of the last matched lines should be included? Set to `0` to include all lines. Default is `10`.

----
## `fileutil.line_count`

Returns count of new line characters in a file.

----
## `fileutil.load_yaml`

Load a file as YAML or return default.

----
## `fileutil.remove_all`

Similar to `file.remove` but with many at once.

----
## `fileutil.upload`

Uploads a file (by default gzipped) to a service.

**ARGUMENTS**

  - **`path`** (str): Path to the file.

**OPTIONAL ARGUMENTS**

  - **`gzip`** (bool): Gzip it? Default is `True`.
  - **`service`** (str): The service to be used (Possible: `dropbox`). Default is None.
  - **`token`** (str): The token to use when uploading (Required when using `dropbox` service)

---

## Gnss

## `gnss.connection`

Query the connection class.

----
## `gnss.help`

Shows this help information.

----
## `gnss.load_geofences`

Loads geofences.
**OPTIONAL ARGUMENTS**

  - `path` path to the geofences file

----
## `gnss.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `gnss.manage hook list`
  - `gnss.manage hook call connection_handler gnss_location`
  - `gnss.manage worker list *`
  - `gnss.manage worker show *`
  - `gnss.manage worker start *`
  - `gnss.manage worker pause *`
  - `gnss.manage worker resume *`
  - `gnss.manage worker kill *`
  - `gnss.manage reactor list`
  - `gnss.manage reactor show *`
  - `gnss.manage run handler="connection" args="[\"gnss_location\"]" converter="gnss_location_to_position" returner="cloud"`

---

## Hooklib

## `hooklib.alternating_readout_filter`

Filter that only returns alternating/changed results.

**OPTIONAL ARGUMENTS**

  - **`pass_interval`** (int): Filter passes values only when this many miliseconds have passed between readings, even when the values are different. Default value is `0`.

----
## `hooklib.battery_converter`

Converts a voltage reading result with battery charge state and level.

----
## `hooklib.battery_event_trigger`

Looks for battery results and triggers `vehicle/battery/*` event when voltage changes.

----
## `hooklib.battery_nominal_voltage_event_trigger`

Looks for battery results and triggers `vehicle/battery/nominal_voltage/*` event when the nominal voltage state changes.
All possible events are:

- vehicle/battery/nominal_voltage/unknown
- vehicle/battery/nominal_voltage/autodetected
- vehicle/battery/nominal_voltage/predefined

----
## `hooklib.context_cache_handler`

Manages cached data in the context.

----
## `hooklib.echo_handler`

Mainly for testing.

----
## `hooklib.geofence_event_trigger`

Listens for position results and triggers geofence inside/outside and enter/exit events
inside/outside - triggered on startup
enter/exit - triggered during driving
Change happens when the same result is repeated [repeat_count_to_trigger_change] times

----
## `hooklib.kernel_error_blacklist_filter`

Filters out blacklisted kernel errors.

----
## `hooklib.kernel_error_event_trigger`

Triggers `system/kernel/error` events.

----
## `hooklib.load_geofences_handler`

Loads geofence file

----
## `hooklib.module_direct_handler`

Calls a Salt execution module directy from current process.

----
## `hooklib.module_handler`

Calls a Salt execution module from within the minion process.

----
## `hooklib.returner_call_handler`

Calls a Salt returner module directy from current process.

----
## `hooklib.skip_empty_filter`

Filters out empty results.

----
## `hooklib.temperature_event_trigger`

Looks for temperature results and triggers `system/temperature/*` event when temperature changes.

---

## Hostapd

## `hostapd.clients`

Returns all connected clients indexed by their MAC address.

**OPTIONAL ARGUMENTS**

  - **`interface`** (str): Specific network interface. Default is `uap0`

----
## `hostapd.clients_changed_trigger`

Triggers `system/hotspot/client/<mac>/connected` and `system/hotspot/client/<mac>/disconnected` events.

The trigger expects the result to be given in the format of what hostapd.clients returns,
which is also the main use case for this trigger.

----
## `hostapd.expect_allow_list_handler`

This handler triggers `system/hotspot/client/<mac>/not_connected` events for clients that aren`t
connected from the hostapd allow list.

In order for the handler to work properly the allow list must be stored in the default hostapd.accept
file, which will be the case if the allow list is set through the Advanced Settings in the Cloud.

----
## `hostapd.help`

Shows this help information.

---

## Introduction(Core)

Commands are executed on the device. They can be run remotely from the [Cloud](https://www.autopi.io/software-platform/cloud-management) terminal or through the local dashboard accessible via the WiFi hotspot. Commands can even be executed directly from the Linux shell via the built-in `autopi` executable.

:::note
You can actually program your own commands in Python through the [AutoPi](https://www.autopi.io) Cloud. When logged in go to: _Device_ -> _Custom Code_
:::

:::tip
Like any [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) functionality, commands can be executed programmatically through the [AutoPi](https://www.autopi.io) REST API. For more information see: https://api.autopi.io/#dongle-execute-create
:::

---

## Keyfob

## `keyfob.action`

Performs a key fob button action.

**ARGUMENTS**

  - **`*name`** (str): Name(s) of the action(s) to perform.

----
## `keyfob.context`

:::warning
**DEPRECATED**
Use 'manage context' instead.
:::
Gets current context.

----
## `keyfob.help`

Shows this help information.

----
## `keyfob.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `keyfob.manage hook list`
  - `keyfob.manage hook call power`
  - `keyfob.manage worker list *`
  - `keyfob.manage worker show *`
  - `keyfob.manage worker start *`
  - `keyfob.manage worker pause *`
  - `keyfob.manage worker resume *`
  - `keyfob.manage worker kill *`
  - `keyfob.manage reactor list`
  - `keyfob.manage reactor show *`

----
## `keyfob.power`

Powers on/off key fob.

**OPTIONAL ARGUMENTS**

  - **`value`** (bool): Power on or off.

---

## Log

## `log.help`

Shows this help information.

----
## `log.journalctl`

Retrive log files for either kernel, system or salt-minion.

**ARGUMENTS**

- **`log`** (str): The log you want to retrieve.

**OPTIONAL ARGUMENTS**

- **`minutes`** (int): Specifies time delimiter on report retrival, time now minus minutes.
- **`days`** (int): Overwrites minutes to days date minus days.
- **`lines`** (int): Specifies the maximum number of lines returned.
- **`grep`** (str): Match expressions and delimit output string.
- **`matched_lines`** (int): Amount of lines returned after grep pattern context.
- **`boot`** (int): Fetches boot records from journal using offset; positive starting from the first boot, non-positive starting from the last boot, -0 or no number for current boot.

----
## `log.kernel`

Print and/or clear the kernel ring buffer.

**OPTIONAL ARGUMENTS**

  - **`level`** (str): Restict output the the given level and higher. Default is `err`.
  - **`facilities`** (str): Restrict output to the given list (comma-separated) of facilities.
  - **`offset`** (str): Offset regex to begin from.
  - **`clear`** (bool): Clear after reading.

----
## `log.kernel_iter`

Helper function to retrieve new kernel log entries (based on cached offset value).

**OPTIONAL ARGUMENTS**

  - **`level`** (str): Restict output the the given level and higher. Default is `err`.
  - **`facilities`** (str): Restrict output to the given list (comma-separated) of facilities.
  - **`offset_key`** (str): Key to get value from result and use as offset. Default is `timestamp`.
  - **`reset`** (bool): Reset cached offset value and start over.

----
## `log.query`

Query a log file or any text file.

**ARGUMENTS**

  - **`file`** (str): Path of log file.

**OPTIONAL ARGUMENTS**

  - **`begin`** (str): Default is `^`.
  - **`end`** (str): Default is `$`.
  - **`match`** (str): Default is `.*`.
  - **`count`** (int): Default is `0`.
  - **`reverse`** (bool): Default is `False`.
  - **`before`** (int): Default is `0`.
  - **`after`** (int): Default is `0`.
  - **`first`** (int): Default is `0`.
  - **`last`** (int): Default is `100`.

---

## Logger

## `logger.call`

Helper command to call handlers or workflows on different engines/services identified by their namespace.

**ARGUMENTS**

  - **`namespace`** (str): The namespace of the engine/service to call.
  - **`handler/workflow`** (str): Name of the handler or workflow to call.
  - **`*args`** (str): The argument(s) to pass to the handler or workflow.

**EXAMPLES**

  - `logger.call can0 manage context`
  - `logger.call can0 obd_query rpm`
  - `logger.call can0_decoder manage worker list`

----
## `logger.channel`

Alias for the `logger.channels` command.

----
## `logger.channel_namespaces`

Returns available namespaces grouped by the channel they belong to.

**ARGUMENTS**

  - **`*only`** (str): The channel(s) to include in the result. If none defined all channels are included.

----
## `logger.channels`

Returns details of all channels available for this device.

**ARGUMENTS**

  - **`*only`** (str): The channel(s) to include in the result. If none defined all channels are included.

**OPTIONAL ARGUMENTS**

  - **`verbose`** (bool): Include more details in the result? Default value is `False`.

----
## `logger.disk`

Alias for the `logger.disks` command.

----
## `logger.disks`

Returns details of all disks available for this device.

**OPTIONAL ARGUMENTS**

  - **`verbose`** (bool): Include more details in the result? Default value is `False`.

----
## `logger.help`

Shows this help information.

----
## `logger.status`

Returns a status overview of all channels and disks available for this device.
This command is just a composite result of the two commands `logger.channels` and `logger.disks`.

**OPTIONAL ARGUMENTS**

  - **`verbose`** (bool): Include more details in the result? Default value is `False`.

---

## Minionutil

## `minionutil.change_master`

Change to different master host.

**ARGUMENTS**

  - **`host`** (str): Hostname of the new master to change to.

**OPTIONAL ARGUMENTS**

  - **`confirm`** (bool): Acknowledge the execution of this command. Default is `False`.
  - **`show_changes`** (bool): Show the changes made in the file `/etc/salt/minion`. Default is `False`.

:::note
When the master (hub) is changed, the API endpoint URL won't be updated automatically
:::
unless there is a pending sync (for example coming from an update) that will execute the
minion.config state.

:::note
When moving back and forth between envs and the key hasn't been accepted,
:::
the device will keep retrying to connect to the master. If then the salt-minion service
is restarted, the service won`t shutdown until a SIGKILL is sent to the process (i.e. the
salt-minion service will keep retrying to connect to the salt-master)

----
## `minionutil.help`

Shows this help information.

----
## `minionutil.last_errors`

Get last errors from minion log.

**OPTIONAL ARGUMENTS**

  - **`file`** (str): Default is `minion`.
  - **`until`** (str): Default is `$`.
  - **`level`** (str): Default is `error`.
  - **`count`** (int): Default is `0`.
  - **`before`** (int): Default is `0`.
  - **`after`** (int): Default is `0`.
  - **`limit`** (int): Default is `100`.

----
## `minionutil.last_logs`

Get last log lines from minion log.

**OPTIONAL ARGUMENTS**

  - **`file`** (str): Default is `minion`.
  - **`until`** (str): Default is `$`.
  - **`match`** (str): Default is `.*`.
  - **`count`** (int): Default is `0`.
  - **`before`** (int): Default is `0`.
  - **`after`** (int): Default is `0`.
  - **`limit`** (int): Default is `100`.

----
## `minionutil.last_startup`

Get log lines for last startup sequence.

**OPTIONAL ARGUMENTS**

  - **`file`** (str): Default is `minion`.
  - **`until`** (str): Default is `$`.
  - **`match`** (str): Default is `Setting up the Salt Minion`.
  - **`limit`** (int): Default is `100`.

----
## `minionutil.log_files`

List all minion log files.

----
## `minionutil.master_status`

Get status of connection to master.
Implementation originates from the `status.master` command but without the logic to trigger events.

----
## `minionutil.request_restart`

Request for a future restart of the minion service.

**OPTIONAL ARGUMENTS**

  - **`pending`** (bool): Default is `True`.
  - **`immediately`** (bool): Default is `False`.
  - **`delay`** (int): Default is `10`.
  - **`expiration`** (int): Default is `1200`.
  - **`reason`** (str): Reason code that tells why we decided to restart. Default is `unknown`.

----
## `minionutil.restart`

Restart the minion service immediately.

**OPTIONAL ARGUMENTS**

  - **`reason`** (str): Reason code that tells why we decided to restart. Default is `unknown`.

----
## `minionutil.run_job`

Run a job by passing it to the minion process.
This function makes it possible to run states and also get pillar data from external processes (engines etc.).

----
## `minionutil.status_schedule`

Dedicated to be called from schedule and trigger minion status events.

----
## `minionutil.trigger_event`

Triggers an event on the minion event bus.

----
## `minionutil.update_release`

Update a minion to newest release by running a highstate if not already up-to-date.

**OPTIONAL ARGUMENTS**

  - **`force`** (bool): Default is `False`. Force an update, skipping all checks that would stop the update from occuring.
  - **`demand`** (bool): Default is `False`. Demand an update, even if the device is already in the latest version.
  - **`dry_run`** (bool): Default is `False`. Don`t actually perform the update.
  - **`only_retry`** (bool): Default is `False`. Perform an update only if it is in the retrying state.
  - **`reset_attempts`** (bool): Default is `False`. Set this to true if you want to reset the attempts counter that limits the amount of failed update retries.

Notes:

- The difference between the `force` and `demand` arguments is that `demand` is used to perform an update even if the device is already up-to-date.
It will not skip over the maximum allowed failed update retries. `force` on the other hand will do both, it will perform an update on the device,
even if it`s already up to date, but will also skip over the maximum allowed failed updates. In other words, they are almost the same, except that
`force` will skip over the retry limit.

---

## Modem

## `modem.connection`

Queries a given connection class command.

**ARGUMENTS**

  - **`cmd`** (str): The command to query.

:::note
When `modem.connection execute` is used with a command like `AT$GPSACP` from bash on device, the `$` must be escaped
with a `\`, so `AT\$GPSACP`. Otherwise, the `$GPSACP` is interpreted as a bash variable.
Retrieve GPS Location
To retrieve the GPS location of the device, use the gnss_location command. This queries the GNSS module for the current geographical position.

Example commands:

`autopi modem.connection execute AT\$GPSACP`
`autopi modem.connection gnss_location`
:::

----
## `modem.help`

Shows this help information.

----
## `modem.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `modem.manage hook list`
  - `modem.manage hook call connection_handler status`
  - `modem.manage worker list *`
  - `modem.manage worker show *`
  - `modem.manage worker start *`
  - `modem.manage worker pause *`
  - `modem.manage worker resume *`
  - `modem.manage worker kill *`
  - `modem.manage reactor list`
  - `modem.manage reactor show *`
  - `modem.manage run handler="connection" args="[\"status\"]"`

----
## `modem.read_sms`

Reads SMS messages stored in the modem and processes them into `system/sms/received` events.
Those events hold information such as the timestamp of the message (when it was received by the
modem), the sender and the text.

Optional parameters:

- clear (bool): Should the messages be deleted from the modem after being processed? Default: False.

----
## `modem.reset`

Enable or disable the one shot or periodic unit reset.

Optional parameters:

- mode (string): The mode in which to operate the command. For available values, look below. Default: None.
- delay (number): Time interval in minutes after that the unit reboots. Default: 0.
- reason (str): The reason the reset was performed. Default: "unspecified".

Available modes:

- disabled: Disables unit reset.
- one_shot: Enables the unit reset only one time (one shot reset).
- periodic: Enables periodic resets of the unit.

---

## Mosquitto

## `mosquitto.error_event_trigger`

Triggers `system/mosquitto/error` events.

---

## Obd(Commands)

## `obd.battery`

Gets current battery voltage

----
## `obd.commands`

Lists all supported OBD commands found for vehicle.

----
## `obd.connection`

Manages current connection.

**OPTIONAL ARGUMENTS**

  - **`baudrate`** (int): Changes baudrate used to communicate with interface.
  - **`reset`** (str): Reboots interface. Available options: warm, cold

**EXAMPLES**

  - `obd.connection`
  - `obd.connection baudrate=1152000`
  - `obd.connection reset=cold`

----
## `obd.context`

:::warning
**DEPRECATED**
Use 'manage context' instead.
:::
Gets current context.

----
## `obd.dtc`

Reads and clears Diagnostics Trouble Codes (DTCs).

**OPTIONAL ARGUMENTS**

 - **`clear`** (bool): clear DTC codes

----
## `obd.dump`

Dumps all messages from bus to screen or file.

**OPTIONAL ARGUMENTS**

  - **`duration`** (int): How many seconds to record data? Default value is `2` seconds.
  - **`file`** (str): Write data to a file with the given name.
  - **`description`** (str): Additional description to the file.
  - **`filtering`** (bool): Use filters while monitoring or monitor all messages? Default value is `False`. It is possible to specify `can` or `j1939` (PGN) in order to add filters based on the messages found in a CAN database file (.dbc).
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`raw_response`** (bool): Get raw response without any validation nor parsing? Default value is `False`.
  - **`format_response`** (bool): Format response frames by separating header and data with a hash sign. Default value is `True`.

----
## `obd.execute`

Executes an AT/ST command.

**ARGUMENTS**

  - **`cmd`** (str): Command to execute.

**OPTIONAL ARGUMENTS**

  - **`assert_result`** (str or list): Validate the response by checking that is matches this specific value.
  - **`reset`** (str): Reset interface after execution. Valid options are: `warm`, `cold`
  - **`keep_conn`** (bool): Keep connection to interface after execution or close it permanently? Default value is `True`.
  - **`type`** (str): Specify a name of the type of the result. Default is the given command.

----
## `obd.file_export`

Fast export of all messages on a bus to a log file.

**OPTIONAL ARGUMENTS**

  - **`run`** (bool): Specify if subprocess should be running or not. If not defined the current state will be queried.
  - **`folder`** (str): Custom folder to place export log files.
  - **`wait_timeout`** (int): Maximum time in seconds to wait for subprocess to complete. Default value is `0`.
  - **`monitor_filtering`** (bool): Use filters while monitoring or monitor all messages? Default value is `False`. It is possible to specify `can` or `j1939` (PGN) in order to add filters based on the messages found in a CAN database file (.dbc).
  - **`monitor_mode`** (int): The STN monitor mode. Default is `0`.
  - **`can_auto_format`** (bool): Apply automatic formatting of messages? Default value is `False`.
  - **`read_timeout`** (int): How long time in seconds should the subprocess wait for data on the serial port? Default value is `1`.
  - **`serial_baudrate`** (int): Specify a custom baud rate to use for the serial connection to the STN.
  - **`process_nice`** (int): Process nice value that controls the priority of the subprocess. Default value is `-2`.
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.

----
## `obd.file_import`

Fast import of exported log files containing messages from a bus.

**OPTIONAL ARGUMENTS**

  - **`folder`** (str): Custom folder to import log files from.
  - **`limit`** (int): The maximum number of lines/messages to read each time. Default value is `5000`.
  - **`idle_sleep`** (int): Pause in seconds if there is no lines/messages to import. Default value is `0`.
  - **`cleanup_grace`** (int): Grace period in seconds before a fully imported log file is deleted. Default value is `60`.
  - **`process_nice`** (int): Process nice value that controls the priority of the service. Default value is `0`.
  - **`type`** (str): Specify a name of the type of the result. Default is `raw`.

----
## `obd.filter`

Manages filters.

**ARGUMENTS**

  - **`action`** (str): Action to perform. Available actions are `auto`, `list`, `add`, `clear` and `sync`.

**EXAMPLES**

  - `obd.filter auto [enable=true]`
  - `obd.filter list [type=<all|pass|block|flow|pgn>]`
  - `obd.filter add <pass|block|flow|pgn> 7c8,7ff`
  - `obd.filter clear [type=<all|pass|block|flow|pgn>]`
  - `obd.filter sync <DBC file path> <pass|block|flow|pgn> [frame_id_mask=0x1FFFFF00]`

----
## `obd.help`

Shows this help information.

----
## `obd.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `obd.manage hook list`
  - `obd.manage hook call execute_handler ATRV`
  - `obd.manage worker list *`
  - `obd.manage worker show *`
  - `obd.manage worker start *`
  - `obd.manage worker pause *`
  - `obd.manage worker resume *`
  - `obd.manage worker kill *`
  - `obd.manage reactor list`
  - `obd.manage reactor show *`
  - `obd.manage run handler="query" args="[\"ELM_VOLTAGE\"]" converter="battery" returner="cloud"`

----
## `obd.monitor`

Monitors messages on bus until limit or duration is reached.

**OPTIONAL ARGUMENTS**

  - **`wait`** (bool): Wait for each message/line to read according to the default timeout of the serial connection (default 1 second). Otherwise there will only be waiting on the first line. line/message. Default value is `False`.
  - **`limit`** (int): The maximum number of messages to read. Default value is `500`.
  - **`duration`** (float): How many seconds to monitor? If not set there is no limitation.
  - **`mode`** (int): The STN monitor mode. Default is `0`.
  - **`auto_format`** (bool): Apply automatic formatting of messages? Default value is `False`.
  - **`filtering`** (bool): Use filters while monitoring or monitor all messages? Default value is `False`. It is possible to specify `can` or `j1939` (PGN) in order to add filters based on the messages found in a CAN database file (.dbc).
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`type`** (str): Specify a name of the type of the result. Default is `raw`.

----
## `obd.play`

Plays all messages from a file on the bus.

**ARGUMENTS**

  - **`file`** (str): Path to file recorded with the `obd.dump` command.

**OPTIONAL ARGUMENTS**

  - **`delay`** (float): Delay in milliseconds between sending each message. Default value is `0`.
  - **`slice`** (str): Slice the list of messages before sending on the CAN bus. Based one the divide and conquer algorithm. Multiple slice characters can be specified in continuation of each other.
    - `t`: Top half of remaining result.
    - `b`: Bottom half of remaining result.
  - **`filter`** (str): Filter out messages before sending on the CAN bus. Multiple filters can be specified if separated using comma characters.
    - `+[id][#][data]`: Include only messages matching string.
    - `-[id][#][data]`: Exclude messages matching string.
    - `+duplicate`: Include only messages where duplicates exist.
    - `-duplicate`: Exclude messages where duplicates exist.
    - `+mutate`: Include only messages where data mutates.
    - `-mutate`: Exclude messages where data mutates.
  - **`group`** (str): How to group the result of sent messages. This only affects the display values returned from this command. Default value is `id`.
    - `id`: Group by message ID only.
    - `msg`: Group by entire message string.
  - **`protocol`** (str): ID of specific protocol to be used to send the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`auto_format`** (bool): Apply automatic formatting of messages? Default value is `False`.
  - **`test`** (bool): Run command in test-only? (dry-run) mode. No data will be sent on CAN bus. Default value is `False`.

----
## `obd.protocol`

Configures protocol or lists all supported.

**OPTIONAL ARGUMENTS**

  - **`set`** (str): Change to protocol with given identifier.
  - **`baudrate`** (int): Use custom protocol baudrate. 
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.

**EXAMPLES**

  - `obd.protocol`
  - `obd.protocol set=auto`
  - `obd.protocol set=6`
  - `obd.protocol set=53 baudrate=250000`

----
## `obd.query`

Queries a given OBD command. To see supported OBD commands for your vehicle run: `obd.commands`

**ARGUMENTS**

  - **`name`** (str): Name of the command.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`mode`** (str): Service section of the PID.
  - **`pid`** (str): Code section of the PID.
  - **`header`** (str): Identifer of message to send. If none is specifed the default header will be used.
  - **`bytes`** (int): Byte size of individual returned frame(s). Default value is `0`.
  - **`frames`** (int): Expected frame count to be returned?
  - **`strict`** (int): Enforce strict validation of specified `bytes` and/or `frames`. Default value is `False`.
  - **`decoder`** (str): Specific decoder to be used to process the response.
  - **`formula`** (str): Formula written in Python to convert the response.
  - **`unit`** (str): Unit of the result.
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`force`** (bool): Force query of unknown command. Default is `False`.
  - **`type`** (str): Specify an alternative name of the type of the result. Default is the given name of the command.

**OPTIONAL ARGUMENTS, CAN SPECIFIC**

  - **`can_extended_address`** (str): Use CAN extended address.
  - **`can_priority`** (str): Set CAN priority bits of a 29-bit CAN ID.
  - **`can_flow_control_clear`** (bool): Clear all CAN flow control filters and ID pairs before adding any new ones.
  - **`can_flow_control_filter`** (str): Ensure CAN flow control filter is added. Value must consist of `<Pattern>,<Mask>`.
  - **`can_flow_control_id_pair`** (str): Ensure CAN flow control ID pair is added. Value must consist of `<Transmitter ID>,<Receiver ID>`.

**OPTIONAL ARGUMENTS, J1939 SPECIFIC**

  - **`j1939_pgn_filter`** (str): Ensure J1939 PGN filter is added. Value must consist of `<PGN>[,<Target Address>]`.

**EXAMPLES**

  - `obd.query RPM`
  - `obd.query SPEED`
  - `obd.query FUEL_LEVEL force=True`
  - `obd.query custom_intake_temp_raw mode=01 pid=0F`
  - `obd.query custom_intake_temp mode=01 pid=0F decoder=temp`

----
## `obd.query_many`

Queries many OBD commands in one call.

For details, check out the `obd_manager.query_many_handler` documentation

----
## `obd.recordings`

Lists all dumped recordings available on disk.

----
## `obd.send`

Sends a message on bus.

**ARGUMENTS**

  - **`msg`** (str): Message to send.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`header`** (str): Identifer of message to send. If none is specifed the default header will be used.
  - **`auto_format`** (bool): Apply automatic formatting of messages? Default value is `False`.
  - **`auto_filter`** (bool): Ensure automatic response filtering is enabled. Default value is `True` if no custom filters have be added.
  - **`expect_response`** (bool): Wait for response after sending? Avoid waiting for timeout by specifying the exact the number of frames expected. Default value is `False`.
  - **`format_response`** (bool): Format response frames by separating header and data with a hash sign. Default value is `False`.
  - **`raw_response`** (bool): Get raw response without any validation nor parsing? Default value is `False`.
  - **`echo`** (bool): Include the request message in the response? Default value is `False`.
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`output`** (str): What data type should the output be returned in? Default is a `list`.
  - **`type`** (str): Specify a name of the type of the result. Default is `raw`.

**OPTIONAL ARGUMENTS, CAN SPECIFIC**

  - **`can_extended_address`** (str): Use CAN extended address.
  - **`can_priority`** (str): Set CAN priority bits of a 29-bit CAN ID.
  - **`can_flow_control_clear`** (bool): Clear all CAN flow control filters and ID pairs before adding any new ones.
  - **`can_flow_control_filter`** (str): Ensure CAN flow control filter is added. Value must consist of `<Pattern>,<Mask>`.
  - **`can_flow_control_id_pair`** (str): Ensure CAN flow control ID pair is added. Value must consist of `<Transmitter ID>,<Receiver ID>`.

**OPTIONAL ARGUMENTS, J1939 SPECIFIC**

  - **`j1939_pgn_filter`** (str): Ensure J1939 PGN filter is added. Value must consist of `<PGN>[,<Target Address>]`.

----
## `obd.setup`

Setup advanced runtime settings.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`print_spaces`** (bool): Turn printing of spaces in OBD responses on or off. To get better performance, turn spaces off.
  - **`adaptive_timing`** (int): Set adaptive timing mode. Sometimes, a single OBD requests results in multiple response frames. The time between frames varies significantly depending on the vehicle year, make, and model - from as low as 5ms up to 100ms. Default value is `1` (on, normal mode).
  - **`response_timeout`** (int): When adaptive timing is on, this sets the maximum time that is to be allowed, even if the adaptive algorithm determines that the setting should be longer. In most circumstances, it is best to let the adaptive timing algorithm determine what to use for the timeout. Default value is `50` x 4ms giving a time of approximately 200ms.
  - **`auto_filter`** (bool): Ensure automatic response filtering is enabled.

**OPTIONAL ARGUMENTS, CAN SPECIFIC**

  - **`can_extended_address`** (str): Use CAN extended address.
  - **`can_priority`** (str): Set CAN priority bits of a 29-bit CAN ID.
  - **`can_flow_control_clear`** (bool): Clear all CAN flow control filters and ID pairs before adding any new ones.
  - **`can_flow_control_filter`** (str): Ensure CAN flow control filter is added. Value must consist of `<Pattern>,<Mask>`.
  - **`can_flow_control_id_pair`** (str): Ensure CAN flow control ID pair is added. Value must consist of `<Transmitter ID>,<Receiver ID>`.

**OPTIONAL ARGUMENTS, J1939 SPECIFIC**

  - **`j1939_pgn_filter`** (str): Ensure J1939 PGN filter is added. Value must consist of `<PGN>[,<Target Address>]`.

----
## `obd.status`

Gets current status information.

---

## Openocd

## `openocd.help`

Shows this help information.

----
## `openocd.program`

Loads a program onto a MCU.

**ARGUMENTS**

  - **`file`** (str): Path of program binary file.
  - **`interface_cfg`** (str): Path of interface configuration file.
  - **`target_cfg`** (str): Path of target configuration file.

**OPTIONAL ARGUMENTS**

  - **`raise_on_error`** (bool): Raise an error upon failure. Default is `True`.
  - **`start_address`** (string): Flash memory start address in hex format (required for .bin files)

---

## Power(Commands)

## `power.help`

Shows this help information.

----
## `power.hibernate`

Power down system and put device into hibernate state.

**OPTIONAL ARGUMENTS**

  - **`delay`** (str): Delay in seconds before powering down. Default is `60`.
  - **`confirm`** (bool): Acknowledge the execution of this command. Default is `False`.
  - **`reason`** (str): Reason code that tells why we decided to hibernate. Default is `unknown`.

----
## `power.reboot`

Reboot system immediately.

**OPTIONAL ARGUMENTS**

  - **`reason`** (str): Reason code that tells why we decided to reboot. Default is `unknown`.

----
## `power.request_reboot`

Request for a future system reboot.

**OPTIONAL ARGUMENTS**

  - **`pending`** (bool): Default is `True`.
  - **`immediately`** (bool): Default is `False`.
  - **`reason`** (str): Reason code that tells why we decided to reboot. Default is `unknown`.

----
## `power.restart_3v3`

Restart the 3V3 power supply. This will restart the modem and also the accelerometer the hard way.

WARNING: Any open serial connections to the modem (eg. in ec2x_manager and tracking_manager) may cause the system to freeze or block the TTYs and make new numbering after modem is re-initialized. It is recommended to use `ec2x.power_off` to restart modem.

**OPTIONAL ARGUMENTS**

  - **`confirm`** (bool): Acknowledge the execution of this command. Default is `False`.
  - **`reason`** (str): Reason code that tells why the 3V3 supply is restarted. Default is `unknown`.

----
## `power.sleep`

Power down system and put device into sleep state.

**OPTIONAL ARGUMENTS**

  - **`interval`** (int): Sleep interval in seconds. Default is `60`.
  - **`delay`** (str): Delay in seconds before powering down. Default is `60`.
  - **`modem_off`** (bool): Power off 3V3 supply to modem on mPCIe slot. Default is `False`.
  - **`acc_off`** (bool): Put accelerometer into standby. Default is `False`.
  - **`confirm`** (bool): Acknowledge the execution of this command. Default is `False`.
  - **`reason`** (str): Reason code that tells why we decided to sleep. Default is `unknown`.

----
## `power.sleep_timer`

Setup sleep timer to schedule power off upon inactivity.

:::note
Do not access pillar data in this function as they will not be available when called from engines (separate processes).
:::

**OPTIONAL ARGUMENTS**

  - **`add`** (str): Add a timer with the given name.
  - **`clear`** (str): Clear sleep timer(s) matching the given name. Use `*` to clear all.
  - **`enable`** (bool): Enable or disable timer. __DEPRECATED__: Use `add` or `clear` instead.
  - **`period`** (int): Timer period in seconds before performing sleep. Default is `1800`.
  - **`reason`** (str): Reason code that tells why we decided to sleep. Default is `unknown`.

----
## `power.status`

Get status and debug information regarding power management.

---

## Qmi

## `qmi.cell_info`

Get cell location info.

----
## `qmi.connection_stats`

Get packet statistics.

----
## `qmi.connection_status`

Get packet service status.

----
## `qmi.help`

Shows this help information.

----
## `qmi.home_network`

Get home network.

----
## `qmi.operator_name`

Get operator name data.

----
## `qmi.serving_system`

Get serving system.

----
## `qmi.signal_strength`

Get current signal strength values.

**OPTIONAL ARGUMENTS**

  - **`rated_only`** (bool): Default is `False`.
  - **`include_desc`** (bool): Default is `True`.

----
## `qmi.system_info`

Get system info.

---

## Reactor

## `reactor.cache`

Queries or manipulates cache of event reactor.

----
## `reactor.context`

:::warning
**DEPRECATED**
Use 'manage context' instead.
:::
Queries or manipulates context of event reactor.

----
## `reactor.help`

Shows this help information.

----
## `reactor.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `reactor.manage hook list`
  - `reactor.manage worker list *`
  - `reactor.manage worker show *`
  - `reactor.manage worker start *`
  - `reactor.manage worker pause *`
  - `reactor.manage worker resume *`
  - `reactor.manage worker kill *`
  - `reactor.manage reactor list`
  - `reactor.manage reactor show *`

---

## Rfid(Commands)

## `rfid.load_settings`

Read the settings file stored in /opt/autopi/rfid/settings.yaml and load it.

----
## `rfid.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`
  - `context [key]... [value=<value>]`

**EXAMPLES**

  - `rfid.manage hook list`
  - `rfid.manage hook call power`
  - `rfid.manage worker list *`
  - `rfid.manage worker show *`
  - `rfid.manage worker start *`
  - `rfid.manage worker pause *`
  - `rfid.manage worker resume *`
  - `rfid.manage worker kill *`
  - `rfid.manage reactor list`
  - `rfid.manage reactor show *`
  - `rfid.manage context`
  - `rfid.manage context <context_key>`

---

## Rpi

## `rpi.boot_time`

Get timestamp for last boot of system.

----
## `rpi.default_interface`

Get default internet interface stats

----
## `rpi.help`

Shows this help information.

----
## `rpi.hw_serial`

Get hardware serial.

----
## `rpi.memory`

Get memory stats

----
## `rpi.ping`

Try pinging url with `<count>` packets of `<packet_size>` bytes

----
## `rpi.salt_pub_connection`

Get connection status to Salt`s publishing service (port 4505)

----
## `rpi.salt_req_connection`

Get connection status to Salt`s request service (port 4506)

----
## `rpi.stats`

Get system and connection stats.

----
## `rpi.temp`

Current temperature readings.

----
## `rpi.temp_cpu`

Current temperature of the ARM CPU.

----
## `rpi.temp_gpu`

Current temperature of the GPU.

----
## `rpi.throttled`

Get throttled flags.

----
## `rpi.uptime`

Get system uptime in seconds

---

## Socketcan

## `socketcan.down`

Bring down CAN interface.

**OPTIONAL ARGUMENTS**

  - **`interface`** (str): CAN interface. Default is `can0`.

----
## `socketcan.dump`

Run CAN dump.

**EXAMPLE** `socketcan.dump can0,18F00000:1FF00000`

----
## `socketcan.help`

Shows this help information.

----
## `socketcan.show`

Show current information for CAN interface.

**OPTIONAL ARGUMENTS**

  - **`interface`** (str): CAN interface. Default is `can0`.
  - **`details`** (bool): Include details. Default is `False`.
  - **`stats`** (bool): Include statistics. Default is `False`.

----
## `socketcan.up`

Bring up CAN interface.

**OPTIONAL ARGUMENTS**

  - **`interface`** (str): CAN interface. Default is `can0`.
  - **`bitrate`** (int): Default is `500000`.
  - **`dbitrate`** (int): CAN-FD data bitrate.
  - **`listen_only`** (bool): Only receive and not transmit CAN messages. Default is `False`.

---

## Spm

## `spm.battery`

Gets current battery voltage

----
## `spm.flash_firmware`

Flashes new SPM firmware to the MCU.

----
## `spm.fuse`

Manages the fuse of the MCU.

----
## `spm.help`

Shows this help information.

----
## `spm.led_pwm`

Change PWM frequency and/or duty cycle for LED.

**OPTIONAL ARGUMENTS**

  - **`frequency`** (float): Change to frequency in Hz.
  - **`duty_cycle`** (float): Change to duty cycle in percent.

----
## `spm.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `spm.manage hook list`
  - `spm.manage hook call query_handler status`
  - `spm.manage worker list *`
  - `spm.manage worker show *`
  - `spm.manage worker start *`
  - `spm.manage worker pause *`
  - `spm.manage worker resume *`
  - `spm.manage worker kill *`
  - `spm.manage reactor list`
  - `spm.manage reactor show *`
  - `spm.manage run handler="query" args="[\"status\"]"`

----
## `spm.query`

Queries a given SPM command.

**ARGUMENTS**

  - **`cmd`** (str): The SPM command to query.

----
## `spm.reset`

Reset/restart the MCU.

---

## Stateutil

## `stateutil.call_error_safe`

Calls a salt module function safely - if an error occurs it will be added as an error in the response.

---

## Stn

## `stn.ext_sleep`

External sleep trigger configuration.

----
## `stn.ext_wake`

External wake trigger configuration.

----
## `stn.help`

Shows this help information.

----
## `stn.power_config`

Summarizes active PowerSave configuration.

----
## `stn.power_pin_polarity`

Specify whether the pin outputs a logic LOW or HIGH in low power mode.

----
## `stn.power_trigger_status`

Reports last active sleep/wakeup triggers since last reset.

----
## `stn.sleep`

Enter sleep mode after the specified delay time.
The OBD connection is closed as default in order to prevent STN wake up on UART communication.

----
## `stn.uart_sleep`

UART inactivity timeout configuration.

----
## `stn.uart_wake`

UART wakeup pulse timing configuration.

----
## `stn.volt_calibrate`

Manual calibration of voltage measurement.
Default value `0000` will restore to the factory calibration.

**OPTIONAL ARGUMENTS**

  - **`value`** (int): The value to set the calibration to. Default is 0000.
  - **`confirm`** (bool): Achknowledge the execution of this command. Default is `False`.

----
## `stn.volt_change_wake`

Voltage change wakeup trigger configuration.

----
## `stn.volt_level`

Determine the current voltage level.

----
## `stn.volt_level_sleep`

Voltage level sleep trigger configuration.

----
## `stn.volt_level_wake`

Voltage level wakeup trigger configuration.

---

## Time

## `time.help`

Shows this help information.

----
## `time.ntp`

Enable or disable network time synchronization.

**OPTIONAL ARGUMENTS**

  - **`enable`** (bool): Default is `True`.

----
## `time.set`

Set system time.

**ARGUMENTS**

  - **`value`** (str): Time string to set.

**OPTIONAL ARGUMENTS**

  - **`adjust_system_clock`** (bool): Default is `False`.

----
## `time.status`

Show current time settings.

---

## Tracking(Commands)

## `tracking.context`

:::warning
**DEPRECATED**
Use 'manage context' instead.
:::
Gets current context.

----
## `tracking.help`

Shows this help information.

----
## `tracking.load_geofences`

Loads geofences.
**OPTIONAL ARGUMENTS**

  - `path` path to the geofences file

----
## `tracking.manage`

Runtime management of the underlying service instance.

**SUPPORTED COMMANDS**

  - `hook list|call <name> [argument]... [<key>=<value>]...`
  - `worker list|show|start|pause|resume|kill <name>`
  - `reactor list|show <name>`
  - `run <key>=<value>...`

**EXAMPLES**

  - `tracking.manage hook list`
  - `tracking.manage hook call gnss_query_handler location`
  - `tracking.manage worker list *`
  - `tracking.manage worker show *`
  - `tracking.manage worker start *`
  - `tracking.manage worker pause *`
  - `tracking.manage worker resume *`
  - `tracking.manage worker kill *`
  - `tracking.manage reactor list`
  - `tracking.manage reactor show *`
  - `tracking.manage run handler="gnss_query" args="[\"location\"]" converter="gnss_location_to_position" returner="cloud"`

----
## `tracking.status`

Gets current status.

---

## Usbutil

## `usbutil.check_expected_devices`

Triggers `system/usb/<vendor>/<product>/not_connected` events when specified (must be present) devices
are missing, i.e. not seen for whatever reason when running the `usbutil.devices` command.

----
## `usbutil.devices`

Returns the lsusb bash command result as a list of dictionaries, each dict is a separete device.
An example dict structure is presented below:

- bus: `001`                          # the linux system bus number
device: `001`                       # the linux system device number
name: Linux Foundation 2.0 root hub # the name of the device
product: `0002`                     # the product number (hex) of the device
vendor: 1d6b                        # the vendor number (hex) of the device

----
## `usbutil.devices_changed_trigger`

Triggers `system/usb/<vendor>/<product>/connected` and `system/usb/<vendor>/<product>/disconnected`
events when USB devices are connected or disconnected.

Expects the result to be in the format as `usbutil.devices` return format.

----
## `usbutil.help`

Shows this help information.

---

## Wifi(Commands)

## `wifi.help`

Shows this help information.

----
## `wifi.scan`

Give the list of Access Points and Ad-Hoc cells in range.

**OPTIONAL ARGUMENTS**

  - **`interface`** (str): Default is `wlan0`.

----
## `wifi.status`

Get current WPA/EAPOL/EAP status.

**OPTIONAL ARGUMENTS**

  - **`interface`** (str): Default is `wlan0`.

---

## Introduction(4)

This section explores the [AutoPi](https://www.autopi.io) Core system, which is one part of the [AutoPi](https://www.autopi.io) platform. The [AutoPi](https://www.autopi.io)
Core is an open-source software running on the hardware device. It is built on [salt stack](https://saltproject.io/).

## What is [AutoPi](https://www.autopi.io) Core?
The [AutoPi](https://www.autopi.io) Core is a system that runs on the [AutoPi](https://www.autopi.io) device. It includes a vast range of
functionalities such as services that manage different components in the device. For example,
there is the [OBD service](/core/services/obd_manager.md), which controls how the device communicates
with the OBD-II port of your vehicle. There is also the [tracking service](/core/services/tracking_manager.md),
which controls the GPS modem inside the device.

  

There are also many modules that provide a single execution commands that help to manage or work
with the device. Modules are separated by functionality, for example, the [OBD module](/core/commands/obd.md)
provides commands that work with the OBD-II port of your vehicle, just like the OBD service
mentioned above. The [ec2x module](/core/commands/ec2x.md) has commands to manage the Quectel 4G/GPS
modem.

## Get Your Device Today and Get Started!

  

[![](/img/hardware/autopi_mini/AutoPi_Mini_5_Top_right.png) **AutoPi Mini** Build for fleet volume scaling and ease of install. CAN bus ready with support for legacy protocols. Support wide range of OEM Parameters. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-mini)

[![](/img/hardware/autopi_tmu_cm4/TMU_Floating_Topside_V1_scaled.png) **AutoPi TMU CM4** Based on Raspberry Pi Compute Module 4. Best for custom solutions requiring large computation power and expansion options. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-telematics-unit-cm4-4g-lte-edition)

[![](/img/hardware/autopi_canfd_pro/canfd_pro_trans.png) **AutoPi CAN-FD Pro** Based on Raspberry Pi Compute Module 4. Our most powerful device to date, designed for full speed automotive datalogging of dual CAN-FD channels. See price.](https://shop.autopi.io/products/autopi-can-fd-pro)

[![](/img/shared/autopi_devices_trans.png) **Comparison of all AutoPi devices** Compare our devices and find the best fit for your requirements.](https://www.autopi.io/hardware/compare/)

---

## High-level

:::note
It is recommended to have an understanding of the [low-level](/core/power_management/low_level.md) power cycle before continuing.
:::

## Commands

See all the available power commands [here](/core/commands/power.md).

## Configuration

See all the available power configuration options [here](/cloud/device_management/advanced_settings/autopi_tmu_cm4/power.md).

## Events

See all the available power events [here](/cloud/device_management/events/system.md#power-events).

---

## Introduction(5)

:::tip
For power cycle, LED and button information on the [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4), please see [configuration here](/hardware/autopi_tmu_cm4/led_and_button.mdx)
:::

The power management of the device consists of a low- and high-level layer. For further details please see: 

1. [Low-level](/core/power_management/low_level.md)
1. [High-level](/core/power_management/high_level.md)

## Power Cycle
Overall, there are three states that the device can be in:

* On
* Sleeping
* Hibernating

#### On
The `On` state is when the device is awake and performing work. It will record data, communicate with the [Cloud](https://www.autopi.io/software-platform/cloud-management) or do whatever it has been configured to do.
Eventually, when the vehicle has turned off, a sleep timer is scheduled that will shut down the device and go to sleep in order to conserve power. This sleep timer puts the device into the `Sleeping` state.

#### Sleeping
The `Sleeping` state is a state where the device is powered off for a certain period of time. Before the device goes to sleep, there is always setup
an interval until it will wake up again ([configuration here](/cloud/device_management/advanced_settings/autopi_tmu_cm4/cloud-config-power/#sleep-timer)). When the [`Modem > Power Save`](/cloud/device_management/advanced_settings/autopi_tmu_cm4/cloud-config-power/#modem) option is disabled, the modem is kept powered on while sleeping. This makes it possible to wake the device by sending an SMS to it, if it is within mobile network range.

There are generally two reasons for a device to go to the `On` state while sleeping:
1. **The vehicle's engine turns on.** More precisely, the vehicle's battery voltage raises above a [specified threshold](/cloud/device_management/advanced_settings/autopi_tmu_cm4/cloud-config-power/#wake-trigger).
2. **The sleep timer's sleep period passes.** When the device goes to sleep, a wake timer is being setup based on the inactivity setting.

We will take a look at example scenarios which will further describe the power cycle of the device.

#### Hibernating
The `Hibernating` state is the last effort the device will do in order to preserve your vehicle's battery. It will shut off almost all
of the functionalities of the [AutoPi](https://www.autopi.io) leaving only one power-cheap component on - a chip that will detect a raise in the battery's
voltage so that it can trigger an `On` state. This will happen when the vehicle is powered on, so this is the moment the battery will
start to charge up again.

### Walk-Through

Let us now walk through an example of the power cycle. We will begin with the device being unplugged and the vehicle's engine not running.
If we plug in a device in the vehicle's OBD-II port the following steps will occur:

1. The device will start booting
2. After some time, bootup process will finish and device will appear online on the [Cloud](https://www.autopi.io/software-platform/cloud-management)
3. A sleep timer will be setup (that will expire after 5 minutes by default)
4. When the sleep timer expires, three things will happen:
    1. A wake up timer will be setup on the hardware level
    2. The device will attempt to upload pending data to the [Cloud](https://www.autopi.io/software-platform/cloud-management)
    3. The device will start its shutdown procedure
5. Device is now sleeping

By default, a sleep timer will introduce a wake-up timer that is in 2 hours after the device goes to sleep. So let's now take a look
at what happens with this:

1. Wake-up timer expires
2. Device will start its boot process
3. After boot, device will appear online on the [Cloud](https://www.autopi.io/software-platform/cloud-management)
4. A new sleep timer will be setup (5 minutes by default)
5. When the sleep timer expires, three things happen:
    1. A wake up timer will be setup on the hardware level
    2. The device will attempt to upload any pending data to the [Cloud](https://www.autopi.io/software-platform/cloud-management)
    2. The device will start its shutdown procedure
5. Device is now sleeping

It is more or less the same procedure. This means that by default, your device will wake up every two hours, setup a sleep timer for 5
minutes and go back to sleep. In the time that the device is `On` it will try to read data off of the CAN bus from the vehicle, record
it and report any data or events it needs to report to the [Cloud](https://www.autopi.io/software-platform/cloud-management). Now, what happens if the vehicle is being driven? Let's assume that
the device is asleep at the moment that the engine of the vehicle gets turned on. Here's what will happen:

1. The STN chip will detect the higher voltage reading
2. The STN chip will send a wake-up request to the device
3. The device will boot up
4. After boot, the device will appear online on the [Cloud](https://www.autopi.io/software-platform/cloud-management)
5. Device will detect CAN bus traffic, more specifically RPM values (only works by default on standard ICE vehicles)
6. The RPM values will trigger an event called `vehicle/engine/running`
7. All sleep timers are cleared and sleep timers are no longer allowed to be set

Almost the same process will occur if the device is already awake with the exception that it won't need to actually boot up again.
Instead, the device will stay awake, current sleep timers will be cleared and new sleep timers won't be able to be set.

So now you may be wondering, when exactly does the device go into hibernation, or maybe what even is the hibernation state?
Hibernation is a state where the device sees that the battery is very low on power and will shut down completely, leaving only
a very power-cheap device which will wake the device up again when the battery level raises to normal values. This mode is necessary
as without it, the [AutoPi](https://www.autopi.io) can potentially drain the battery so low that the vehicle won't be able to start up the next time, or
even worse - permanently damage the battery. So, in essence, hibernation is a last resort effort of the [AutoPi](https://www.autopi.io) to protect the battery
of the vehicle.

There are two settings that you can tweak on the [Cloud](https://www.autopi.io/software-platform/cloud-management) in the Advanced > Settings > Power section: `Critical Level` and `Safety Cut-Out`.
They both make the device go to hibernation, however they differ on one key point - Critical Level will still shut down the device
gracefully, while Safety Cut-Out will essentially pull the plug on it. The difference is that with a graceful shutdown the [Cloud](https://www.autopi.io/software-platform/cloud-management) will
(*likely*\*) receive an event that will be reported. With Safety Cut-out, this won't happen, there will only be a notification the next
time the device gets online.

:::note
\**likely* - If the device doesn't have access to the internet for whatever reason (no WiFi connection, no 4G/LTE enabled, or there is no
coverage at the current moment) the event will not be sent to the [Cloud](https://www.autopi.io/software-platform/cloud-management) even if it went to hibernation due to the Critical Level threshold.
:::

As long as the battery doesn't go below the Voltage threshold that are set on those two settings (`Critical Level` and `Safety Cut-Out`)
your device will wake up occasionally to check up on if it needs to do something or not. If there is nothing to do, it will go back to
sleep after the sleep timer is triggered.

:::caution
For OBD-II non-compliant vehicles additional configuration may be required to ensure a well-functioning power cycle.
For EVs please see this [guide](/getting_started/electric_vehicles/power-cycle-for-electric-vehicles/).
:::

## Status LEDs

:::note
Status LEDs are only available on the [AutoPi](https://www.autopi.io) Telematics Unit.
:::

### Blue LED

The blue LED indicates the current state of the [low-level ](/core/power_management/low_level.md) SPM system.

| LED State | Description |
| ------ | ------ |
| Turned off | SPM is in [OFF](/core/power_management/low_level.md#off) state. |
| Flashing brightly | SPM is in [BOOTING](/core/power_management/low_level.md#booting) state. |
| Constantly bright | SPM is in [ON](/core/power_management/low_level.md#on) state. |
| Breathing effect | SPM is in [SLEEPING](/core/power_management/low_level.md#sleeping) state. |
| Constantly dimmed | SPM is in [HIBERNATING](/core/power_management/low_level.md#hibernating) state. |

### Green LED

The green LED indicates the current state of the [high-level](/core/power_management/high_level.md) system.

| LED State | Description |
| ------ | ------ |
| Turned off | Not running or in the process of booting up. |
| Flashing brightly | Up and running but NOT (yet) connected to the [Cloud](https://www.autopi.io/software-platform/cloud-management). |
| Constantly bright | Up and running and connected to the [Cloud](https://www.autopi.io/software-platform/cloud-management). |

---

## Low-level

## SPM

The SPM (Smart Power Management) is an embedded system that controls the low-level power cycle of the device. It interacts with a number of subsystems that can initiate power state changes:

| Subsystem | Description |
| ------ | ------ |
| Accelerometer | Built-in accelerometer is capable of triggering wake up based on physical movement events. |
| Modem | Installed modem module can trigger wake up on received SMS or dial up call. |
| [STN](#stn) | Built-in chipset triggers power on and off based on voltage level changes. |

Finally the Raspberry Pi communicates directly with the SPM and performs power state changes based on more [high-level](/core/power_management/high_level.md) decisions.  

### States

Below diagram shows an overview of all possible SPM states and the transitions between.

#### OFF

Everything is powered off.

##### Transitions

| State | Condition |
| ------ | ------ |
| [BOOTING](#booting) | The device is plugged in. |
| [HIBERNATING](#hibernating) | Maximum number of boot attempts reached. Default is 10 attempts. |

#### BOOTING

Everything is powered on and the Raspberry Pi is booting up.

##### Transitions

| State | Condition |
| ------ | ------ |
| [ON](#on) | Successfully communicated with the Raspberry Pi. |
| [OFF](#off) | No communication with the Raspberry Pi within a given time limit. Default boot timeout is 10 minutes. |

#### ON

Everything is powered on and there is regular communication with the Raspberry Pi.

##### Transitions

| State | Condition |
| ------ | ------ |
| [SLEEPING](#sleeping) | The Raspberry Pi decided to sleep for a given period of time. |
| [HIBERNATING](#hibernating) | The Raspberry Pi decided to hibernate or the STN chip powered off according to its triggers. |
| [OFF](#off) | No communication with the Raspberry Pi within a given time limit. Default heartbeat timeout is 3 minutes. |

#### SLEEPING

The Raspberry Pi is powered off. Modem and GPS is kept on in low power mode.

Wake up will happen after a specified period of sleep time or earlier if:

  - STN is powered on.
  - Received wake signal from modem.
  - Received wake signal from accelerometer.

##### Transitions

| State | Condition |
| ------ | ------ |
| [BOOTING](#booting) | See the above criteria. |

#### HIBERNATING

Everything is shut down for maximum power saving.

##### Transitions

| State | Condition |
| ------ | ------ |
| [BOOTING](#booting) | The STN powers on (when transitions from off to on). |

## STN

See the STN command for available power trigger options [here](core/commands/stn.md).

---

## Sleep Timers

---

Sleep timers are a functionality built into the [AutoPi](https://www.autopi.io) who's purpose is to protect the battery of your vehicle by
limiting the amount of power required by the device when it's plugged into a vehicle. On this page, we will explore how
you can work with the sleep timers using a command and look over some of the configuration options that are available
to manipulate how sleep timers are added and cleared from the device.

:::note
Regarding the sleep timers, the device will automatically configure them to help protect your vehicle’s battery. However, this behavior is fully configurable. You can adjust the sleep timer settings by navigating to: Devices → pick the device → Advanced Settings → Power. There, you’ll find all related power and sleep configurations.
:::

## The `power.sleep_timer` Command

Let us start by going through the command that you can use to view, set and clear sleep timers. The command is
[`power.sleep_timer`](core/commands/power.md#powersleep_timer). If you execute the command on its own, it will return
the currently set sleep timers on the device:

```bash
user@my_device $ power.sleep_timer 
_sleep_timer/inactivity_fallback:
  function: power.sleep
  _stamp: '2023-05-08T09:26:57.353790'
  name: _sleep_timer/inactivity_fallback
  seconds: 10800
  enabled: true
  job_args: []
  return_job: false
  jid_include: true
  maxrunning: 1
  job_kwargs:
    delay: 60
    reason: inactivity_fallback
    interval: 21600
    confirm: true
  metadata:
    transient: true
    revision: 2
    expires: '2023-05-08T12:25:13.961144'
    created: '2023-05-08T09:25:13.961144'
```

In the code snippet above, we can see that there is a sleep timer currently set for `my_device` - the
`_sleep_timer/inactivity_fallback` sleep timer. That sleep timer will expire at `2023-05-08T12:25:13.961144` - note
that this timestamp is in UTC, as are all timestamps generated by an [AutoPi](https://www.autopi.io) device. The `expires` key shows the moment
in time when the device will initiate its "Going to sleep" sequence.

To clear all sleep timers, we can use the command together with the `clear` keyword argument, like so:

```bash
user@my_device $ power.sleep_timer clear=*
{}
```

We are also able to clear sleep timers based on their name. For example, we have the `_sleep_timer/inactivity_fallback`
sleep timer above. Note that the actual name of the sleep timer in this example is `inactivity_fallback`, omitting the
`_sleep_timer/` part. Now, we can execute the command like below, to clear that specific sleep timer:

```bash
user@my_device $ power.sleep_timer clear=inactivity_fallback
{}
```

If we run the `power.sleep_timer` command on it's own and it returns an empty response like below, that means there
are no sleep timers currently set on the device:

```bash
user@my_device $ power.sleep_timer
{}
```

If you don't see any sleep timers set, that means the device won't go down to sleep. Or at least, until a new sleep
timer is set. A new sleep timer can be set in different situations, based on the configuration of the device, but it's
important to remember that there could be new sleep timers set, even if you clear all current timers. Usually, this
happens only when the device detects that a trip with a vehicle has ended, using the Event Driven sleep timer (we will
explore that a little later).

## Configuration Options

Now, it's time for us to look through how we can configure the automatic sleep timers of the [AutoPi](https://www.autopi.io). We will explore
first how to automate setting of sleep timers (i.e. when the device should go to sleep and for how long). Then, we will
also look into how we can automate the clearing of sleep timers.

:::note
You can see all available power configuration options [here](/cloud/device_management/advanced_settings/autopi_tmu_cm4/power.md).
:::

### Power > Sleep Timer

The [sleep timer](/cloud/device_management/advanced_settings/autopi_tmu_cm4/power.md#sleep-timer) section of the Advanced Power settings allows you to
configure how the device behaves in terms of setting and clearing sleep timers automatically. The `Event Driven`,
`Inactivity After Sleep` and `Inactivity Fallback` settings configure how the device goes to sleep, while the `Suppress`
section configures the device on how to stay awake.

#### Setting Sleep Timers

Firstly, let's take a look at the settings that set sleep timers.
The common settings amongst all of them are the following:

- **Period** - The period defines how long the device will stay awake for before going to sleep due to this sleep timer.
- **Interval** - The interval defines the amount of time the device will sleep for, due to this sleep timer.
- **Delay** - The delay is the amount of time to wait before going to sleep. The delay is applied after the period has
  expired, but before the device actually powers off.

Now, let's discuss the functionalities each one brings to the table:

- **Event Driven** - The `Even Driven` sleep timer get's set when the event defined in its `Event Regex` option is
  triggered by the device. This event can either be one of the default ones (like
  [Engine events](/cloud/device_management/events/vehicle.md#engine-events) such as `vehicle/engine/stopped` or
  [Communication events](/cloud/device_management/events/vehicle.md#communication-events) such as `vehicle/communication/disconnected`).
  The purpose of this sleep timer is to put the device to sleep when we have detected that the vehicle is no longer
  being used (hence the engine/stopped instead of engine/running, which we will see in the suppress settings further
  down).

- **Inactivity After Sleep** - The `Inactivity After Sleep` sleep timer get's set when the device wakes up and does not
  see the event defined in the *Suppress > Event Regex* configuration (explained in next section). This sleep timer is
  usually set when the device wakes up from its sleep due to an expired `Interval`, but the vehicle the device is
  plugged into isn't on or running.

- **Inactivity Fallback** - The `Inactivity Fallback` sleep timer get's set when the device has been freshly plugged
  into a power source, the event defined in the `Event Driven` regex isn't seen and the suppress event hasn't been
  triggered in this power cycle. In essence it works exactly the same as the `Inactivity After Sleep` sleep timer,
  however is only triggered upon first plugging in the device into power.

#### Suppressing Sleep Timers

Now, let's explore the `Suppress` section of the Advanced Power settings. This section defines how the device will
clear and suppress further sleep timers from putting the device to sleep. There's two options available in this
section - `Event Regex` and `Schedule`.

##### `Event Regex`

Let's start with the `Event Regex`. This option allows you to set a regex pattern that will be matched against every
event that get's triggered inside the device. What this allows us to do is to set a specific event, that when triggered,
will clear all sleep timers that have been setup on the device. It also prevents new sleep timers from being set until
another event is seen (specifically, the `Event Regex` from the `Event Driven` sleep timer).

Common examples here are using the opposite events from the `Event Driven` sleep timer:
[Engine events](/cloud/device_management/events/vehicle.md#engine-events) like `vehicle/engine/started` or
[Communication events](/cloud/device_management/events/vehicle.md#communication-events) like `vehicle/communication/established`. Note that
here, we are looking for an event that shows the vehicle is now being driven, so we want to clear the sleep timers as
we don't want the device to go to sleep, but instead record all of our data.

##### `Schedule`

Next, we have the `Schedule` option. That option allows us to setup a schedule for the device for when it should be
awake and how long it should be awake for. This option is useful for situations where you need the device to be awake
at specific times of the day and stay awake for the necessary duration. The way this setting is defined is by writing
a cron expression, then the pipe sign (`|`), followed by the amount of time the device should be awake for in seconds.
Let's go through an example:

```
0 9 9 5 * | 3600
```

If we grab just the `0 9 9 5 *` part, which is the cron expression and paste it into a crontab resolver, we will find
that this expression will be executed on 9th May at 9:00 AM in UTC time. Remember that the devices are all working in
UTC, so this (suppress) expression will also be resolved in UTC. Next, the `3600` portion says that the device will
stay awake starting at that time for 1 hour in the future.

This means that the device will be woken up at the appropriate time and then any sleep timers that are added to the
device will be adjusted to ensure the device will be awake for the desired duration. For example, suppose we have set
the suppress schedule to keep the device up for the next hour. Now, if the device automatically adds a sleep timer, or
if we add it manually using the `power.sleep_timer` command, the new sleep timer set will be adjusted so that it only
puts the device to sleep after the hour from the suppress schedule passes.

:::note
If you're running commands locally on the device, you can use this to disable all active sleep timers:
```python
autopi power.sleep_timer clear="*" 
```

To disable the sleep timers directly on the device, please follow these steps:
* Navigate to the directory: `/etc/salt/minion.d/`
* Open the `engines.conf` file
* Locate and delete the actions related to: `power.sleep_timer`
* Restart the Salt minion service to apply the changes, run: 
```python
sudo systemctl restart salt-minion.service
```

:::

## Troubleshooting

### My Device is Constantly Shutting Down, Even Though My Vehicle is On and Driving

It's important to remember that the [AutoPi](https://www.autopi.io) device will automatically setup sleep timers in an attempt to protect your
vehicle's battery. This will happen even if there are no custom configurations setup or without any interference by the
user. This usually causes confusion as to why the device isn't on, even though it should be on and recording data.

The cause for this is usually because the device hasn't been setup to listen to the correct data and/or events, in order
to suppress (aka clear) sleep timers when the vehicle is being driven. If the device is plugged into an electric vehicle
that can be a bit more difficult to accomplish.

---

## Cloud(Returners)

## `cloud.returner`

Return a result to [Cloud](https://www.autopi.io/software-platform/cloud-management) cache.

----
## `cloud.returner_data`

Return any arbitrary data structure to [Cloud](https://www.autopi.io/software-platform/cloud-management) cache.

----
## `cloud.returner_event`

Return an event to [Cloud](https://www.autopi.io/software-platform/cloud-management) cache.

----
## `cloud.returner_job`

Return a Salt job result to [Cloud](https://www.autopi.io/software-platform/cloud-management) cache.

---

## Cloud Jsonl

## `cloud_jsonl.close_writers`

Ensure all open writers are closed.

----
## `cloud_jsonl.is_expired`

Check if this returner has expired.

----
## `cloud_jsonl.returner`

Return a result to [Cloud](https://www.autopi.io/software-platform/cloud-management) jsonl file.

----
## `cloud_jsonl.returner_data`

Return any arbitrary data structure to [Cloud](https://www.autopi.io/software-platform/cloud-management) jsonl file.

----
## `cloud_jsonl.returner_event`

Return an event to [Cloud](https://www.autopi.io/software-platform/cloud-management) jsonl file.

----
## `cloud_jsonl.returner_job`

Return a Salt job result to [Cloud](https://www.autopi.io/software-platform/cloud-management) jsonl file.

----
## `cloud_jsonl.set_expiration`

Set or clear expiration for this returner.
Delay of zero means instant expiration.
Negative delay will clear any already set expiration.

---

## Event

## `event.returner`

Publishes a job execution notification on the minion`s local event bus.

---

## Event Result

## `event_result.returner`

Publishes an entire job result on the minion`s local event bus.

---

## Introduction(6)

Returners are executed on the device and are responsible for transferring command results, events and other data to a given system or endpoint. In an upcoming release it will be possible for users to code their own custom returners in Python.

---

## Jsonl

## `jsonl.returner`

Return a result to JSONL file.

**EXAMPLE** salt `*` test.ping --return jsonl --return_kwargs `{"dir": "/opt/", "filename": "test.jsonl"}`

----
## `jsonl.returner_data`

Return any arbitrary data structure to a JSONL file.

----
## `jsonl.returner_job`

Return a Salt job result to a JSONL file.

---

## Mqtt(Returners)

## `mqtt.returner`

Return a result to MQTT.

**EXAMPLE** salt `*` test.ping --return mqtt --return_kwargs `{"host": "127.0.0.1", "port": 1883}`

----
## `mqtt.returner_data`

Return any arbitrary data structure to MQTT.

----
## `mqtt.returner_job`

Return a Salt job result to MQTT.

----
## `mqtt.setup_client`

Sets up a newly created MQTT client based on provided options

---

## Acc Manager

## Enrichers
### `orientation`

Adds device orientation (in degrees) which attempts to report back the exact orientation of the
device to the ground.

:::note
This enricher is still a work-in-progress and is not considered stable. The calculations
:::
here are based on this article: http://www.starlino.com/imu_guide.html

----
### `roll_pitch`

Calculates roll and pitch for a XYZ reading and appends it to the result.
This enricher supports both single value results as well as multiple values results.

## Filters
### `alternating_readout`

Filter that only returns alternating/changed results.

**OPTIONAL ARGUMENTS**

  - **`pass_interval`** (int): Filter passes values only when this many miliseconds have passed between readings, even when the values are different. Default value is `0`.

## Handlers
### `connection`

Manages current connection.

**OPTIONAL ARGUMENTS**

  - **`close`** (bool): Close connection? Default value is `False`.

----
### `dump`

Dumps raw XYZ readings to screen or file.

**OPTIONAL ARGUMENTS**

  - **`duration`** (int): How many seconds to record data? Default value is `1`.
  - **`file`** (str): Write data to a file with the given name.
  - **`range`** (int): Maximum number of g-forces being measured. Default value is `8`.
  - **`rate`** (float): How many Hz (samples per second)? Default value is `12.5`.
  - **`decimals`** (int): How many decimals to calculate? Default value is `4`.
  - **`timestamp`** (bool): Add timestamp to each sample? Default value is `True`.
  - **`sound`** (bool): Play sound when starting and stopping recording? Default value is `True`.
  - **`interrupt_driven`** (bool): Await hardware data ready signal before reading a sample? Default value is `True`.

----
### `query`

Queries a given accelerometer command.

**ARGUMENTS**

  - **`cmd`** (str): The command to query.

## Triggers
### `motion_event`

Triggers `vehicle/motion/jolting`, `vehicle/motion/shaking` and `vehicle/motion/steady` events based on accelerometer XYZ readings.

**OPTIONAL ARGUMENTS**

  - **`jolt_g_threshold`** (float): G force threshold for jolting detection. Disabled when set to zero. Default value is `0.3`.
  - **`jolt_duration`** (float): How long in seconds should the G force threshold be observed over? Default value is `1`.
  - **`shake_g_threshold`** (float): G force threshold for shaking detection. Disabled when set to zero. Default value is `0.01`.
  - **`shake_duration`** (float): How long in seconds should the G force threshold be observed over? Default value is `3`.
  - **`shake_percentage`** (float): Percentage of positive motion detections required within duration period to conclude shaking. Default value is `90`.
  - **`debounce_delay`** (float): Minimum delay in seconds between triggering events. Default value is `1`.

---

## Api Service

Serves the local REST API for running AutoPi commands.

---

## Audio Manager

## Handlers
### `aplay`

Play a given audio file using the `aplay` command.

**ARGUMENTS**

    - **`audio_file`** (str): Local path of the audio file to play.

**OPTIONAL ARGUMENTS**

  - **`duration`** (int): Interrupt playback after amount of seconds.

----
### `espeak`

Speak a given text using the `espeak` command.

:::note
Unfortunately 'espeak' command is not always reliable - sometimes it fails for uncertain reasons.
:::

**ARGUMENTS**

  - **`text`** (str): Text to speak out.

**OPTIONAL ARGUMENTS**

  - **`volume`** (int): Set volumen of the playback. Default value is `100`.
  - **`language`** (str): The language to speak in. Default value is `en-gb`.
  - **`pitch`** (int): The pitch of the voice. Default value is `50`.
  - **`speed`** (int): Rate of speech. Default value is `175`.
  - **`word_gap`** (int): Time gap between words spoken. Default value is `10`.
  - **`timeout`** (int): Timeout in seconds of the command to finish. Default value is `10`.

----
### `play`

Plays a specific audio file.

**ARGUMENTS**

  - **`audio_file`** (str): Local path of the audio file to play.

**OPTIONAL ARGUMENTS**

  - **`force`** (bool): Force even though another playback is in progress? Default is `False`.
  - **`loops`** (int): How many repetitions of playback? Default is `0`.
  - **`volume`** (int): Set volumen of the playback.

----
### `queue`

Queues an audio file.

**ARGUMENTS**

  - **`audio_file`** (str): Local path of the audio file to play.

----
### `stop`

Stops playback of the current audio.

----
### `volume`

Set volumen of the playback.

**OPTIONAL ARGUMENTS**

  - **`value`** (int): The volume to set.

---

## Ble Manager

## Handlers
### `flash_firmware`

Flashes new firmware to the BlueNRG device.

----
### `interface`

Manages the interface to the BlueNRG device.

----
### `mode`

Manages the low-level modes of the BlueNRG device.

----
### `query`

Queries a given BlueNRG ACI command.

---

## Can Manager

## Converters
### `can`

Converts raw CAN data using the CAN database available for the current protocol.
The CAN database file (.dbc) is found on the local file system by the following path expression:

/opt/autopi/obd/can/db/protocol_`<PROTOCOL ID>`.dbc

## Handlers
### `autodetect`

Autodetection of interfaces and their supported protocols.

----
### `connection`

Manages the CAN connections.

**OPTIONAL ARGUMENTS**

  - **`open`** (bool): Attempt to open connection. Defaults to `True` if autodetecting, otherwise, don`t change connection state.

----
### `dump`

Stores messages from the CAN bus to a file until a limit or duration is reached.

**ARGUMENTS**

  - **`file`** (str): Write data to a file with the given name. Supported file extensions are `.asc`, `.blf`, `.csv`, `.db` and `.log`.

**OPTIONAL ARGUMENTS**

  - **`duration`** (int): How many seconds to record data? Default value is `1`.
  - **`limit`** (int): The maximum number of messages to read.
  - **`receive_timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.
  - **`skip_11bit_ids`** (bools): Skip all messages with 11bit arbitration IDs. Default value is `False`.
  - **`skip_29bit_ids`** (bools): Skip all messages with 29bit arbitration IDs. Default value is `False`.
  - **`skip_error_frames`** (bool): Skip all messages marked as error frames. Default value is `False`.
  - **`skip_remote_frames`** (bool): Skip all messages marked as remote frames. Default value is `False`.
  - **`skip_normal_frames`** (bool): Skip all messages marked as normal data frames. Default value is `False`.
  - **`pass_filters`** (list): List of arbitration ID filters which are allowed to be received.
  - **`keep_listening`** (bool): Continue listening for messages in the background? Default value is `False`.
  - **`buffer_size`** (int): The limit of messages that the internal queue can hold. If the value is less than or equal to zero, the queue size is infinite. Default value is `0`.
  - **`bus`** (str): Name of bus to use. Defaults to can_conn.DefaultBus mapping.
  - **`conn`** (str): Name of the CAN interface to use. 
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

**OPTIONAL ARGUMENTS FOR ASC AND BLF FILES**

  - **`channel`** (int): The default value to use when a message does not have a channel set. Default value is `1`.

**OPTIONAL ARGUMENTS FOR CSV FILE**

  - **`append`** (bool): Append messages to an existing file where no header line is written or truncate and start with a newly written header line? Default value is `False`.

**OPTIONAL ARGUMENTS FOR DB FILE (SQLITE)**

  - **`table_name`** (str): The name of the table to store messages in. Default value is `messages`.

**OPTIONAL ARGUMENTS FOR LOG FILE**

  - **`channel`** (str): The default value to use when a message does not have a channel set. Default value is `vcan0`.
  - **`append`** (bool): Append messages to any existing file or truncate it?  Default value is `False`.

----
### `external_dump`

Helper for performing CAN dump with external process.

----
### `external_dump_match`

Helper for performing CAN dump matching with external process.

----
### `filter`

Display and management of CAN filters.

**ARGUMENTS**

  - **`*channels`** (str): The channel(s) to include in the result. If none defined all channels are included.

**OPTIONAL ARGUMENTS**

  - **`bus`** (str): Name of a specific bus to display or change.
  - **`add`** (str): The CAN arbitration ID to add as filter.
  - **`mask`** (str): The bitmask to use with the CAN arbitration ID to perform filtering. If not specified, the value is automatically set to the highest possible, meaning a perfect match with the defined CAN arbitration ID.
  - **`is_ext_id`** (bool): Explicit indication of whether to use extended CAN arbitration ID or not (29 or 11 bit). If omitted, the value will be inferred automaticlly by the length of the defined CAN arbitration ID.
  - **`clear`** (bool): Clear any existing filters? This is always done before adding. Default value is `False`.

**EXAMPLES**

  - `can.filter can0`
  - `can.filter can0 bus=dump`
  - `can.filter can0 bus=dump add=7E0`
  - `can.filter can0 bus=dump clear=true`
  - `can.filter can0 bus=dump clear=true add=x7E0`
  - `can.filter can0 bus=dump clear=true add=x7E0 mask=x7FF`
  - `can.filter can0 bus=dump clear=true add=x7E0 mask=x7FF is_ext_id=false`

----
### `j1939_query`

Queries a J1939 PGN on the CAN bus.

**ARGUMENTS**

  - **`pgn`** (int): Number of the PGN to query.

**OPTIONAL ARGUMENTS, J1939 QUERY SPECIFIC**

  - **`priority`** (int): The priority to use for the request message. Default value is `6`.
  - **`destination_address`** (int): The destination address of the request message. Default value is `0`.
  - **`source_address`** (int): The source address of the request message. Default value is `249` (Service Tool).
  - **`auto_filter`** (bool): Ensure to apply filtering to only include reply message for the specific PGN. Default value is `True`.
  - **`auto_filter_mask`** (int): The bitmask to use when the filter is applied. Default value is `0x00FFFF00`.
  - **`auto_tp`** (bool): Automatically enable Transport Protocol (TP) for multi-frame messages. Default value is `True`.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`name`** (str): Name of the command. (E.g. `VehicleSpeed` or `SeatTemperature`)
  - **`output`** (str): Select `obj`, `dict` or `str` as the output data type of the reply messages. Ignored if formula argument is given. Default value is `str`. 
  - **`formula`** (str): Python code that decodes the raw byte data to a value. 
  - **`conn`** (str): Name of the CAN interface to use.
  - **`bus`** (str): Name of the bus instance to use. Default value is `default_query_j1939`.
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

**OPTIONAL ARGUMENTS, QUERY GENERAL**

  - **`pass_filters`** (list): List of pass filters to use for receiving reply frames. 
  - **`ensure_filtering`** (bool): Ensure that reply messages not matching the filters are excluded. Default value is `True`.
  - **`flow_control`** (list): List of flow control ID resolvers to enable. Options are `obd` and `custom`.
  - **`custom_flow_control_id_mappings`** (dict): ID mappings to use for custom flow control.
  - **`replies`** (int): The amount of reply messages to wait for within a timeout.
  - **`skip_error_frames`** (bool): Skip any reply message marked as an error frame. Default value is `True`.
  - **`skip_remote_frames`** (bool): Skip any reply message marked as a remote frame. Default value is `True`.
  - **`strict`** (bool): Raise an error when no reply messages are received or if the amount of expected reply messages is not met within the timeout. Default value is `True`.
  - **`timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.

----
### `monitor`

Monitors messages on the CAN bus until a limit and/or duration is reached.

**OPTIONAL ARGUMENTS**

  - **`duration`** (float): How many seconds to record data? Default value is `1`.
  - **`limit`** (int): The maximum number of messages to read.
  - **`receive_timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.
  - **`skip_error_frames`** (bool): Skip any reply message marked as an error frame. Default value is `False`.
  - **`bus`** (str): Name of bus to use. Defaults to can_conn.DefaultBus mapping.
  - **`conn`** (str): Name of the CAN interface to use. 
  - **`keep_listening`** (bool): Continue listening for messages in the background? Default value is `False`.
  - **`bus_keep_alive`** (bool): Will keep the bus and its settings alive after the handler is finished. Forced to True if keep_listening is set. Default value is `False`.
  - **`buffer_size`** (int): The limit of messages that the internal queue can hold. If the value is less than or equal to zero, the queue size is infinite. Default value is `0`.
  - **`output`** (str): Select `obj`, `dict` or `str` as the output data type of the reply messages. Ignored if `dbc` argument is given. Default value is `str`.
  - **`dbc`** (str): Path of the can database file (like .dbc) for filtering and decoding.
  - **`mask`** (str): Mask to apply to filters and CAN database for decoding.
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

----
### `obd_query`

Queries an OBD-II PID on the CAN bus.

**ARGUMENTS**

  - **`name`** (str): Name of the command.

**OPTIONAL ARGUMENTS, OBD-II QUERY SPECIFIC**

  - **`mode`** (str): Service section of the PID.
  - **`pid`** (str): Code section of the PID.
  - **`bytes`** (int): Byte size of individual returned frame(s). Default value is `0`.
  - **`frames`** (int): Expected frame count to be returned?
  - **`strict_lengths`** (bool): Enforce strict validation of specified `bytes` and/or `frames`. Default value is `False`.
  - **`decoder`** (str): Specific decoder to be used to process the response.
  - **`unit`** (str): Unit of the result.
  - **`auto_filter`** (bool): Ensure to apply filtering to only include OBD-II reply messages. Default value is `True`.
  - **`auto_format`** (bool): Ensure that the PID request message always has a fixed data length of 8 bytes (zero padding). Default value is `True`.
  - **`id`** (int): Use a custom CAN arbitration ID for the PID request message. 
  - **`is_ext_id`** (bool): Enforce to use extended CAN arbitration ID or not (29 or 11 bit) for the PID request message.
  - **`extended_address`** (int): Extended address value that will be set as the first data byte.
  - **`zero_padding`** (int): Number of zero padding bytes to add to data. Defaults to `8` when `auto_format` is set to `True`.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`formula`** (str): Python code that decodes the raw byte data to a value.
  - **`conn`** (str): Name of the CAN interface to use.
  - **`bus`** (str): Name of the bus instance to use. Default value is `default_query_obd`.
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

**OPTIONAL ARGUMENTS, QUERY GENERAL**

  - **`pass_filters`** (list): List of pass filters to use for receiving reply frames. 
  - **`ensure_filtering`** (bool): Ensure that reply messages not matching the filters are excluded. Default value is `True`.
  - **`flow_control`** (list): List of flow control ID resolvers to enable. Options are `obd` and `custom`.
  - **`custom_flow_control_id_mappings`** (dict): ID mappings to use for custom flow control.
  - **`replies`** (int): The amount of reply messages to wait for within a timeout.
  - **`skip_error_frames`** (bool): Skip any reply message marked as an error frame. Default value is `True`.
  - **`skip_remote_frames`** (bool): Skip any reply message marked as a remote frame. Default value is `True`.
  - **`strict`** (bool): Raise an error when no reply messages are received or if the amount of expected reply messages is not met within the timeout. Default value is `True`.
  - **`timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.

----
### `play`

Sends all messages from one or more dump files on the CAN bus.

**ARGUMENTS**

  - **`*files`** (str): Specify one or more dump files for playback.

**OPTIONAL ARGUMENTS**

  - **`ignore_timestamps`** (bool): Ignore the timestamps of the messages and use the `min_gap` parameter as the time between messages instead. Default value is `False`.
  - **`min_gap`** (float): Minimum time between sent messages in seconds. Default value is `0.0001`.
  - **`skip_gaps_gt`** (float): Skip periods of inactivity greater than this (in seconds). Default value is `86400`.
  - **`include_error_frames`** (bool): Also send messages marked as error frames? Default value is `True`.
  - **`bus`** (str): Name of bus to use. Defaults to can_conn.DefaultBus mapping.
  - **`conn`** (str): Name of the CAN interface to use. 
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

----
### `query`

Queries by sending one or more request messages on the CAN bus and then waits for one or more reply messages.

**ARGUMENTS**

  - **`*messages`** (can.Message|str): CAN request messages to send.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`name`** (str): Name of the command (e.g. `VehicleSpeed` or `SeatTemperature`).
  - **`output`** (str): Select `obj`, `dict` or `str` as the output data type of the reply messages. Default value is `str`.
  - **`formula`** (str): Python code that decodes the raw byte data to a value.
  - **`conn`** (str): Name of the CAN interface to use.
  - **`bus`** (str): Name of the bus instance to use. Default value is `default_query`.
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

**OPTIONAL ARGUMENTS, QUERY GENERAL**

  - **`pass_filters`** (list): List of pass filters to use for receiving reply frames. 
  - **`ensure_filtering`** (bool): Ensure that reply messages not matching the filters are excluded. Default value is `True`.
  - **`flow_control`** (list): List of flow control ID resolvers to enable. Options are `obd` and `custom`.
  - **`custom_flow_control_id_mappings`** (dict): ID mappings to use for custom flow control.
  - **`replies`** (int): The amount of reply messages to wait for within a timeout.
  - **`skip_error_frames`** (bool): Skip any reply message marked as an error frame. Default value is `True`.
  - **`skip_remote_frames`** (bool): Skip any reply message marked as a remote frame. Default value is `True`.
  - **`strict`** (bool): Raise an error when no reply messages are received or if the amount of expected reply messages is not met within the timeout. Default value is `True`.
  - **`timeout`** (float): The amount of time in seconds to wait for a reply message. Default value is `0.2`.

----
### `send`

Sends one or more messages on the CAN bus.

**ARGUMENTS**

  - **`*messages`** (str): CAN messages to send.

**OPTIONAL ARGUMENTS**

  - **`bus`** (str): Name of bus to use. Defaults to can_conn.DefaultBus mapping.
  - **`conn`** (str): Name of the CAN interface to use. 
  - **`sanitize`** (bool): Enable/disable input sanitization. Defaults to `True`.

---

## Cloud Manager

## Handlers
### `cache`

Queries/calls a given cache function.

----
### `status`

Gets current status.

----
### `upload`

Uploads cached data to cloud.

---

## Crypto Manager

## Handlers
### `query`

Queries a given command.

**ARGUMENTS**

  - **`cmd`** (str): The command to query.

---

## Docker Monitor

Internal service for monitoring container changes.

---

## Doip Manager

## Handlers
### `context`

Gets current context.

----
### `interface`

Manages the DoIP interface.

----
### `uds`

Queries using the UDS client. The UDS client works synchronously and can handle a single request/response at a time.

---

## Ec2X Manager

## Handlers
### `connection`

Manages current connection.

**OPTIONAL ARGUMENTS**

  - **`close`** (bool): Close serial connection? Default value is `False`.

----
### `delete_sms`

Delete messages from message storage.

It is possible to list possible for deleting if no indexes are passed and the `delete_all` kwarg is not passed (or set to `False`).

Keyword argumnets:

- index (int): The index of the message to be deleted. Default None.
- delete_all (bool): Set this boolean to true if all messages stored in the modem should be deleted. Default `False`.
- confirm (bool): A confirm flag when deleting messages. Default `False`.

----
### `download`

Downloads a file from the EC2X device.

**ARGUMENTS**

  - **`cmd`** (str): AT command to perform the actual download.
  - **`size`** (int): Size of the file to download.
  - **`dest`** (str): Destination path to which the downloaded file is to be written.

----
### `exec`

Runs an AT command against the EC2X device.

**ARGUMENTS**

  - **`cmd`** (str): AT command to execute.

----
### `list_sms`

List all messages from message storage.

:::note
In order to use this function, you need to first execute `ec2x.sms_format_config value=1`
:::
to set the correct format of the SMS messages.

----
### `power`

Powers down the EC2X device. Afterwards the module will start automatically.
A 30-second wait is included after power off to allow the module time to recover before receiving any new requests.

**ARGUMENTS**

  - **`cmd`** (str): AT command to perform the power down.

**OPTIONAL ARGUMENTS**

  - **`reason`** (str): Reason code that tells why we decided to power down. Default is `unknown`.

----
### `read_sms`

Reads SMS messages stored in the modem and processes them into `system/sms/received` events.
Those events hold information such as the timestamp of the message (when it was received by the
modem), the sender and the text. Messages will be deleted from the modem after being processed.

:::note
This function will configure the SMS format to text mode. This is necessary in order to read
:::
the messages correctly. If necessary, revert the configuration with the `ec2x.sms_format_config`
command.

----
### `sms_format_config`

Gets or sets the SMS format configuration.

Possible values:

- 0: PDU mode - entire TP data units used (hex responses). This is the default value.
- 1: Text mode - headers and body of the message given as separate parameters.

----
### `sync_time`

Synchronizes the system clock with the EC2X device.

**OPTIONAL ARGUMENTS**

  - **`force`** (bool): Default is `False`.

----
### `sync_time`

Ensures following keys for return value:

clock_synced: boolean
npt_enabled: boolean

----
### `upload`

Uploads a file to the EC2X device.

**ARGUMENTS**

  - **`cmd`** (str): AT command to perform the actual upload.
  - **`src`** (str): Destination path to the file to be uploaded.

---

## Event Reactor

## Converters
### `detained_composite_event`

Ensures a worker thread is scheduled for events with a detain period specified.
Only one scheduled worker thread can exist at a time.

Example scenario 1:

- (00:00:00) tag=`vehicle/ignition/on`, detain_period=0   ->` The event is immediately passed on to the trigger
- (00:00:01) tag=`vehicle/ignition/off`, detain_period=5  ->` The trigger is scheduled to run in 5 seconds
- (00:00:02) tag=`vehicle/ignition/on`, detain_period=0   ->` The scheduled trigger is cancelled and the event is immediately passed on to the trigger

Example scenario 2:

- (00:00:00) tag=`vehicle/ignition/off`, detain_period=5  ->` The trigger is scheduled to run in 5 seconds
- (00:00:01) tag=`vehicle/ignition/off`, detain_period=5  ->` The event is enqueued to the already scheduled trigger that will run in now 4 seconds

Example scenario 3:

- (00:00:00) tag=`vehicle/ignition/on`, detain_period=5   ->` The trigger is scheduled to run in 5 seconds
- (00:00:01) tag=`vehicle/ignition/off`, detain_period=5  ->` The scheduled trigger is cancelled and and a new trigger is scheduled to run in 5 seconds

## Filters
### `alternating_cache_event`

Filter that only returns alternating/changed events from cache.

## Handlers
### `cache`

Manages cached data.

----
### `composite_event`

Creates composite events that are based on other events.

## Returners
### `module_result_cache`

Stores/caches a module result in context.

## Triggers
### `composite_event`

Triggers a composite event and updates its triggered at timestamp.

---

## Gnss Manager

## Converters
### `gnss_location_to_position`

Converts a GNSS location result into position type.

----
### `nmea_gga_to_dict`

Parses NMEA0183 GGA messages to a dictionary that can be serialized.

Example values:

$GPGGA,143824.00,5702.167555,N,00956.116128,E,1,09,0.6,13.9,M,43.0,M,,*55
$GPGGA,,,,,,0,,,,,,,,*66

----
### `nmea_vtg_to_dict`

Parses NMEA0183 VTG messages to a dictionary that can be serialized.

Example values:

$GPVTG,,T,0.3,M,0.0,N,0.0,K,A*0E
$GPVTG,,T,,M,,N,,K,N*2C

## Filters
### `significant_position`

Filter that only returns significant non duplicated positions.

## Handlers
### `connection`

Queries a given command down to the connection class.

**ARGUMENTS**

  - **`cmd`** (str): The command to query.

----
### `nmea0183_readout`

Read and parse all available NMEA0183 sentences through serial connection.

## Triggers
### `position_event`

Listens for position results and triggers position unknown/standstill/moving events.

---

## Introduction(7)

A variety of services are running on the device, each having its own specific area of responsibility. Most services are built around the same structure and using the same concepts which are described below.

:::note
Services can be setup and configured from the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management). When logged in go to: _Device_ > _Services_
:::

## Settings

At startup, a service is initialized with the given settings. They vary between different services but usually contains connection strings, timeout threshold etc.

## Workers

Within a service multiple worker threads can run. Each worker is setup to process one or more workflows sequentially for a limited period of time or indefinitely.

Available options for a worker instance:

| Field | Type | Description | Default Value |
| ------ | ------ | ------ | ------ |
| `name` | Text | System name to identify the given worker. | - |
| `delay` | Decimal | Initial delay in seconds before starting the worker. No delay if left empty. | - |
| `interval` | Decimal | Pause in seconds between each run. Enter `0` if no pause. | `1` |
| `loop` | Integer | How many runs should the worker do? Enter `-1` if infinite. | `-1` |
| `suppress_exceptions` | Boolean | Suppress errors/exceptions so that they do not kill the worker thread? | `True` |
| `kill_upon_success` | Boolean | Kill the worker thread after the first successful run? Successful means that no errors/exceptions occurred. | `False` |
| `transactional` | Boolean | Ensure that consecutive workflows are processed in an uninterrupted sequence and not potentially mixed with others from other workers? | `False` |

### Workflows

A worker can process one or more workflows in a sequence. A worflow consists of a number of steps. The primary step of a workflow is called __`handler`__ and is always required. Then more steps may occur both before and/or after, and are not normally required. At present, there are two built-in workflows. Below is an overview of the steps in the first workflow called `simple`:

| __`handler`__ | → | _`trigger`_ | → | _`filter`_ | → | _`returner`_ |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ |

And secondly the `extended` workflow:

| _`validator`_ | → | __`handler`__ | → | _`converter`_ | → | _`trigger`_ | → | _`filter`_ | → | _`enricher`_ | → | _`returner`_ |
| ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ | ------ |

Each step in a workflow has a defined area of responsibility:

| Step | Description | Example |
| ------ | ------ | ------ |
| _`validator`_ | Validates the request and decide whether or not to proceed to the handler. | - |
| __`handler`__ | Produces a result typically by interacting with an external device or system. | [See](/core/services/obd_manager.md#handlers) |
| _`converter`_ | Converts the result returned from the handler into a more usable format. | [See](/core/services/obd_manager.md#converters) |
| _`trigger`_ | Decides whether to trigger an event based on the result. | [See](/core/services/obd_manager.md#triggers) |
| _`filter`_ | Filters out result if insignificant. | [See](/core/services/obd_manager.md#filters) |
| _`enricher`_ | Enriches result with additional information. Could for example be calculations. | [See](/core/services/acc_manager.md#enrichers) |
| _`returner`_ | Returns the final result to an external system or service. | [See](/core/returners/index.md) |

## Reactors
Reactors in AutoPi are components that listen for specific events and execute predefined actions in response (how device handle the different events). They are integral to automating behaviors based on real-time data from the device.

### Managing Reactors
Reactors can be managed using the `reactor.manage` command, which provides runtime control over the reactor service.

#### Supported Commands:

```python
reactor.manage reactor list
reactor.manage reactor show <name>
```

**Example Usage:**
```python
reactor.manage reactor list
reactor.manage reactor show enable_obd_on_motion_shaking
```

* These commands allow you to list all available reactors and view detailed information about a specific reactor.

### Example: Automatic OBD Logger Pausing
An illustrative use case involves the automatic pausing of the OBD logger based on vehicle motion:
1. Enable Motion Events: Ensure that motion events are enabled in the device settings.
2. Configure Reactors: Navigate to Services > event_reactor > Reactors in the AutoPi Cloud interface.
3. Enable Specific Reactors: Activate the following reactors:
    * `enable_obd_on_motion_shaking`
    * `disable_obd_on_motion_steady_or_trip_end`
        * These reactors respond to motion events, enabling or disabling the OBD logger accordingly.

## Hooks
Hooks are custom functions that can be integrated into the AutoPi workflow to process data at various stages. They provide flexibility in handling data by allowing custom processing logic to be executed.
Hooks are the core of how your AutoPi.io device works and we only recommend that you change these if you are sure of what you are doing.

### Creating Custom Hooks
Steps to create a custom hook:
* Create a Custom Module: navigate to Device > Custom Code in the AutoPi Cloud interface and create a new module of type Execution.
* Define the Hook Function.
* Register the Hook by going to the relevant service's Hooks section (e.g., Services > obd_manager > Hooks) and register the new hook.
4. Integrate into workflow: edit the desired worker's workflow to include the custom hook in the appropriate step (e.g., as a filter or returner).

### Hook Behavior
* Hooks receive the output from the previous step in the workflow and return a modified result.
* If a hook returns a falsy value (e.g., None, False), the workflow is halted at that point.
* Hooks are ideal for data validation, transformation, or conditional processing within the workflow.

---

## Key Fob Manager

## Handlers
### `action`

Performs a key fob button action.

**ARGUMENTS**

  - **`*name`** (str): Name(s) of the action(s) to perform.

----
### `power`

Powers on/off key fob.

**OPTIONAL ARGUMENTS**

  - **`value`** (bool): Power on or off.

----
### `toggle_action`

Toggle an action. The action that`s being toggled needs to be defined with an `opposite` field
containing the name of the opposite action. The function will toggle the two actions each
time it is called with either name.

Parameters:

- default (bool) - What should the default state of these actions be set to. (default False)

---

## Manager



---

## Modem Manager

## Handlers
### `connection`

Queries a given connection class command.

**ARGUMENTS**

  - **`cmd`** (str): The command to query.

----
### `read_sms`

Reads SMS messages stored in the modem and optionally processes them into `system/sms/received` events.
Those events hold information such as the timestamp of the message (when it was received by the
modem), the sender and the text.

Optional parameters:

- status (str): The status of the messages that are to be returned. Look below for avalable options. Default: "ALL".
- clear (bool): Should the returned messages be removed from the modem as well?
- format_mode (str): The format in which the messages should be processed. Currently, only TXT mode is supported. Default: "TXT".
- trigger_events (bool): Should the handler trigger SMS events? Default: False

Available options (status):

- "REC UNREAD" - new messages
- "REC READ" - read messages
- "STO UNSENT" - stored messages not sent yet
- "STO SENT" - stored messages already sent
- "ALL" - all messages

----
### `reset`

Enable or disable the one shot or periodic unit reset.

Optional parameters:

- mode (string): The mode in which to operate the command. For available values, look below. Default: None.
- delay (number): Time interval in minutes after that the unit reboots. Default: 0.
- reason (str): The reason the reset was performed. Default: "unspecified".

Available modes:

- disabled: Disables unit reset.
- one_shot: Enables the unit reset only one time (one shot reset).
- periodic: Enables periodic resets of the unit.

---

## Obd Manager

## Converters
### `battery`

Converts a voltage reading result with battery charge state and level.

----
### `can`

Converts raw CAN data using the CAN database available for the current protocol.
This converter supports both single value results as well as multiple values results.
The CAN database file (.dbc) is found on the local file system by the following path expression:

/opt/autopi/obd/can/db/protocol_`<PROTOCOL ID>`.dbc

----
### `dtc`

Converts Diagnostics Trouble Codes (DTCs) result into a cloud friendly format that will NOT be flattened by the cloud returner.

----
### `dtc_flattening`

Converts Diagnostics Trouble Codes (DTCs) result into a cloud friendly format.

:::note
This was the old default DTC converter in the past. The new default converter will not be flattening the DTC result.
:::

----
### `realistic_speed`

Converts speed value of 255 (max value 0xFF) to 0. Some vehicles can sporadically return value of 255.

## Filters
### `alternating_dtc`

Filters out repeating Diagnostics Trouble Codes (DTCs).

----
### `alternating_readout`

Filter that only returns alternating/changed results.

**OPTIONAL ARGUMENTS**

  - **`pass_interval`** (int): Filter passes values only when this many miliseconds have passed between readings, even when the values are different. Default value is `0`.

## Handlers
### `commands`

Lists all supported OBD commands found for vehicle.

----
### `connection`

Manages current connection.

**OPTIONAL ARGUMENTS**

  - **`baudrate`** (int): Changes baudrate used to communicate with interface.
  - **`reset`** (str): Reboots interface and re-initializes connection.

----
### `dump`

Dumps all messages from bus to screen or file.

**OPTIONAL ARGUMENTS**

  - **`duration`** (int): How many seconds to record data? Default value is `2` seconds.
  - **`file`** (str): Write data to a file with the given name.
  - **`description`** (str): Additional description to the file.
  - **`filtering`** (bool): Use filters while monitoring or monitor all messages? Default value is `False`. It is possible to specify `can` or `j1939` (PGN) in order to add filters based on the messages found in a CAN database file (.dbc).
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`raw_response`** (bool): Get raw response without any validation nor parsing? Default value is `False`.
  - **`format_response`** (bool): Format response messages by separating header and data with a hash sign? Default value is `True`.

----
### `execute`

Executes an AT/ST command.

**ARGUMENTS**

  - **`cmd`** (str): Command to execute.

**OPTIONAL ARGUMENTS**

  - **`assert_result`** (str or list): Validate the response by checking that is matches this specific value.
  - **`reset`** (str): Reset interface after execution. Valid options are: `warm`, `cold`
  - **`keep_conn`** (bool): Keep connection to interface after execution or close it permanently? Default value is `True`.
  - **`type`** (str): Specify a name of the type of the result. Default is the given command.

----
### `export`

Fast export of all messages on a bus to a log file.

**OPTIONAL ARGUMENTS**

  - **`run`** (bool): Specify if subprocess should be running or not. If not defined the current state will be queried.
  - **`folder`** (str): Custom folder to place export log files.
  - **`wait_timeout`** (int): Maximum time in seconds to wait for subprocess to complete. Default value is `0`.
  - **`monitor_filtering`** (bool): Use filters while monitoring or monitor all messages? Default value is `False`. It is possible to specify `can` or `j1939` (PGN) in order to add filters based on the messages found in a CAN database file (.dbc).
  - **`monitor_mode`** (int): The STN monitor mode. Default is `0`.
  - **`can_auto_format`** (bool): Apply automatic formatting of messages? Default value is `False`.
  - **`read_timeout`** (int): How long time in seconds should the subprocess wait for data on the serial port? Default value is `1`.
  - **`serial_baudrate`** (int): Specify a custom baud rate to use for the serial connection to the STN.
  - **`process_nice`** (int): Process nice value that controls the priority of the subprocess. Default value is `-2`.
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.

----
### `filter`

Manages filters.

**ARGUMENTS**

  - **`action`** (str): Action to perform. Available actions are `auto`, `list`, `add`, `clear` and `sync`.

----
### `import`

Fast import of exported log files containing messages from a bus.

**OPTIONAL ARGUMENTS**

  - **`folder`** (str): Custom folder to import log files from.
  - **`limit`** (int): The maximum number of lines/messages to read each time. Default value is `5000`.
  - **`idle_sleep`** (int): Pause in seconds if there is no lines/messages to import. Default value is `0`.
  - **`cleanup_grace`** (int): Grace period in seconds before a fully imported log file is deleted. Default value is `60`.
  - **`process_nice`** (int): Process nice value that controls the priority of the service. Default value is `0`.
  - **`type`** (str): Specify a name of the type of the result. Default is `raw`.

----
### `monitor`

Monitors messages on bus until limit or duration is reached.

**OPTIONAL ARGUMENTS**

  - **`wait`** (bool): Wait for each message/line to read according to the default timeout of the serial connection (default 1 second). Otherwise there will only be waiting on the first line/message. Default value is `False`.
  - **`limit`** (int): The maximum number of messages to read. Default value is `500`.
  - **`duration`** (float): How many seconds to monitor? If not set there is no limitation.
  - **`mode`** (int): The STN monitor mode. Default is `0`.
  - **`auto_format`** (bool): Apply automatic formatting of messages? Default value is `False`.
  - **`filtering`** (bool): Use filters while monitoring or monitor all messages? Default value is `False`. It is possible to specify `can` or `j1939` (PGN) in order to add filters based on the messages found in a CAN database file (.dbc).
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`type`** (str): Specify a name of the type of the result. Default is `raw`.

----
### `play`

Plays all messages from a file on the bus.

**ARGUMENTS**

  - **`file`** (str): Path to file recorded with the `obd.dump` command.

**OPTIONAL ARGUMENTS**

  - **`delay`** (float): Delay in milliseconds between sending each message. Default value is `0`.
  - **`slice`** (str): Slice the list of messages before sending on the CAN bus. Based one the divide and conquer algorithm. Multiple slice characters can be specified in continuation of each other.
    - `t`: Top half of remaining result.
    - `b`: Bottom half of remaining result.
  - **`filter`** (str): Filter out messages before sending on the CAN bus. Multiple filters can be specified if separated using comma characters.
    - `+[id][#][data]`: Include only messages matching string.
    - `-[id][#][data]`: Exclude messages matching string.
    - `+duplicate`: Include only messages where duplicates exist.
    - `-duplicate`: Exclude messages where duplicates exist.
    - `+mutate`: Include only messages where data mutates.
    - `-mutate`: Exclude messages where data mutates.
  - **`group`** (str): How to group the result of sent messages. This only affects the display values returned from this command. Default value is `id`.
    - `id`: Group by message ID only.
    - `msg`: Group by entire message string.
  - **`protocol`** (str): ID of specific protocol to be used to send the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`auto_format`** (bool): Apply automatic formatting of messages? Default value is `False`.
  - **`test`** (bool): Run command in test-only? (dry-run) mode. No data will be sent on CAN bus. Default value is `False`.

----
### `protocol`

Configures protocol or lists all supported.

**OPTIONAL ARGUMENTS**

  - **`set`** (str): Change to protocol with given identifier.
  - **`baudrate`** (int): Use custom protocol baudrate.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.

----
### `query`

Queries an OBD command.

**ARGUMENTS**

  - **`name`** (str): Name of the command.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`mode`** (str): Service section of the PID.
  - **`pid`** (str): Code section of the PID.
  - **`header`** (str): Identifer of message to send. If none is specifed the default header will be used.
  - **`bytes`** (int): Byte size of individual returned frame(s). Default value is `0`.
  - **`frames`** (int): Expected frame count to be returned?
  - **`strict`** (int): Enforce strict validation of specified `bytes` and/or `frames`. Default value is `False`.
  - **`decoder`** (str): Specific decoder to be used to process the response.
  - **`formula`** (str): Formula written in Python to convert the response.
  - **`unit`** (str): Unit of the result.
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`force`** (bool): Force query of unknown command. Default is `False`.
  - **`type`** (str): Specify an alternative name of the type of the result. Default is the given name of the command.

**OPTIONAL ARGUMENTS, CAN SPECIFIC**

  - **`can_extended_address`** (str): Use CAN extended address.
  - **`can_priority`** (str): Set CAN priority bits of a 29-bit CAN ID.
  - **`can_flow_control_clear`** (bool): Clear all CAN flow control filters and ID pairs before adding any new ones.
  - **`can_flow_control_filter`** (str): Ensure CAN flow control filter is added. Value must consist of `<Pattern>,<Mask>`.
  - **`can_flow_control_id_pair`** (str): Ensure CAN flow control ID pair is added. Value must consist of `<Transmitter ID>,<Receiver ID>`.

**OPTIONAL ARGUMENTS, J1939 SPECIFIC**

  - **`j1939_pgn_filter`** (str): Ensure J1939 PGN filter is added. Value must consist of `<PGN>[,<Target Address>]`.

----
### `query_many`

Queries many OBD commands in one call.

The function should receive an array of dictionaries. Each dict should have an `args` key which value is an array,
and a `kwargs` key which value is another dictionary. Inside the `args` and `kwargs` fields, the respective arguments
and keyword arguments from the `query_handler` should be passed.

Example as command:

```
$ obd.query_many \
`{"args": ["SPEED"], "kwargs": {"header": "7DF", "mode": "01", "pid": "0D"}}` \
`{"args": ["RPM"], "kwargs": {"header": "7DF", "mode": "01", "pid": "0C"}}`
```

:::note
The dictionaries need to be surrounded by a single quote character, not a backtick.
:::

To set this up as a handler inside a worker, the format is the same. You will need to pass the parameters in the
"args" field in the respective workflow.

----
### `recordings`

Lists all dumped recordings available on disk.

----
### `send`

Sends a message on bus.

**ARGUMENTS**

  - **`msg`** (str): Message to send.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`header`** (str): Identifer of message to send. If none is specifed the default header will be used.
  - **`auto_format`** (bool): Apply automatic formatting of messages? Default value is `False`.
  - **`auto_filter`** (bool): Ensure automatic response filtering is enabled. Default value is `True` if no custom filters have be added.
  - **`expect_response`** (bool): Wait for response after sending? Avoid waiting for timeout by specifying the exact the number of frames expected. Default value is `False`.
  - **`format_response`** (bool): Format response frames by separating header and data with a hash sign. Default value is `False`.
  - **`raw_response`** (bool): Get raw response without any validation nor parsing? Default value is `False`.
  - **`echo`** (bool): Include the request message in the response? Default value is `False`.
  - **`protocol`** (str): ID of specific protocol to be used to receive the data. If none is specifed the current protocol will be used.
  - **`baudrate`** (int): Specific protocol baudrate to be used. If none is specifed the current baudrate will be used.
  - **`verify`** (bool): Verify that OBD-II communication is possible with the desired protocol? Default value is `False`.
  - **`output`** (str): What data type should the output be returned in? Default is a `list`.
  - **`type`** (str): Specify a name of the type of the result. Default is `raw`.

**OPTIONAL ARGUMENTS, CAN SPECIFIC**

  - **`can_extended_address`** (str): Use CAN extended address.
  - **`can_priority`** (str): Set CAN priority bits of a 29-bit CAN ID.
  - **`can_flow_control_clear`** (bool): Clear all CAN flow control filters and ID pairs before adding any new ones.
  - **`can_flow_control_filter`** (str): Ensure CAN flow control filter is added. Value must consist of `<Pattern>,<Mask>`.
  - **`can_flow_control_id_pair`** (str): Ensure CAN flow control ID pair is added. Value must consist of `<Transmitter ID>,<Receiver ID>`.

**OPTIONAL ARGUMENTS, J1939 SPECIFIC**

  - **`j1939_pgn_filter`** (str): Ensure J1939 PGN filter is added. Value must consist of `<PGN>[,<Target Address>]`.

----
### `setup`

Setup advanced runtime settings.

**OPTIONAL ARGUMENTS, GENERAL**

  - **`adaptive_timing`** (int): Set adaptive timing mode. Sometimes, a single OBD requests results in multiple response frames. The time between frames varies significantly depending on the vehicle year, make, and model - from as low as 5ms up to 100ms. Default value is `1` (on, normal mode).
  - **`response_timeout`** (int): When adaptive timing is on, this sets the maximum time that is to be allowed, even if the adaptive algorithm determines that the setting should be longer. In most circumstances, it is best to let the adaptive timing algorithm determine what to use for the timeout. Default value is `50` x 4ms giving a time of approximately 200ms.

**OPTIONAL ARGUMENTS, CAN SPECIFIC**

  - **`can_extended_address`** (str): Use CAN extended address.
  - **`can_priority`** (str): Set CAN priority bits of a 29-bit CAN ID.
  - **`can_flow_control_clear`** (bool): Clear all CAN flow control filters and ID pairs before adding any new ones.
  - **`can_flow_control_filter`** (str): Ensure CAN flow control filter is added. Value must consist of `<Pattern>,<Mask>`.
  - **`can_flow_control_id_pair`** (str): Ensure CAN flow control ID pair is added. Value must consist of `<Transmitter ID>,<Receiver ID>`.
  - **`allow_sending_can_frames`** (bool): Allow the connection to send CAN frames on the CAN bus.

**OPTIONAL ARGUMENTS, J1939 SPECIFIC**

  - **`j1939_pgn_filter`** (str): Ensure J1939 PGN filter is added. Value must consist of `<PGN>[,<Target Address>]`.

----
### `status`

Gets current status information.

## Triggers
### `battery_event`

Looks for battery results and triggers `vehicle/battery/*` event when voltage changes.

----
### `communication_event`

Looks for error in result and triggers `vehicle/communication/[inactive|established|disconnected]` event based on the outcome.

----
### `rpm_engine_event`

Looks for RPM result and triggers `vehicle/engine/[not_running|running|stopped]` event based on the value(s) found.
This trigger supports single value results as well as multiple values results.

----
### `rpm_motor_event`

Looks for RPM result and triggers motor `vehicle/motor/[not_running|running|stopped]` event based on the value(s) found.
This trigger supports single value results as well as multiple values results.
This trigger is meant to be used for electric vehicles without an engine.

----
### `speed_motor_event`

Looks for speed result and triggers motor `vehicle/motor/[not_running|running|stopped]` event based on the value(s) found.
This trigger supports single value results as well as multiple values results.
This trigger is meant to be used for electric vehicles without an engine.

---

## Process Manager

## Handlers
### `manage_process`

Starts a new process if it`s not already started.

---

## Rfid Manager

## Handlers
### `authenticate_rfid`

If there are any authorized_tokens saved in context, this handler will attempt to authenticate
an RFID against those tokens. Triggers `system/rfid/<rfid>/rejected` and
`system/rfid/<rfid>/authenticated` events.

If the tokens get updated in /opt/autopi/rfid/settings.yaml the manager needs to know about
the changes - use `load_settings_handler` to reload the settings.

----
### `load_settings`

Read the settings file stored in /opt/autopi/rfid/settings.yaml and load it.

----
### `reader`

Reads input from the RFID reader.

## Triggers
### `rfid_read`

Triggers `system/rfid/<rfid>/read` events when RFID chips are read.

:::note
Use in conjunction with reader_handler.
:::

---

## Spm Manager

## Handlers
### `flash_firmware`

Flashes new SPM firmware to the MCU.

----
### `fuse`

Manage fuse of the MCU.

----
### `heartbeat`

Triggers SPM heartbeat and fires power on event when booting.

----
### `led_pwm`

Change PWM frequency and/or duty cycle for LED.

**OPTIONAL ARGUMENTS**

  - **`frequency`** (float): Change to frequency in Hz.
  - **`duty_cycle`** (float): Change to duty cycle in percent.

----
### `query`

Queries a given SPM command.

**ARGUMENTS**

  - **`cmd`** (str): The SPM command to query.

----
### `reset`

Reset/restart the MCU.

---

## Tracking Manager

## Converters
### `gnss_location_to_position`

Converts a GNSS location result into position type.

----
### `nmea0183_readout_to_position`

Converts NMEA0183 sentences result into position type.

## Filters
### `significant_position`

Filter that only returns significant non duplicated positions.

## Handlers
### `gnss_query`

Reads GNSS data and settings synchronously from EC2X module.

----
### `nmea0183_readout`

Reads all available NMEA0183 sentences through serial connection.

----
### `status`

Gets current status.

## Triggers
### `position_event`

Listens for position results and triggers position unknown/standstill/moving events.

---

## Accessing Raw GPS Data (10 Hz)

---
This guide explains how to enable and stream raw GPS (NMEA) data at 10 Hz from your AutoPi device.

## Overview 
By default, the device’s `GNSS Manager` service handles GPS communication. To stream raw NMEA data directly, this service must first be disabled to free up the serial (TTY) port used for GPS communication.
Once disabled, you can use a simple Python script mentioned below to configure the GPS polling rate, enable streaming mode, and read data from the serial output in real time.

## Steps

### 1. Disable the GNSS Manager Service 
1. Navigate to the device you want to configure on [AutoPi's cloud](https://my.autopi.io/#/login)
2. Go to **Services** page under Device. 
3. Locate the `gnss_manager`service.
4. Disable the service. Disabling this service ensures that no other process is using the same TTY port needed for raw NMEA streaming.

![Disable the gnss manager service](/img/guides/services_gnss_manager.png)

### 2. Configure and Start the GPS Data Stream
Use the provided Python script to set up the GPS polling rate and start the NMEA data stream.

This example script:
* Configures the GPS to output data at 10 Hz
* Enables continuous streaming mode
* Prints raw NMEA sentences to stdout

:::note
You can modify the script to log data to a file, filter specific NMEA messages, or integrate with your application.
:::

You can copy the **example Python script** below: 
```python
#!/bin/python3

import serial
import time
import threading

PORT_GPS = "/dev/ttyTLT02"
PORT_MODEM = "/dev/ttyTLT01"
BAUD = 115200
stop_flag = False

def key_listener():
    global stop_flag
    key = str(input())
    print("you pressed {}".format(key))
    stop_flag=True

def setup_gps():
    with serial.Serial(PORT_GPS, BAUD, timeout=1) as modem:
        modem.reset_input_buffer()
        modem.reset_output_buffer()
        modem.write(b'AT$GPSNHZ?\r')
        time.sleep(0.5)
        response = modem.read_all().decode(errors="ignore")
        if not "3" in response:
            modem.write(b'AT$GPSP=0\r')
            time.sleep(5)
            modem.write(b'AT$GPSNHZ=3\r')
            time.sleep(5)
            modem.write(b'AT$GPSP=1\r')
            time.sleep(5)
        # open port!
        modem.write(b'AT$GPSNMUN=2,1,0,0,0,0,0\r')
        time.sleep(5)

def stop_streaming():
    with serial.Serial(PORT_GPS, BAUD, timeout=1) as modem:
        modem.reset_input_buffer()
        modem.reset_output_buffer()
        modem.write(b'AT$GPSNMUN=0\r')
        time.sleep(0.5)
        return modem.read_all().decode(errors="ignore")

    

def run():
    global stop_flag
    consecutive_errors = 0
    while not stop_flag:
        try:
            setup_gps()
            with serial.Serial(PORT_GPS, BAUD, timeout=0.1) as ser:
                print("Listening for NMEA...")
                while not stop_flag:
                    try:
                        line = ser.readline().decode(errors="ignore").strip()
                        if not line:
                            consecutive_errors += 1
                            if consecutive_errors > 10:
                                print("Too many consecutive errors, assuming disconnect.")
                                break
                            continue

                        consecutive_errors = 0
                        if line.startswith("$"):
                            print(line)
                        if stop_flag:
                            print("EXITING NOW!!!")

                    except serial.SerialException as e:
                        consecutive_errors += 1
                        print("Serial error: {}".format(e))
                    except Exception as e:
                        print("Unexpected error: {}".format(e))
        except serial.SerialException as e:
            consecutive_errors += 1
            print("Could not open serial port {}: {}".format(PORT_GPS, e))
        except Exception as e:
            print("General error: {}".format(e))
    res = stop_streaming()
    print("stopped streaming with res: {}".format(res))

if __name__ == "__main__":
    n=threading.Thread(target=key_listener).start()
    i=threading.Thread(target=run).start()

```

### 3. Verify Data Stream 
When the script runs successfully, you’ll see a continuous stream of raw NMEA sentences, for example:
```
$GPGGA,120000.00,5540.1234,N,01234.5678,E,1,12,0.8,15.0,M,40.0,M,,*5C
$GPRMC,120000.00,A,5540.1234,N,01234.5678,E,0.13,240.15,060625,,,A*6D
```

These sentences contain the raw GPS position, velocity, and time data updated at 10 Hz.

---

## Troubleshooting 
While configuring your AutoPi device to be able to stream GPS data at 10 Hz, some issues may arise and therefore we are mentioning the most common issues and ways to solve them. 

### GPS Port Not Found
If you receive an error such as:
```python
serial.serialutil.SerialException: [Errno 2] No such file or directory: '/dev/ttyUSB0'
```

* Run dmesg | grep tty on the device to list available serial ports.
* The GPS may appear as /dev/ttyS4, /dev/ttyACM0, or /dev/ttyUSB1 depending on your setup.
* Update the tty_device variable in the script accordingly.

### Permission Denied
If you see a permission error when opening the serial port:
```python
PermissionError: [Errno 13] Permission denied: '/dev/ttyS4'
```

* Run the script as root or add your user to the dialout group:
```
sudo usermod -a -G dialout $USER
```

Then log out and back in.

### No Data Received
If the script runs but no NMEA data is printed:
* Confirm that the `gnss_manager` service is disabled.
* Check that your GPS module has a valid satellite fix (usually indicated by an LED or diagnostic message).
* Try reducing the baud rate (e.g., 9600) if unsure of the GPS module’s settings.

---

## AutoPi Logs

---

In this guide we will talk about how you can manage your AutoPi's logs. The topics that we will
cover are how you can view your device's logs and how you can download the log files to your
computer.

## Viewing Logs

There are two primary methods for viewing your AutoPi's logs. The first method uses some commands
that you can write in the web terminal from the [Cloud](https://my.autopi.io) or the local admin
for your device. The second method retrieves the log files directly from the device through SSH.

### Viewing Logs From the Cloud

To retrieve the primary logs from the device, we have some terminal commands that can be executed
(on [my.autopi.io](https://my.autopi.io/) and [local.autopi.io](http://local.autopi.io/)):

```
$ minionutil.last_logs
$ minionutil.last_errors
$ minionutil.last_startup
```

These functions can also take various parameters. You can check the documentation for those commands
[here](/core/commands/minionutil.md) or by running the following command:

```
$ minionutil.help
```

### Viewing Logs Directly On the Device

If you are logged onto the system using SSH ([How to SSH to your device](how_to_ssh_to_your_device.md))
you can view the log file by running the following command:

```bash
$ less /var/log/salt/minion
```

:::tip
Remember that the timestamps in the log files are in UTC.
:::

## Downloading Logs

Sometimes, if we're having a back and forth on our support channel (support@autopi.io), we might
ask you to provide some log files from your device. Most of the time, it will be the minion log
file (`/var/log/salt/minion`), but sometimes it might also be the syslog file (`/var/log/syslog`).
There are three ways that you can download log files from your device: downloading the files
from the local admin page ([local.autopi.io](http://local.autopi.io)), copying it to your own computer with
the `scp` command or by uploading it to your dropbox account.

### 1. Local Admin Page Download

To download the log files from the local admin page, you will need to connect to the device's WiFi
hotspot first. After you've done that, you can navigate your browser to http://local.autopi.io.

:::tip
If the browser is unable to load the web page because it can't resolve the URL, try typing in the
IP address instead: http://192.168.4.1.
:::

Once you've opened the local admin page, on the right-hand side, you should see a list of the log
files available for downloading. Click on the one you'd like to download.

![local_admin_log_files](/img/getting_started/developer_guides/autopi_logs/local_admin_log_files.jpg)

### 2. SCP (SSH Copy)

You are able to download the minion log file using the `scp` command from your computer. First,
you'll need to have the file in the home directory of the `pi` user. The first two commands should
be run directly on the device (through SSH) and the last one should be run from your own computer.

```bash
# copy the file to the home directory
$ sudo cp /var/log/salt/minion /home/pi

# make sure the pi user owns the file
$ sudo chown pi:pi /home/pi/minion

# finally, exit SSH and run the scp command from your own computer
scp pi@local.autopi.io:~/minion ./
```

After executing those commands, you should have a minion file in your current working directory.

### 3. Uploading the Log File to Your Dropbox

If you're not familiar with SSH or you don't have access to it at the moment, you can instead
upload the log file to your dropbox account. Here are the steps you need to take to get the log
file uploaded:

1. Create a Dropbox app by going here and input like so:
  [https://www.dropbox.com/developers/apps/create](https://www.dropbox.com/developers/apps/create)

  ![dropbox_create_app](/img/getting_started/developer_guides/autopi_logs/dropbox_create_app.png) 

2. Go to the Permissions tab and make sure that the **files.content.write** permission is enabled.

3. Now go back to the settings tab and click the "Generate" button under **Generated access token**.

4. You can now use the below commands to send files to your new dropbox folder located in
"dropbox/Apps/AutoPi Logfiles". Execute them in the web terminal, or in the SSH terminal by
prepending `autopi` before the command.
:::note
Remember to replace the YOUR_ACCESS_TOKEN with the actual token you received in the last step.
:::

  ```bash
  # web terminal
  $ fileutil.upload /var/log/salt/minion gzip=True service=dropbox token=YOUR_ACCESS_TOKEN

  # SSH
  $ autopi fileutil.upload /var/log/salt/minion gzip=True service=dropbox token=YOUR_ACCESS_TOKEN
  ```

5. You should now be able to see the uploaded file in your dropbox folder.

6. You can also upload the file to dropbox using raw Linux commands. Here are the commands:

  ```
  cmd.run 'gzip --keep -f /var/log/salt/minion'
  ```

  And then run the following command to upload the data:

  ```bash
  cmd.run 'curl -X POST https://content.dropboxapi.com/2/files/upload \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Dropbox-API-Arg: {\"path\": \"/minion.gz\"}" \
  --header "Content-Type: application/octet-stream" \
  --data-binary @/var/log/salt/minion.gz'
  ```

  :::note
   If the above command does not work, you can try this one instead (*Same command on a
  single line, without the slashes*)
  :::

  ```bash
  cmd.run 'curl -X POST https://content.dropboxapi.com/2/files/upload --header "Authorization: Bearer YOUR_ACCESS_TOKEN" --header "Dropbox-API-Arg: {\"path\": \"/minion.gz\"}" --header "Content-Type: application/octet-stream" --data-binary @/var/log/salt/minion.gz'
  ```

## Log Rotation
Every so often the logs on your AutoPi device will [rotate](https://en.wikipedia.org/wiki/Log_rotation).
This essentially means that the current log files will be compressed and renamed so that a new log
file can start being used. This is done in order to keep the size of the log files relatively small.

#### `/var/log/salt/minion`
By default, the salt minion log file is being rotated every week. Also by default, there will be 7
older versions of the log file that will be kept on the SD card before being removed. You can
double check those defaults if you read the `/etc/logrotate.d/salt-common` file which has those
definitions.

#### `/var/log/syslog`
By default, the syslog file is being rotated every day. Also by default, there will be 7 older
versions of the log file that will be kept on the SD card before being removed. You can double check
those defaults if you read the `/etc/logrotate.d/rsyslog` file which has those definitions.

---

## Build a Grafana Dashboard Pipeline for AutoPi CAN-FD Pro Data in Amazon S3

---

This guide shows how to take AutoPi CAN-FD Pro logged data that is already being uploaded to Amazon S3, process it with AWS Lambda, store it in a query-friendly Parquet format, and visualize it in Grafana through Athena. AutoPi CAN-FD Pro supports output to an AWS S3 bucket, and the AutoPi REST API documentation also covers API-based export and device settings if you want to add metadata or automate parts of the setup later.

The recommended data flow is:

  AutoPi CAN-FD Pro
  →
  S3 raw bucket / prefix
  →
  S3 ObjectCreated event
  →
  Lambda
  →
  Parquet in curated S3 prefix
  →
  Glue / Athena
  →
  Grafana

For high-volume CAN logging, this is a better fit than pulling bulk data through the AutoPi API. The S3 bucket should remain the primary ingestion path, while the AutoPi API is best used for optional enrichment, backfill, or automation of configuration. AWS supports invoking Lambda directly from S3 object-created events, and Grafana supports Athena as a query layer for S3-backed datasets.

---

## 1. Architecture overview

Use two S3 locations:

* A **raw** location for the files uploaded by the CAN-FD Pro.
* A **curated** location for transformed Parquet files used by Athena and Grafana.

A simple structure is:

```text
s3://autopi-canfd-raw/
s3://autopi-canfd-curated/can_fd_parquet/
```

The raw bucket receives files from the device. S3 then emits an ObjectCreated event, which triggers Lambda. Lambda reads the file, normalizes the records, and writes partitioned Parquet output to the curated bucket. Athena reads the curated dataset through the Glue Data Catalog, and Grafana queries Athena. This pattern follows AWS’s standard S3-to-Lambda processing model and Grafana’s Athena integration model.

A practical partition layout is:

```
s3://autopi-canfd-curated/can_fd_parquet/
  device_id=<device_id>/
  channel=<channel>/
  year=<YYYY>/
  month=<MM>/
  day=<DD>/
```

That partitioning works well for common dashboard filters such as device, CAN channel, and time window. Parquet is the preferred format here because it is columnar and much more efficient for Athena queries than raw JSON or JSONL.

---

## 2. When to use the AutoPi API

The AutoPi API is useful, but it should not be the main path for large CAN log ingestion when the device is already writing files to S3. AutoPi’s API export guide exposes both aggregated and raw telemetry export, and AutoPi’s REST API also supports changing device settings directly, which makes it suitable for optional tasks around the pipeline rather than the pipeline itself.

Use the AutoPi API for:
* Mapping device_id, unit_id, or vehicle identifiers to human-readable names.
* Adding fleet, project, or customer metadata.
* Backfilling data if an S3 upload was missed.
* Automating device configuration so S3 logging is enabled consistently across devices. 

Do not use it for:
* Continuously reading high-rate CAN logs for dashboard ingestion.
* Replacing the S3 upload path for bulk analytics data. That split keeps the pipeline simple, scalable, and aligned with the existing CAN-FD Pro setup documented by AutoPi.

> **Note** If you want to learn more about how API works, check out this guide: [Getting started with API](https://docs.autopi.io/getting_started/api/). 

---

## 3. Prerequisites
Before starting, make sure the following are in place:
* An AutoPi CAN-FD Pro already configured to log to S3.
* An AWS account with access to S3, Lambda, IAM, Glue, and Athena. 
* A Grafana instance, either self-hosted or Amazon Managed Grafana. 
* Sample log files from the CAN-FD Pro so you can validate the input format. 
* An AutoPi API token only if you plan to use metadata enrichment or automation. 

### 3.1 Uploading Data to AWS S3 Bucket from AutoPi CAN-FD Pro

The AutoPi CAN-FD Pro device supports two types of data logging:
* Raw data – captures everything exactly as received. 
* Decoded data – data is processed and translated before storing. 

By default, all data is logged and stored locally on the device. However, you can easily configure the device to upload your logged data directly to an AWS S3 bucket (both Raw data and Decoded data). Here’s how to do it:
* On your Pro device, go to: CAN Logging → Loggers.
* Create a new logger or edit an existing one.
* Navigate to Step 4: Outputs. This is where you define where the logged data should be sent. You can also read more here: [Output handler configuration explained](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/#step-4-outputs). 

![Output handler for S3](/img/getting_started/autopi_canfd_pro/aws_creation/channel_s3_bucket.png)

* To upload to AWS S3, fill in the following fields:
    * Access Key ID – your AWS access key.
    * Secret Access Key – your AWS secret key.
    * Destination Path – the URL of your S3 bucket (e.g., s3://your-bucket-name/folder)
* (Optional) Configure Advanced Settings:
    * Exclude Patterns – to filter out specific data
    * Sync Interval – how often the device syncs data
    * Error Retry Interval – wait time before retrying a failed upload
    * Job Timeout – how long to wait before canceling a sync job
* Save your settings.

Once saved, your device will begin uploading data to the specified S3 bucket based on the configuration you've chosen.

> **Note:** You can read more about advanced settings for the S3 upload process here: [Advanced settings for Output Handler](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/#advanced-settings-for-output-handler)

### 3.2 AWS account with access to S3, Lambda, IAM, Glue, and Athena
Ensure that your AWS account is created and that you have access to the following services:
* [Have an AWS account](https://aws.amazon.com/getting-started/) and ensure the [IAM (Identity and Access Management) console](https://docs.autopi.io/getting_started/autopi_canfd_pro/set_up_AWS_S3_bucket/#step-1-create-users-with-correct-permissions) is set up correctly.
* [Setup your Amazon S3](https://aws.amazon.com/s3/getting-started/)
* [Setup your AWS Lambda](https://docs.aws.amazon.com/lambda/)
* [Setup your AWS Glue](https://aws.amazon.com/glue/?nc2=type_a)
* [Setup your Amazon Athena](https://aws.amazon.com/athena/?nc2=type_a)

### 3.3 A Grafana instance, either self-hosted or Amazon Managed Grafana
Browse the available Grafana features and integrations, then choose between self-hosted Grafana and [Amazon Managed Grafana](https://aws.amazon.com/blogs/mt/amazon-managed-grafana-getting-started/). You can read more here: [Grafana](https://grafana.com/).

### 3.4 Sample log files from the CAN-FD Pro so you can validate the input format
Collect at least one recent raw file and one decoded file from your S3 raw prefix. You will use these samples to verify parsing logic and schema mapping before enabling the full pipeline.

### 3.5 Deployment checklist before you continue
Before building Lambda and Grafana, verify these platform settings once:
* Raw and curated S3 paths are separate, and lifecycle rules are enabled for the raw bucket if you do not need long retention.
* S3 event notifications on the raw bucket are scoped to the upload prefix only.
* Athena has a query results S3 location configured (workgroup setting).
* Glue Data Catalog database exists and is in the same region as Athena/Grafana.
* Lambda timeout and memory are sized for your average file size.
* CloudWatch log retention is configured (for example 14, 30, or 90 days).

---

## 4. Configure CAN-FD Pro to upload to S3
Start by following AutoPi’s existing S3 output handler flow for the CAN-FD Pro. The device already supports sending logger output to AWS S3, so the goal here is not to invent a new upload mechanism, only to consume what the device already sends.

At this stage, validate:
* Files are arriving in the expected raw S3 prefix.
* Filenames and folder structure are predictable.
* The payload format is known: JSON, JSONL, gzip-compressed JSONL, or another file type.
* Each record includes enough context such as timestamp, device ID, channel, and message/signal content.

Before building Lambda, download one or two real sample files and inspect them. This is important because the transform logic depends on the exact structure written by the device.

---

## 5. Design the target analytics schema
Grafana works best when the data is flattened into a query-friendly table rather than left in a deeply nested raw format. For decoded signal data, a good starting schema is one row per signal value. For raw traffic analysis, you can create a second table with one row per CAN frame.

Suggested decoded signal table:

```
event_time          timestamp
device_id           string
unit_id             string
vehicle_id          string
channel             string
logger_type         string
message_id          string
is_extended_id      boolean
is_fd               boolean
dlc                 int
payload_hex         string
signal_name         string
signal_value_double double
signal_value_text   string
source_file         string
ingested_at         timestamp
year                string
month               string
day                 string
```

Suggested raw frame table:
```
event_time          timestamp
device_id           string
unit_id             string
vehicle_id          string
channel             string
message_id          string
is_extended_id      boolean
is_fd               boolean
dlc                 int
payload_hex         string
source_file         string
ingested_at         timestamp
year                string
month               string
day                 string
```

Use the decoded table for dashboards and the raw table for debugging or advanced engineering analysis. That separation keeps dashboard queries lighter and easier to maintain.

---

## 6. Create the Lambda function
The Lambda function should stay narrow in scope:
* Read the newly uploaded S3 object.
* Decompress it if needed.
* Parse and normalize the records.
* Write Parquet to the curated S3 location.
* Avoid reprocessing the same file if an event is retried. 

AWS documents S3 object-created events as a standard Lambda trigger pattern.

### 6.1 Runtime and dependencies
Use Python 3.11 or newer if possible. For Parquet output, include:
* `pandas`
* `pyarrow`

For larger dependencies, package them with a Lambda layer or use a container-based Lambda deployment. The code below assumes the input is JSON lines or gzip-compressed JSON lines and that the records are already either decoded or at least structured enough to normalize.

### 6.2 Environment variables
Create these Lambda environment variables:
* `CURATED_BUCKET=autopi-canfd-curated`
* `CURATED_PREFIX=can_fd_parquet`

Optional but recommended:
* `RAW_PREFIX=canfd/raw/` (skip keys outside this prefix)
* `MAX_RECORDS_PER_FILE=500000` (guardrail for malformed files)

### 6.3 Lambda example

```python
import os
import io
import json
import gzip
import boto3
import pandas as pd
from urllib.parse import unquote_plus
from datetime import datetime, timezone

s3 = boto3.client("s3")

CURATED_BUCKET = os.environ["CURATED_BUCKET"]
CURATED_PREFIX = os.environ.get("CURATED_PREFIX", "can_fd_parquet")

def read_s3_object(bucket, key):
    obj = s3.get_object(Bucket=bucket, Key=key)
    data = obj["Body"].read()

    if key.endswith(".gz"):
        data = gzip.decompress(data)

    return data.decode("utf-8")

def parse_records(text):
    rows = []

    for line in text.splitlines():
        line = line.strip()
        if not line:
            continue

        record = json.loads(line)

        ts = record.get("timestamp")
        frame = record.get("frame", {})
        signals = record.get("signals") or {}

        base = {
            "event_time": ts,
            "device_id": record.get("device_id"),
            "unit_id": record.get("unit_id"),
            "vehicle_id": record.get("vehicle_id"),
            "channel": record.get("channel"),
            "logger_type": record.get("logger_type"),
            "message_id": frame.get("id"),
            "is_extended_id": frame.get("extended"),
            "is_fd": frame.get("fd"),
            "dlc": frame.get("dlc"),
            "payload_hex": frame.get("data"),
        }

        if signals:
            for signal_name, signal_value in signals.items():
                row = dict(base)
                row["signal_name"] = signal_name
                if isinstance(signal_value, (int, float)):
                    row["signal_value_double"] = float(signal_value)
                    row["signal_value_text"] = None
                else:
                    row["signal_value_double"] = None
                    row["signal_value_text"] = str(signal_value)
                rows.append(row)
        else:
            row = dict(base)
            row["signal_name"] = None
            row["signal_value_double"] = None
            row["signal_value_text"] = None
            rows.append(row)

    return rows

def write_parquet(rows, source_bucket, source_key):
    if not rows:
        return {"rows_written": 0}

    df = pd.DataFrame(rows)
    df["event_time"] = pd.to_datetime(df["event_time"], utc=True, errors="coerce")
    df["ingested_at"] = datetime.now(timezone.utc)

    df["year"] = df["event_time"].dt.strftime("%Y")
    df["month"] = df["event_time"].dt.strftime("%m")
    df["day"] = df["event_time"].dt.strftime("%d")
    df["source_file"] = f"s3://{source_bucket}/{source_key}"

    buffer = io.BytesIO()
    df.to_parquet(buffer, index=False, engine="pyarrow")

    first = df.iloc[0]
    device_id = first.get("device_id") or "unknown-device"
    channel = first.get("channel") or "unknown-channel"
    year = first.get("year") or "unknown-year"
    month = first.get("month") or "unknown-month"
    day = first.get("day") or "unknown-day"

    out_name = source_key.split("/")[-1].rsplit(".", 1)[0] + ".parquet"
    out_key = (
        f"{CURATED_PREFIX}/"
        f"device_id={device_id}/"
        f"channel={channel}/"
        f"year={year}/month={month}/day={day}/"
        f"{out_name}"
    )

    s3.put_object(
        Bucket=CURATED_BUCKET,
        Key=out_key,
        Body=buffer.getvalue(),
        ContentType="application/octet-stream",
    )

    return {
        "rows_written": len(df),
        "output_key": out_key,
    }

def lambda_handler(event, context):
    results = []

    for record in event.get("Records", []):
        if record.get("eventSource") != "aws:s3":
            continue

        bucket = record["s3"]["bucket"]["name"]
        key = unquote_plus(record["s3"]["object"]["key"])

        if not (key.endswith(".json") or key.endswith(".jsonl") or key.endswith(".gz")):
            results.append({"skipped": key, "reason": "unsupported extension"})
            continue

        text = read_s3_object(bucket, key)
        rows = parse_records(text)
        result = write_parquet(rows, bucket, key)
        results.append({"source_key": key, **result})

    return {"results": results}
```

This example is intentionally simple. In production, add dead-letter handling, structured logging, schema versioning, and duplicate protection. S3 event notifications can be retried, so the function should be idempotent. AWS’s S3 and Lambda documentation is the reference point for this event-driven behavior, such as: [Process Amazon S3 event notifications with Lambda](https://docs.aws.amazon.com/lambda/latest/dg/with-s3.html).

### 6.4 Production hardening for Lambda
Use these production defaults so the pipeline remains stable under load:
* Enable Lambda retries with an on-failure destination (SQS or SNS) or a dead-letter queue.
* Add idempotency: store processed `bucket + key + eTag` in DynamoDB and skip if already processed.
* Set reserved concurrency if you need to protect downstream services.
* Log structured JSON lines with source key, row count, parse failures, and output key.
* Emit CloudWatch metrics (files processed, rows written, rows failed, duration).

---
## 7. Set up the S3 event trigger
Configure the raw bucket so that `ObjectCreated` events invoke the Lambda function. AWS supports Lambda directly as an S3 event destination, and the bucket notification is the standard way to do this.

Recommended settings:
* Event type: `ObjectCreated:*`.
* Prefix filter: the raw CAN-FD Pro upload folder only.
* Suffix filter: `.json`, `.jsonl`, or `.gz` depending on the actual file type.

Adding S3 Trigger for Lambda: 
* Open the AWS Lambda console and navigate to your existing function.
* Click 'Add trigger'.
* In the trigger settings:
  * Set Source to S3.
  * Select the Bucket used by the logger uploads.
  * Specify Suffix depending on the actual file type. 
  * Acknowledge the warning prompt at the bottom.
* Save the trigger configuration.

> **Warning:** be careful not to configure the curated output prefix as a trigger source, otherwise the Lambda can trigger itself recursively when it writes Parquet back to S3. AWS explicitly warns about this kind of loop when using S3 as a Lambda trigger.

---
## 8. IAM permissions
The Lambda execution role needs permission to:
* Read objects from the raw S3 bucket.
* Write objects to the curated S3 bucket.
* Write logs to CloudWatch.

**Configure Permissions through AWS Management Console (Execution Role):**
* Option 1: If you are uploading for the first time, create an IAM role with the required permissions. You can read more in this guide: [Create a role to delegate permissions to an AWS service](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console)
* Option 2: If you have already created a role, you can continue by selecting the existing role.
  * Select 'Use an existing role'.
  * Select the Existing role as 'example' from the drop-down options.
  * Select 'Create function'.

If you add API enrichment, the AutoPi API call itself does not require AWS IAM, but the Lambda will need access to the secret or token stored in environment variables or AWS Secrets Manager. AutoPi’s API uses token-based authentication, so store that token securely and never hardcode it in the source.

A minimal IAM policy for S3 access would cover:
* `s3:GetObject` on the raw prefix
* `s3:PutObject` on the curated prefix
* `s3:ListBucket` on both buckets if needed for checks

---
## 9. Create the Athena dataset
Once Parquet files are being written to the curated prefix, expose them to Athena through Glue. You can either use a Glue crawler or create the Athena table manually. Grafana then queries Athena rather than reading the S3 files directly. Grafana’s Athena data source documentation expects a standard Athena setup behind it. You can read more here: [Amazon Athena data source for Grafana](https://grafana.com/docs/plugins/grafana-athena-datasource/latest/).

### 9.1 Example Athena table

```SQL
CREATE EXTERNAL TABLE IF NOT EXISTS autopi_canfd_signals (
  event_time timestamp,
  device_id string,
  unit_id string,
  vehicle_id string,
  logger_type string,
  message_id string,
  is_extended_id boolean,
  is_fd boolean,
  dlc int,
  payload_hex string,
  signal_name string,
  signal_value_double double,
  signal_value_text string,
  source_file string,
  ingested_at timestamp
)
PARTITIONED BY (
  channel string,
  year string,
  month string,
  day string
)
STORED AS PARQUET
LOCATION 's3://autopi-canfd-curated/can_fd_parquet/';
```

After creating the table, either run a Glue crawler or add partitions manually. If you ingest data continuously, configure partition discovery as part of the workflow so new data becomes queryable without manual intervention. Athena and Glue are designed for this S3-plus-catalog pattern.

### 9.2 Partition refresh and smoke test
If you are not using a crawler, run partition discovery after new data arrives:

```SQL
MSCK REPAIR TABLE autopi_canfd_signals;
```

Then run a quick validation query:

```SQL
SELECT count(*) AS rows_total
FROM autopi_canfd_signals
WHERE year = date_format(current_date, '%Y')
  AND month = date_format(current_date, '%m');
```

If this query returns rows, Athena can see your curated data and partitions.

---

## 10. Connect Grafana to Athena

The [Amazon Athena](https://grafana.com/grafana/plugins/grafana-athena-datasource/) data source plugin allows you to query and visualize Amazon Athena data metrics from within Grafana.

Step 1: Prepare Athena query output and workgroup
* In Athena, create or select a workgroup for Grafana.
* Configure an S3 output location for Athena query results.
* Confirm Grafana credentials/role can write to this output location.

Step 2: Add Athena as a data source in Grafana
* Open [Grafana](https://grafana.com/auth/sign-in/).
* Go to Connections → Data Sources.
* Click "Add new data source" button in the top right corner.
* Search for Amazon Athena plugin.
* Install Amazon Athena plugin. You can also follow the installation steps in this [guide](https://grafana.com/grafana/plugins/grafana-athena-datasource/?tab=installation). 

Step 3: Configure authentication for Grafana
Recommended for Amazon Managed Grafana:
* Use IAM role-based access (workspace role or assumed role), not long-lived access keys.

For self-hosted Grafana, if you use IAM user credentials:
* Open the AWS IAM Console.
* Go to Users → click Create User.
* Enter a username and click Next.
* For permissions, choose Attach policies directly.
* Select the required Athena and S3 access policies.
* Click Create user.
* Copy or download the Access Key ID and Secret Access Key and store them securely.
* Click Done.

Step 4: Configure Athena plugin in Grafana
* In Grafana, open the Athena data source you added and go to settings.
* Configure authentication based on your setup:
  * Amazon Managed Grafana: select IAM role/assume-role settings.
  * Self-hosted Grafana with IAM user: enter Access Key ID and Secret Key.
* Fill in the following settings:
  * Default Region (where your S3 bucket and Athena DB are).
  * Catalog (typically `AwsDataCatalog`).
  * Workgroup.
  * Database (Athena DB containing your tables).
  * Output location: S3 bucket folder for query results.
* Click Save & Test and confirm the data source connects successfully.

Step 5: Build a dashboard in Grafana
* Go to Dashboards → New → New Dashboard.
* Click Add visualization.
* Select your Athena data source.
* In the query editor, write your SQL query.
* Click Run query to preview results.
* Adjust the panel visualization (graph, table, etc.) based on your preferences. 

Step 6: Save and use
* Save the panel and add more panels as needed.
* Save the dashboard.
* Setup is complete. Your Grafana dashboard now pulls data from AWS Athena.

For Amazon Managed Grafana, AWS also documents [A guided Athena connection flow](https://docs.aws.amazon.com/vpc/latest/userguide/flow-logs-athena.html). For self-hosted Grafana, use the [Athena data source plugin](https://grafana.com/grafana/plugins/grafana-athena-datasource/) and [Standard AWS credentials](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) or [IAM role configuration](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html).

### Example Grafana queries
Time series of a decoded signal: 

```SQL
SELECT
  event_time AS time,
  signal_value_double AS value,
  device_id
FROM autopi_canfd_signals
WHERE signal_name = 'VehicleSpeed'
  AND device_id = '${device_id}'
  AND channel = 'can0'
  AND $__timeFilter(event_time)
ORDER BY event_time
```

Last known value per signal: 
```SQL
SELECT
  signal_name,
  max_by(signal_value_double, event_time) AS latest_value,
  max(event_time) AS latest_ts
FROM autopi_canfd_signals
WHERE device_id = '${device_id}'
  AND $__timeFilter(event_time)
GROUP BY signal_name
ORDER BY signal_name
```

Signal count per minute: 
```SQL
SELECT
  date_trunc('minute', event_time) AS time,
  count(*) AS value
FROM autopi_canfd_signals
WHERE device_id = '${device_id}'
  AND $__timeFilter(event_time)
GROUP BY 1
ORDER BY 1
```

Grafana’s Athena integration supports SQL queries and time filter macros for dashboard use.

---

## 11. Optional AutoPi API enrichment
If the raw log files do not contain enough business context, enrich the data in one of two ways:
* Call the AutoPi API from Lambda at ingest time.
* Run a separate periodic metadata sync job and join on device_id in Athena. 

The second option is usually cleaner. It avoids adding API latency and possible rate-limit pressure to the ingest path. AutoPi’s API documentation confirms that data export and device management endpoints are available, which makes a scheduled metadata sync practical.

A simple pattern is:
* Nightly job fetches device and vehicle metadata from AutoPi.
* Writes a small metadata table to S3 as Parquet.
* Athena joins telemetry data with metadata table in Grafana queries.

This keeps the Lambda function focused on file transformation and avoids coupling the main ingest path to an external API call for every uploaded log file.

---

## 12. Performance recommendations for high-volume logging
For high-volume CAN data, the most important design choices are around query efficiency rather than just ingestion. Athena charges by data scanned, and Grafana panel performance depends heavily on how much data each query needs to read. 
> **Warning:** The Athena/Grafana approach is strong, but only if the dataset is curated properly.

**Recommended practices:**
* Write Parquet, not JSON, to the analytics bucket.
* Partition by device, channel and date.
* Keep one curated table for decoded signals and another for raw frames.
* Downsample or pre-aggregate extremely high-rate signals if the dashboard only needs overview metrics.
* Keep the AutoPi API out of the core ingest loop.
* Use prefix filters on S3 event notifications so Lambda only processes relevant files.
* Make the Lambda function idempotent to handle retries safely.

AWS’s S3 event and Lambda model supports this event-driven pipeline well, while Grafana and Athena are suited to curated analytical datasets rather than arbitrary raw log dumps.

---

## 13. Troubleshooting
**Lambda is not triggered**
Check the S3 bucket notification configuration, the event type, and the Lambda resource-based permission that allows S3 to invoke the function. 
Recommendation: AWS documents both the event notification setup and the Lambda S3 trigger requirements.

**Athena table shows no rows**
Confirm the Parquet files are being written to the same S3 prefix referenced by the table and that partitions have been added or crawled. Athena depends on the table location and partition metadata being correct.

**Grafana queries are slow**
Check whether the query filters on partition columns such as device_id, channel, year, month, and day. If not, Athena will scan far more data than needed. Using Parquet and proper partitions is the main fix.

**Grafana says "AccessDenied" or "Unable to verify/create output bucket"**
Check that Grafana's AWS identity can run Athena queries, access Glue metadata, and write to the Athena query result S3 path. Also verify the selected Athena workgroup and region match your dataset.

**Input format does not match the Lambda parser**
Download a real sample file from the raw bucket and adapt the parser to the exact structure. The provided Lambda code is a starting point, not a guarantee of a perfect match to every logger output format. Our [CAN logging guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/) is the right reference point for understanding what the device produces.

---

## 14. Summary
The simplest and most scalable way to build Grafana dashboards for AutoPi CAN-FD Pro log data is to keep the device’s existing S3 upload path, add an S3-triggered Lambda transform step, write partitioned Parquet for Athena, and connect Grafana to Athena.

AutoPi already supports S3 output for CAN-FD Pro, AWS supports direct S3-to-Lambda event processing, and Grafana supports Athena as a data source. The AutoPi API is useful for enrichment and automation, but it should stay optional rather than becoming the main ingestion path for large logging volumes.

---

## 15. End-to-end validation checklist
Use this final checklist before sharing dashboards with other users:
* Device uploads a new CAN log file to the raw S3 prefix.
* Lambda is invoked and writes a Parquet object to the curated prefix.
* Glue/Athena can discover the new partition.
* Athena test query returns rows for expected device/channel/date filters.
* Grafana Athena data source passes "Save & Test".
* At least one panel renders values over time and updates with new data.
* CloudWatch shows no repeated parse or permission errors.

---

## Configuring MQTT

---

## Overview

This guide walks you through a complete MQTT setup between an AutoPi device and a Mosquitto broker.

By the end, you will have:

1. A working MQTT broker on Linux.
2. An AutoPi device connected in either direct-connect or broker-bridge mode.
3. MQTT returners enabled on common data sources (loggers, services, jobs).
4. A validation flow and troubleshooting checklist.

## Before You Start

Make sure you have the following:

* A Linux server reachable by your AutoPi device (examples use Debian 11).
* AutoPi Cloud permissions to edit Advanced Settings, Services, Loggers, and Jobs. Read more here: [Account Permissions](https://docs.autopi.io/cloud/accounts/#modifying-user-permissions).
* Network access from device to broker on the MQTT port:
    * 1883 for non-TLS
    * 8883 for TLS
* A mode choice:
    * Direct-connect mode: faster setup, but no local buffering during outages.
    * Broker-bridge mode: more resilient, with buffering on the device.

:::info
If you are unsure which mode to use, start with direct-connect mode for testing, then move to broker-bridge mode for production-like behavior.
:::

:::warning
The initial broker setup in this guide is intended for testing. Do not use `allow_anonymous true` in production.
:::

:::note
This setup is not available for AutoPi Mini devices. There might be a different option available at no cost. If you are interested, contact our sales team at sales@autopi.io.
:::

## 1. Set Up the Endpoint Broker

Install Mosquitto and MQTT client tools on your Linux server:

```python
sudo apt update
sudo apt install -y mosquitto mosquitto-clients
```

For quick testing, create a minimal open configuration:

```bash
sudo sh -c "echo 'allow_anonymous true
listener 1883 0.0.0.0' > /etc/mosquitto/conf.d/mosquitto.conf"
```

Restart and verify broker status:

```bash
sudo systemctl restart mosquitto.service
sudo systemctl status mosquitto.service
```

Test publish/subscribe locally.

Terminal 1:

```python
mosquitto_sub -h localhost -t test/my_topic/#
```

Terminal 2:

```python
mosquitto_pub -h localhost -t test/my_topic -m "Test data from a local source"
```

Expected result:
![publish_subsribe_server_test_expected_result](/img/getting_started/developer_guides/configuring_MQTT/pub_sub_server_test.png)

:::tip
If your broker runs behind a firewall, allow inbound TCP traffic on the MQTT listener port (for example `1883`).
:::

## 2. Choose Device Connection Mode

Choose one of the following modes before continuing.

| Mode | Best for | Buffering when offline | Complexity |
|:---|:---|:---:|:---:|
| Direct-connect | Fast testing and simple setups | No | Low |
| Broker-bridge | Reliable operation in unstable networks | Yes | Medium |

### Direct-Connect Mode

![direct_connect_diagram](/img/getting_started/developer_guides/configuring_MQTT/direct-connect_diagram.png)

In AutoPi Cloud, go to Device > Advanced Settings > MQTT > Returner and set:

* Returner > Enabled: True
* Returner > host: `<host></host>`
* Returner > port: `<port></port>`.

:::warning
Direct-connect mode is often configured first without TLS for testing. Use authentication and TLS before production use.
:::

Next, add an MQTT returner to at least one data source that produces frequent data (for example voltage or GPS). After saving and syncing, messages should start appearing on your broker.

This mode is the fastest to configure. If the device is offline, data generated during that period is not buffered locally.

### Broker-Bridge Mode

![broker_bridge_diagram](/img/getting_started/developer_guides/configuring_MQTT/broker-bridge_diagram.png)

> Important: settings under Broker > ... affect the local broker on the device, not the Returner client settings used in direct-connect mode.

#### Setup Broker-Bridge Mode

Set:
* In AutoPi Cloud, navigate to Device > Advanced Settings > MQTT.
* Broker > Install: `Mosquitto v1.x` (or newer if available).
* Bind > Address: specify the local bind address for the device broker.
* Bind > Port: specify the local port for the device broker.
* Custom > Configuration:
    ```python
    * connection <connection_name></connection_name>
    * address <host></host>:<port></port>
    * topic # out 1 "" <topic_name></topic_name>/
    * bridge_attempt_unsubscribe false
    * keepalive_interval 15
    * notifications false
    * restart_timeout 10
    * cleansession false
    * max_queued_messages 10000
    * autosave_interval 300
    * queue_qos0_messages true 
    * try_private false
    * bridge_protocol_version mqttv311
    * max_inflight_messages 10
    ```
    > The custom bridge lines are written to `/etc/mosquitto/conf.d/custom.conf` on the device. For full parameter descriptions, see the [Mosquitto configuration reference](https://mosquitto.org/man/mosquitto-conf-5.html).
* Returner > Enabled: True. 
* Save. 
* Sync the changes to the device. 
* (Validation) Run this test command in AutoPi Cloud terminal in order to double check if the connection has been made correctly:
    ```python
    cmd.run 'mosquitto_pub -h localhost -t test/my_topic -m "my test data"'
    ```
* (Validation) If this appears on the remote subscriber, the bridge is working:
![publish_from_cloud](/img/getting_started/developer_guides/configuring_MQTT/pub_from_cloud.png)

:::note
If `mosquitto_pub` is unavailable on the device, it can be installed from apt (it is not used outside of this test).
```python  
cmd.run "apt install -y mosquitto-clients"
```

![installinging_through_apt](/img/getting_started/developer_guides/configuring_MQTT/installing_mosq_clients.png)
:::

#### Example of Broker-Bridge Mode on AutoPi Cloud
This is an example of broker-bridge mode:
![publish_from_cloud](/img/getting_started/developer_guides/configuring_MQTT/example-broker-bridge.png)
    > The custom bridge lines are written to `/etc/mosquitto/conf.d/custom.conf` on the device. For full parameter descriptions, see the [Mosquitto configuration reference](https://mosquitto.org/man/mosquitto-conf-5.html).

## 3. Add MQTT Returners to Data Sources

This section covers adding MQTT returners to the three main data sources: loggers, services, and jobs.

| Data point | Source | MQTT topic |
|:---:|:---:|:---:|
| PID data | Logger | `obd/<LOGGER_NAME>` |
| CAN data | Service | `obd/<LOGGER_NAME>` |
| GPS location | Service | `track/pos` |
| Accelerometer readings | Service | `acc/xyz` |
| Voltage | Service | `spm/bat` |
| Events | Service | `reactor` |
| Device temperature | Job | `rpi/temp` |

### Loggers

Use loggers when you want to publish periodic OBD-II PID values, such as engine and vehicle diagnostics.

For each logger of type OBD-II PID:

1. Navigate to Device > Loggers. 
2. Open the logger.
3. Select Advanced.
4. Set Returner to MQTT.
5. Save.

![setup_pid_mqtt_returner](/img/getting_started/developer_guides/configuring_MQTT/edit_logger_mqtt.png)

### Services

Use services when you want to publish live worker or reactor output, most commonly CAN, GPS, accelerometer, voltage, or event data. A service can serve as a data source in two ways: through workers and through reactors. Most commonly, you will use this for CAN data.

Follow these steps:
* Navigate to Device > Services.
* Select `obd_manager`.
* Create a new worker, or open an existing worker.
* Under workflows, find Returner and add `mqtt`.
* Save.

![can_mqtt_setup_step_1](/img/getting_started/developer_guides/configuring_MQTT/workflow_mqtt.png)

Other service data points:

| Data point | Source path |
|:---:|:---:|
| CAN data | `obd_manager` > Workers > `can_logger` |
| GPS location | `gnss_manager` > Workers > `poll_logger` |
| Accelerometer readings | `acc_manager` > Workers > `xyz_logger` |
| Voltage | `spm_manager` > Workers > `_battery_checker` |
| Events | `event_reactor` > Reactors > `cache_events` |

### Jobs

Use jobs when you want to publish scheduled command output, such as periodic device health metrics.

* Navigate to Device > Jobs.
* Open the job you want to update.
* Under Returner, set `mqtt`.

> Note: jobs support only one returner. A single job cannot send output to both MQTT and AutoPi Cloud at the same time.

![rpi_temp_job_with_mqtt_returner](/img/getting_started/developer_guides/configuring_MQTT/jobs_mqtt.png)

## 4. Validate End-to-End Data Flow

After setup, subscribe on your server and confirm live messages:

    ```bash
    mosquitto_sub -h <host> -t '#'
    ```

Example output:
![final_expected_result](/img/getting_started/developer_guides/configuring_MQTT/final_result.png)

Expected behavior:

- Incoming topics match configured data sources.
- In broker-bridge mode, queued messages continue after reconnect.

## Production Hardening Checklist

Before moving to production:

1. Disable anonymous access (`allow_anonymous false`).
2. Create broker users/passwords and update device credentials.
3. Restrict topic permissions with ACLs.
4. Use TLS (`8883`) and certificates where possible.
5. Restrict broker exposure with firewall rules and trusted IP ranges.
6. Monitor broker disk usage and queue limits.

## Troubleshooting

1. Broker service does not start after sync (broker-bridge mode):
    - Check status and logs on the device.
    - Inspect `/var/log/mosquitto/mosquitto.log` for syntax errors in custom bridge configuration.
2. No data on remote broker:
    - Verify host, DNS resolution, port, and firewall path from device to broker.
    - Confirm all MQTT settings were saved and synced.
    - Verify that at least one logger, service, or job has Returner set to `mqtt`.
3. Data appears intermittently:
    - Validate network stability and packet loss.
    - Prefer broker-bridge mode for buffering during outages.
    - Check queue settings such as `max_queued_messages`.
4. Messages appear locally but not remotely (broker-bridge mode):
    - Confirm `address` in bridge configuration points to the remote broker.
    - Confirm the remote broker accepts incoming client connections from the device IP.

---

## Enabling Bluetooth on Legacy Devices With STN Chips

:::note
  This guide only works with legacy devices using STN/ELM based chips for automotive interface. No devices sold after February 2021 contains the STN chip. 

  If you have a newer AutoPi device (such as TMU CM4 or CAN-FD Pro), follow the [newer Bluetooth guide](./how_to_use_bluepy.md).
:::

In this guide we will take a look at how you can enable Bluetooth for [AutoPi](https://www.autopi.io) devices that use the
STN chip. By default the STN chip and Bluetooth don't work well together, so we will need to disable
the STN chip entirely in order to get the Bluetooth functionality to work properly and the device to
be kept running despite the STN chip's absence.

## Enabling Bluetooth
1. **Disable uart_sleep**  
  First, we will need to disable the STN chip's uart sleep functionality. When disabling the
  obd_manager (next step), we also disable a key heartbeat worker that keeps the device up and
  running by communicating to the STN chip. If the STN chip hasn't seen any communication in 15
  minutes (by default), then it will put itself and the Raspberry Pi to hibernation - we want to
  avoid that. Run the following command to disable that functionality:

  ```
  $ stn.uart_sleep enable=False
  ```

  :::caution
  If there are any power related pending syncs on the [Cloud](https://www.autopi.io/software-platform/cloud-management) to the device you're working with the
  settings we just changed might be reverted back to the default. We recommend that you synchronize
  all changes to your device prior to following this guide. Once the obd_manager is disabled though,
  no settings related to the STN can be changed by the [Cloud](https://www.autopi.io/software-platform/cloud-management).
  :::

  You can confirm if this setting was applied correctly by running the following command and looking
  for the uart_sleep value. It should say `OFF, 900 s`.

  ```
  $ stn.power_config

  # example response
  _stamp: '2022-02-08T10:09:04.694796'
  _type: stslcs
  ctrl_mode: NATIVE
  ext_input: LOW = SLEEP
  ext_sleep: ON,  LOW FOR 3000 ms
  ext_wake: ON,  HIGH FOR 500 ms
  pwr_ctrl: LOW PWR = LOW
  uart_sleep: OFF, 900 s
  uart_wake: OFF, 0-30000 us
  vchg_wake: ON,  +2.00V IN 1000 ms
  vl_sleep: ON,  <12.20V FOR 240 s
  vl_wake: ON,  >15.50V FOR 3 s
  ```

2. **Disable obd_manager**  
  Next, the obd_manager needs to be disabled. You can do that by going over to Device > Services
  and selecting the obd_manager entry. The page that opens up should include a tab called
  "Settings" - click on it. On the panel that opens up, there should be a checkbox that's called
  Enabled - uncheck that box. You don't need to synchronize the changes yet, as we will be
  making another change in the next step.

3. **Enable Bluetooth**  
  Finally, you need to enable Bluetooth on the device. You can do that by going over to Device >
  Advanced Settings > Bluetooth and changing the Mode field from `disable` to `miniuart`. After synchronizing
  the changes, the [Cloud](https://www.autopi.io/software-platform/cloud-management) will ask you to reboot the device. After the reboot you should be able to
  start using the Bluetooth on the [AutoPi](https://www.autopi.io). Use the `bluetoothctl` command to work with Bluetooth on
  the device.

## Direct Communication With the STN Chip

In case you still need to communicate with the STN chip after disabling the obd_manager, you can.
You need to have `socat` installed in order to successfully establish a communication. You can do
that by typing in:

```
$ sudo apt update && sudo apt install -y socat
```

You can connect to the STN chip with the following command. Feel free to tweak the device parameters
to your own liking:

```
$ sudo socat /dev/serial0,echo=0 -
```

Let's take a look at some example commands:
```
STSLU off, off     # disables the uart_sleep functionality
ATZ                # needed in order to apply the above command's settings
STSLCS             # use this command to double check if the UART SLEEP value is off
```

If you need to execute other commands, you will need to consult the
[STN chip specification](https://www.obdsol.com/solutions/chips/stn2100/).

---

## Enabling an External UART

---

## Overview

A UART (Universal Asynchronous Receiver/Transmitter) is the simplest and most widely supported way to move serial data between two devices. On an AutoPi TMU CM4 you already have one UART occupied by the automotive interface, but many real‑world projects—GPS receivers, CAN bridges, industrial sensors or even another microcontroller—need a *second* serial interface.

> **Goal** – Re‑purpose the built‑in **UART 2** of the CM4 and break it out on the HAT so your add‑on hardware can talk to the AutoPi at 300 baud or 4 Mbit/s and everything in between.

By the end of this page you will have:

* **Wired** the right pins
* **Edited** the Raspberry Pi firmware so it exposes `/dev/ttyAMA1`, and
* **Verified** data can flow both ways with a quick loop‑back test.

## When should I use an external UART?

| Scenario                                                                           | Why a second UART helps                                                                     |
| :----------------------------------------------------------------------------------: | :-------------------------------------------------------------------------------------------: |
| Adding a GNSS (GPS) module                                                         | NMEA sentences at 9600 or 115200 baud stream continuously—best handled on a dedicated port. |
| Talking to an OBD‑II dongle while keeping the main AutoPi vehicular interface free | Avoids contention and keeps logs clean.                                                     |
| Bridging to RS‑232/RS‑485 industrial sensors                                       | A 3‑wire TX/RX/GND connection keeps wiring simple.                                          |
| Debugging another microcontroller’s boot output                                    | Power up your MCU and capture console logs without a USB serial dongle.                     |

## Quick facts

* **Signal names** – `TXD2` transmits *from* the Pi, `RXD2` receives *into* the Pi.
* **Pin numbers** – Physical pins 27 & 28 on the 40‑pin header map to GPIO 0 & 1 (ID_SD and ID_SC on the HAT).
* **Logic level** – 3.3 V; never connect directly to 5 V RS‑232 without level shifting.

---

## Prerequisites

2. **SSH access** or Physical HDMI/USB console.
3. Micro‑jumper wires or a breakout header to reach pins 27/28.
4. A multimeter (optional but handy for continuity checks).

---

## Why GPIO 0/1?

The CM4 has six UART blocks but only **GPIO 0 & 1** expose the pins for **UART 2 (alt‑function 4)**. Your other free pins—`GPIO22‑24, 27`—can do many clever things (SPI, PCM, PWM) but *not* TX/RX. Hence we use the HAT‑EEPROM I²C pins (`ID_SD`, `ID_SC`) for serial use.

:::tip EEPROM probe vs. UART
Normally the Pi firmware tugs `GPIO0/1` low during the first 200 ms of boot while it looks for a HAT EEPROM. The `force_eeprom_read=0` flag in the next section disables that so your external device sees a clean idle‑high line from power‑up.
:::

---

## 1  Hardware wiring

| HAT label   | BCM GPIO | UART2 signal           | Connect to                |
| :-----------: | :--------: | :----------------------:| :-------------------------: |
| **ID\_SD**  | 0        | **TXD2** (Pi → device) | RX of the external device |
| **ID\_SC**  | 1        | **RXD2** (device → Pi) | TX of the external device |
| I2C1\_SDA\* | 2        | CTS2 (optional)        | RTS of the device         |
| I2C1\_SCL\* | 3        | RTS2 (optional)        | CTS of the device         |
| **GND**     | —        | —                      | Common ground             |

*Wire CTS/RTS only if you need hardware flow control and intend to enable it in the `dtoverlay`.*

```
       AutoPi TMU CM4       External Device
      ┌──────────────┐     ┌────────────┐
 ID_SD│27   TXD2  ➔──┼────►│ RX         │
 ID_SC│28   RXD2  ◄──┼─────│ TX         │
 SDA  │ 3   CTS2  ◄──┼─────│ RTS  (opt) │
 SCL  │ 5   RTS2  ➔──┼────►│ CTS  (opt) │
  GND │ 6   GND   ───┼─────│ GND        │
      └──────────────┘     └────────────┘
```

:::caution Level shifting
If the external device works at 5 V **TTL** or ±12 V **RS‑232**, you *must* level‑shift or use a proper line driver (e.g.
MAX3232, SN65HVD230 for RS‑485). Direct 5 V into a CM4 pin can permanently damage the SoC.
:::

---

## 2  Enable UART2 in `config.txt`

Open the file with `sudo nano /boot/config.txt` and add:

```ini
# === External UART2 on GPIO0/1 ===
force_eeprom_read=0          # skip HAT‑EEPROM probe on GPIO0/1
dtoverlay=uart2              # TX=GPIO0, RX=GPIO1  => /dev/ttyAMA1
#dtoverlay=uart2,ctsrts      # remove # to enable flow control on GPIO2/3
enable_uart=1                # leave as‑is if already present
```

Save, exit, and `sudo reboot`.

**Check dmesg** after the reboot:

```bash
dmesg | grep -i ttyAMA1
```

You should see a line similar to `ttyAMA1 at MMIO 0x.....` confirming the driver is active.

---

## 3  Verify with a loop‑back test

1. Jumper `GPIO0` to `GPIO1` directly on the HAT.
2. Open a terminal on the Pi and run:

   ```bash
   stty -F /dev/ttyAMA1 115200 raw -echo
   echo "hello" > /dev/ttyAMA1 &
   cat < /dev/ttyAMA1
   ```
3. The word `hello` should appear. Press *Ctrl‑C*, remove the jumper, and connect your real device.

### Alternative: use **`minicom`**

```bash
sudo apt install -y minicom
minicom -b 115200 -D /dev/ttyAMA1
```

Minicom gives you scroll‑back, line‑ending control and macros—handy for debugging.

---

## 4  Using the port in Python

```python
import serial

ser = serial.Serial(
    port='/dev/ttyAMA1',
    baudrate=115200,
    bytesize=serial.EIGHTBITS,
    parity=serial.PARITY_NONE,
    stopbits=serial.STOPBITS_ONE,
    timeout=1
)

ser.write(b'AT\r')      # send a modem‑style command
print(ser.readline())   # read back a line
ser.close()
```

Python’s `pyserial` package makes scripting trivial—ideal for quick sensor polls.

---

## 5  Troubleshooting

| Symptom                                       | Likely cause & fix                                                                                                                                   |
| :---------------------------------------------: | :----------------------------------------------------------------------------------------------------------------------------------------------------: |
| **No `/dev/ttyAMA1`**                         | Overlay typo or missing `enable_uart=1`. Re‑check `/boot/config.txt`.                                                                                |
| **Boot hang with garbage on console**         | Another service (e.g. `serial‑getty@ttyAMA1.service`) grabbed the port. Disable it with `sudo systemctl disable --now serial-getty@ttyAMA1.service`. |
| **Lines held low for \~0.2 s after power‑up** | `force_eeprom_read=0` missing; firmware still probing EEPROM.                                                                                        |
| **Flow‑control ignored**                      | Verify you removed `#` in `dtoverlay=uart2,ctsrts` *and* wired GPIO2/3 correctly.                                                                    |
| **Overruns at >1 Mbit/s**                     | Increase `init_uart_clock` in `config.txt` or use DMA mode via `dwc_uart_fifo_enable=1`.                                                             |

---

## 6  Advanced topics

### Disable I²C on GPIO0/1 entirely

If another overlay or user‑space application tries to re‑enable I²C0, add `dtparam=i2c_vc=off` to `config.txt`.

### Throughput tuning

Use `core_freq_min=250` to keep the UART clock stable during idle throttling, and prefer 8N1 framing for max payload density.

---

## 7  References

* [Raspberry Pi CM4 Datasheet – Alternate‑function table](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf#page=23)
* [Understanding Device Tree Overlays](https://www.raspberrypi.com/documentation/computers/config_txt.html#device-tree-overlays)
* [AutoPi TMU CM4 HAT Pinout](/hardware/autopi_tmu_cm4/using-hat/)

---

## Custom Event for Your Custom Logger

---

This guide walks you through creating a custom event for your own logger script. This is useful when you want your AutoPi device to react to specific conditions like determining when a trip has started or ended based on your own parameters.

We'll go step-by-step through:
* Creating a custom execution script
* Hooking it into the OBD Manager
* Enabling it on a CAN logger

## Step 1: Create a Custom Execution Script
Start by creating a new custom module. In this example, we’ll call it `custom_event`.
* Navigate to Devices and click on the device you want this change to be applied to. 
* Click on Custom Code tab and click "Create". 
![Custom Code tab](/img/guides/custom_event/custom_event.png)

Here’s what the script looks like:
![Custom Code creation](/img/guides/custom_event/create_custom_code.png)

Here is the code example: 

```python
import logging
  
log = logging.getLogger(__name__)
  
def trigger(res):
    if not isinstance(res, dict):
        return 
    for logger_output in res['values']:
        if logger_output['_type'] == "pack_sum_voltage":
            trigger_val = None
            if logger_output["value"] > 400:
                trigger_val = "nominal"
            else:
                trigger_val = "low"
  
            __salt__["minionutil.trigger_event"]("vehicle/hv_battery/voltage/{}".format(trigger_val), data=(dict({"value": logger_output['value']}, **{"_alternating_cache_event_filter.skip": True})))
            log.info("Triggered event {:}".format(trigger_val))
    return None
```

### Explanation
You have created a new function that is called trigger, and it takes one input argument res. 
* `res` is a dictionary passed from the `obd.manager`. 
* The _type attribute of the res dict is the name of the logger we want to react to. Here you can set up some conditionals for 2 different event types: 
    * Preferably, limit the event types to limit the amount of indexing elastic_search has to do.
    * The data parameter will usually be the data we react to - which is the value parameter of the logger_output we are looking at. 
* We use the alternating_cache_event_filter.skip to ensure that we limit the amount of events, if the events do no change. 

## Step 2: Add the Script as a Trigger in the OBD Manager
* Navigate to Services tab. 
* Select OBD Manager.
* Navigate to the Hooks tab.
* Click Create Hook.
* Fill in the fields:
    * Name: Choose a descriptive name (e.g., event_trigger)
    * Type: Select trigger from the dropdown
    * Function: Use the format custom_event.trigger
    * Enabled: Make sure this toggle is turned on
* Click Save.

![Create Hook event_trigger](/img/guides/custom_event/create_hook.png)

## Step 3: Assign the Trigger to a Logger
* Navigate to the Workers tab.
* Select the CAN Logger you want to apply the trigger to.
* In the logger settings, find the Trigger dropdown.
* Select your newly created trigger (e.g., event_trigger).
* If your new trigger doesn't appear immediately, try clearing any pending syncs and refreshing the page.

![Create Worker can_logger_1](/img/guides/custom_event/create_worker.png)

You now have a custom trigger configured for your custom logger. Your AutoPi device will automatically evaluate the logger output and trigger events based on your defined conditions.

---

## How to SSH to Your Device

---

There are several ways to connect to your AutoPi device. This guide explains how to access your device remotely using **SSH (Secure Shell)**. SSH allows you to open a terminal session on your AutoPi device and run commands remotely.

:::note
SSH access is **not available for AutoPi Mini devices**.
:::

## How to SSH into Your Device

You can connect to your AutoPi device using several different methods depending on your setup:

* Connect to the device's **Hotspot**.
* Connect through your **local Wi-Fi network**.
* Connect using **Tailscale**. 
* Connect using **WireGuard**.

---

## Connect to the Device's Hotspot

The simplest way to connect to your device is directly through its Wi-Fi hotspot.

### Step 1: Connect to the Hotspot

Use the following credentials:

* **SSID:** `AutoPi-XXXXXXXXXXXX` *(“AutoPi-” followed by the last 12 characters of your Unit ID)*. Unit ID is the unique ID on the side of your device. Alternatively, you can find your Unit ID by navigating to Devices > Select your device > Overview: Device specifications: Unit ID.

* **Password:** the **first 13 characters of your Device ID**, including dashes. You can find your Device ID either by navigating to Devices > Select your device > Overview: Device specifications; or in the documentation attached to your shipping email. 

Additionally, you can access hotspot information directly from the AutoPi Cloud. To do this, navigate to Devices > Select Your Device > Advanced Settings > Wi-Fi. Here, you will find the Wi-Fi hotspot's password and SSID credentials.

![Hotspot Advanced Settings](/img/guides/ssh_access/wifi_hotspot.png)

:::note
You can change the hotspot SSID and password in **Advanced Settings → WiFi** in the AutoPi Cloud.
:::

### Step 2: Connect via SSH

Once connected to the hotspot, open your SSH client and connect using the following details:

- **Host:** `local.autopi.io`  
- **User:** `pi`  
- **Password:**
  - for devices with **board versions earlier than 7.0** the password: `autopi2018` .
  - for devices with **board version 7.0 and newer** the password: First 13 characters of the Device ID (including dash).

Example:
```python
ssh pi@local.autopi.io
```

---

## Connect Through Your Home Wi-Fi
If your AutoPi device is connected to your local Wi-Fi network, you can also access it through SSH.
By default, SSH access through Wi-Fi is disabled for security reasons, especially when using public networks.

### Enable SSH on Wi-Fi:
* Open AutoPi Cloud.
* Navigate to Device → Advanced Settings.
* Go to WiFi → Client.
* Enable Allow SSH.
* Once enabled, connect using the IP address assigned by your router.

![Wifi Client](/img/guides/ssh_access/advanced_wifi_client.png)

Example:
```python
ssh pi@192.168.1.50
```

---

## Connect Using Tailscale
You can also use Tailscale for secure remote access to your AutoPi device from anywhere. If you want to read about the whole setup, check out this guide: [How to connect to Tailscale on your Autopi device](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/)

### Setup Steps:
* Open Advanced Settings on your device.
* Navigate to Tailscale.
* Enable Tailscale and provide your Auth Key.
* For a full setup guide, refer to the [Tailscale documentation](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/#2-create-a-tailnet). 
* Once configured, connect using the device’s Tailscale IP address.

![Tailscale Advanced Settings](/img/guides/ssh_access/advanced_tailscale.png)

Example:
```python
ssh pi@tailscale_IP
```

---

## Connect Using WireGuard
If you operate your own VPN server, you can connect to the device using WireGuard. You can read more about specific settings here: [Wireguard settings](https://docs.autopi.io/cloud/device_management/advanced_settings/autopi_tmu_cm4/cloud-config-wireguard/)

### Setup Steps:
* Navigate to Device → Advanced Settings.
* Open the WireGuard configuration.
* Enable:
  * Allow SSH.
  * Enable WireGuard.
* After enabling these settings, configure the Interface and Peer parameters according to your WireGuard setup.

![Wireguard Advanced Settings](/img/guides/ssh_access/advanced_wireguard.png)

---

## Transfer Files Using SCP
If you are using an AutoPi CAN-FD Pro device, you can also transfer files from the device using SCP (Secure Copy Protocol).

Example command:
```python
scp pi@192.168.0.100:/opt/autopi/can0/log.csv ~/Downloads
```

For more details, see the guide: [Accessing files via SFTP/SCP on AutoPi](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/#option-2-connect-via-command-line-scp)

---

## Executing AutoPi Commands via SSH
Most AutoPi commands that you normally run from the Cloud Terminal can also be executed directly through SSH.
To run them from the SSH terminal, prepend the command with `autopi`.

Example of `power.status` command:
```python
autopi power.status
```

If you want to learn more about different commands you can use, check out this part of AutoPi documentation: [Commands](https://docs.autopi.io/core/commands/).

Running commands through SSH can be useful for:
* Local development.
* Troubleshooting devices.
* Adjusting configurations directly on the device.

---

## Enabling Bluetooth on AutoPi

---

## Introduction
[AutoPi](https://www.autopi.io) Core relies on BluePy and Bluez packages built into the Linux core on the device. 

:::note
If you are using an older AutoPi device with an STN/ELM chip, follow the [legacy Bluetooth guide](./enabling_bluetooth_on_TMU_devices.md). This guide is intended for newer devices such as AutoPi TMU CM4 and AutoPi CAN-FD Pro.
:::

## Prerequisites
- AutoPi [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) or AutoPi [CAN-FD Pro](https://www.autopi.io/hardware/autopi-canfd-pro) device

## Installation and Setup

1. Enable bluetooth from Advanced settings:
![Enable bluetoth](/img/guides/advanced_settings_bluetooth.png)

## Using the Built-in Bluetooth Extention

It is possible to use the [bluetooth.scan](/core/commands/core-commands-bluetooth/#bluetoothscan) command to remote scanning for bluetooth device using the built in [Cloud](https://www.autopi.io/software-platform/cloud-management) terminal.

## Custom Software for Basic bluepy Usage
A great example of using the [AutoPi](https://www.autopi.io) edge devices full functionality, is teh usage of [creating custom services](/cloud/device_management/services/create-custom-services/). Using this extendabilty of the devices you utilize the full functionality of the bluepy library on the device.   

### Scanning for Devices - Custom Code Example

```python
from bluepy.btle import Scanner, DefaultDelegate

class ScanDelegate(DefaultDelegate):
    def __init__(self):
        DefaultDelegate.__init__(self)

    def handleDiscovery(self, dev, isNewDev, isNewData):
        if isNewDev:
            print(f"Discovered device {dev.addr}")
        elif isNewData:
            print(f"Received new data from {dev.addr}")

# Initialize scanner object
scanner = Scanner().withDelegate(ScanDelegate())

# Scan for devices (timeout in seconds)
devices = scanner.scan(10.0)

# Print discovered devices
for dev in devices:
    print(f"Device {dev.addr} ({dev.addrType}), RSSI={dev.rssi} dB")
    for (adtype, desc, value) in dev.getScanData():
        print(f"  {desc}: {value}")
```

```python
from bluepy.btle import Scanner, DefaultDelegate

class ScanDelegate(DefaultDelegate):
    def __init__(self):
        DefaultDelegate.__init__(self)

    def handleDiscovery(self, dev, isNewDev, isNewData):
        if isNewDev:
            print("Discovered device {}".format(dev.addr))
        elif isNewData:
            print("Received new data from {}".format(dev.addr))

# Initialize scanner object
scanner = Scanner().withDelegate(ScanDelegate())

# Scan for devices (timeout in seconds)
devices = scanner.scan(10.0)

# Print discovered devices
for dev in devices:
    print("Device {} ({}), RSSI={} dB".format(dev.addr, dev.addrType, dev.rssi))
    for (adtype, desc, value) in dev.getScanData():
        print("  {}: {}".format(desc, value))
```

### Connecting to a Device - Custom Code Example

```python
from bluepy.btle import Peripheral, UUID
import time

try:
    # Connect to device
    device = Peripheral("XX:XX:XX:XX:XX:XX")  # Replace with your device's address
    
    # Get all services
    services = device.getServices()
    
    for service in services:
        print(f"Service UUID: {service.uuid}")
        
        # Get characteristics for this service
        characteristics = service.getCharacteristics()
        
        for char in characteristics:
            print(f"  Characteristic UUID: {char.uuid}")
            # Check if readable
            if char.supportsRead():
                print(f"    Value: {char.read()}")
                
except Exception as e:
    print(f"Error: {str(e)}")
finally:
    device.disconnect()
```

```python
from bluepy.btle import Peripheral, UUID
import time

try:
    # Connect to device
    device = Peripheral("XX:XX:XX:XX:XX:XX")  # Replace with your device's address
    
    # Get all services
    services = device.getServices()
    
    for service in services:
        print("Service UUID: {}".format(service.uuid))
        
        # Get characteristics for this service
        characteristics = service.getCharacteristics()
        
        for char in characteristics:
            print("  Characteristic UUID: {}".format(char.uuid))
            # Check if readable
            if char.supportsRead():
                print("    Value: {}".format(char.read()))
                
except Exception as e:
    print("Error: {}".format(str(e)))
finally:
    device.disconnect()
```

### Reading and Writing Characteristics - Custom Code Example

```python
from bluepy.btle import Peripheral, UUID

class BLEDevice:
    def __init__(self, address):
        self.address = address
        self.device = None
    
    def connect(self):
        self.device = Peripheral(self.address)
        
    def read_characteristic(self, service_uuid, char_uuid):
        service = self.device.getServiceByUUID(UUID(service_uuid))
        char = service.getCharacteristics(UUID(char_uuid))[0]
        return char.read()
        
    def write_characteristic(self, service_uuid, char_uuid, data):
        service = self.device.getServiceByUUID(UUID(service_uuid))
        char = service.getCharacteristics(UUID(char_uuid))[0]
        char.write(data)
        
    def disconnect(self):
        if self.device:
            self.device.disconnect()

# Example usage
if __name__ == "__main__":
    device = BLEDevice("XX:XX:XX:XX:XX:XX")
    try:
        device.connect()
        # Example UUIDs - replace with your device's UUIDs
        service_uuid = "1800"
        char_uuid = "2a00"
        
        # Read value
        value = device.read_characteristic(service_uuid, char_uuid)
        print(f"Read value: {value}")
        
        # Write value
        device.write_characteristic(service_uuid, char_uuid, bytes([0x01]))
    finally:
        device.disconnect()
```

```python
from bluepy.btle import Peripheral, UUID

class BLEDevice:
    def __init__(self, address):
        self.address = address
        self.device = None
    
    def connect(self):
        self.device = Peripheral(self.address)
        
    def read_characteristic(self, service_uuid, char_uuid):
        service = self.device.getServiceByUUID(UUID(service_uuid))
        char = service.getCharacteristics(UUID(char_uuid))[0]
        return char.read()
        
    def write_characteristic(self, service_uuid, char_uuid, data):
        service = self.device.getServiceByUUID(UUID(service_uuid))
        char = service.getCharacteristics(UUID(char_uuid))[0]
        char.write(data)
        
    def disconnect(self):
        if self.device:
            self.device.disconnect()

# Example usage
if __name__ == "__main__":
    device = BLEDevice("XX:XX:XX:XX:XX:XX")
    try:
        device.connect()
        # Example UUIDs - replace with your device's UUIDs
        service_uuid = "1800"
        char_uuid = "2a00"
        
        # Read value
        value = device.read_characteristic(service_uuid, char_uuid)
        print("Read value: {}".format(value))
        
        # Write value
        device.write_characteristic(service_uuid, char_uuid, b"\x01")
    finally:
        device.disconnect()
```

### Handling Notifications - Custom Code Example

```python
from bluepy.btle import DefaultDelegate, Peripheral
import time

class NotifyDelegate(DefaultDelegate):
    def __init__(self):
        DefaultDelegate.__init__(self)

    def handleNotification(self, cHandle, data):
        print(f"Notification from handle {cHandle}: {data}")

class BLENotifyDevice:
    def __init__(self, address):
        self.device = Peripheral(address)
        self.device.setDelegate(NotifyDelegate())
    
    def enable_notifications(self, service_uuid, char_uuid):
        service = self.device.getServiceByUUID(UUID(service_uuid))
        char = service.getCharacteristics(UUID(char_uuid))[0]
        
        # Enable notifications by writing to the CCCD
        notify_handle = char.getHandle() + 1
        self.device.writeCharacteristic(notify_handle, b"\x01\x00")
    
    def wait_for_notifications(self, timeout=1.0):
        self.device.waitForNotifications(timeout)
    
    def disconnect(self):
        self.device.disconnect()

# Example usage
if __name__ == "__main__":
    device = BLENotifyDevice("XX:XX:XX:XX:XX:XX")
    try:
        # Enable notifications for a characteristic
        device.enable_notifications("service_uuid", "char_uuid")
        
        # Wait for notifications
        while True:
            if device.wait_for_notifications(1.0):
                continue
            print("Waiting...")
    finally:
        device.disconnect()
```

```python
from bluepy.btle import DefaultDelegate, Peripheral
import time

class NotifyDelegate(DefaultDelegate):
    def __init__(self):
        DefaultDelegate.__init__(self)

    def handleNotification(self, cHandle, data):
        print("Notification from handle {}: {}".format(cHandle, data))

class BLENotifyDevice:
    def __init__(self, address):
        self.device = Peripheral(address)
        self.device.setDelegate(NotifyDelegate())
    
    def enable_notifications(self, service_uuid, char_uuid):
        service = self.device.getServiceByUUID(UUID(service_uuid))
        char = service.getCharacteristics(UUID(char_uuid))[0]
        
        # Enable notifications by writing to the CCCD
        notify_handle = char.getHandle() + 1
        self.device.writeCharacteristic(notify_handle, b"\x01\x00")
    
    def wait_for_notifications(self, timeout=1.0):
        self.device.waitForNotifications(timeout)
    
    def disconnect(self):
        self.device.disconnect()

# Example usage
if __name__ == "__main__":
    device = BLENotifyDevice("XX:XX:XX:XX:XX:XX")
    try:
        # Enable notifications for a characteristic
        device.enable_notifications("service_uuid", "char_uuid")
        
        # Wait for notifications
        while True:
            if device.wait_for_notifications(1.0):
                continue
            print("Waiting...")
    finally:
        device.disconnect()
```

### Error Handling - Custom Code Example

```python
from bluepy.btle import Peripheral, BTLEDisconnectError, BTLEGattError

class BLEDeviceManager:
    def __init__(self, address):
        self.address = address
        self.device = None
        self.max_retries = 3
        
    def connect_with_retry(self):
        for attempt in range(self.max_retries):
            try:
                self.device = Peripheral(self.address)
                print("Connected successfully")
                return True
            except BTLEDisconnectError:
                print(f"Connection failed, attempt {attempt + 1} of {self.max_retries}")
                time.sleep(1)
        return False
    
    def safe_read_characteristic(self, service_uuid, char_uuid):
        try:
            service = self.device.getServiceByUUID(UUID(service_uuid))
            char = service.getCharacteristics(UUID(char_uuid))[0]
            return char.read()
        except BTLEGattError as e:
            print(f"GATT error: {str(e)}")
        except BTLEDisconnectError:
            print("Device disconnected")
            self.connect_with_retry()
        return None
```

```python
from bluepy.btle import Peripheral, BTLEDisconnectError, BTLEGattError

class BLEDeviceManager:
    def __init__(self, address):
        self.address = address
        self.device = None
        self.max_retries = 3
        
    def connect_with_retry(self):
        for attempt in range(self.max_retries):
            try:
                self.device = Peripheral(self.address)
                print("Connected successfully")
                return True
            except BTLEDisconnectError:
                print("Connection failed, attempt {} of {}".format(attempt + 1, self.max_retries))
                time.sleep(1)
        return False
    
    def safe_read_characteristic(self, service_uuid, char_uuid):
        try:
            service = self.device.getServiceByUUID(UUID(service_uuid))
            char = service.getCharacteristics(UUID(char_uuid))[0]
            return char.read()
        except BTLEGattError as e:
            print("GATT error: {}".format(str(e)))
        except BTLEDisconnectError:
            print("Device disconnected")
            self.connect_with_retry()
        return None
```

## Complete Application - Custom Code Example

```python
from bluepy.btle import Scanner, Peripheral, DefaultDelegate, BTLEDisconnectError
import time
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class BLEDeviceManager:
    def __init__(self, target_name):
        self.target_name = target_name
        self.device = None
        self.target_address = None
        
    def scan_for_device(self, timeout=10):
        scanner = Scanner()
        devices = scanner.scan(timeout)
        
        for dev in devices:
            for (adtype, desc, value) in dev.getScanData():
                if desc == "Complete Local Name" and value == self.target_name:
                    self.target_address = dev.addr
                    logger.info(f"Found device: {self.target_address}")
                    return True
        return False
    
    def connect(self):
        if not self.target_address:
            raise ValueError("No device address available")
            
        try:
            self.device = Peripheral(self.target_address)
            logger.info("Connected successfully")
            return True
        except BTLEDisconnectError as e:
            logger.error(f"Connection failed: {str(e)}")
            return False
            
    def discover_services(self):
        services = self.device.getServices()
        for service in services:
            logger.info(f"Service: {service.uuid}")
            chars = service.getCharacteristics()
            for char in chars:
                logger.info(f"  Characteristic: {char.uuid}")
                
    def disconnect(self):
        if self.device:
            self.device.disconnect()
            logger.info("Disconnected")

if __name__ == "__main__":
    manager = BLEDeviceManager("MyDevice")  # Replace with your device name
    
    try:
        if manager.scan_for_device():
            if manager.connect():
                manager.discover_services()
                # Add your device-specific operations here
                time.sleep(5)  # Keep connection alive for 5 seconds
    finally:
        manager.disconnect()
```

```python
from bluepy.btle import Scanner, Peripheral, DefaultDelegate, BTLEDisconnectError
import time
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

class BLEDeviceManager:
    def __init__(self, target_name):
        self.target_name = target_name
        self.device = None
        self.target_address = None
        
    def scan_for_device(self, timeout=10):
        scanner = Scanner()
        devices = scanner.scan(timeout)
        
        for dev in devices:
            for (adtype, desc, value) in dev.getScanData():
                if desc == "Complete Local Name" and value == self.target_name:
                    self.target_address = dev.addr
                    logger.info("Found device: {}".format(self.target_address))
                    return True
        return False
    
    def connect(self):
        if not self.target_address:
            raise ValueError("No device address available")
            
        try:
            self.device = Peripheral(self.target_address)
            logger.info("Connected successfully")
            return True
        except BTLEDisconnectError as e:
            logger.error("Connection failed: {}".format(str(e)))
            return False
            
    def discover_services(self):
        services = self.device.getServices()
        for service in services:
            logger.info("Service: {}".format(service.uuid))
            chars = service.getCharacteristics()
            for char in chars:
                logger.info("  Characteristic: {}".format(char.uuid))
                
    def disconnect(self):
        if self.device:
            self.device.disconnect()
            logger.info("Disconnected")

if __name__ == "__main__":
    manager = BLEDeviceManager("MyDevice")  # Replace with your device name
    
    try:
        if manager.scan_for_device():
            if manager.connect():
                manager.discover_services()
                # Add your device-specific operations here
                time.sleep(5)  # Keep connection alive for 5 seconds
    finally:
        manager.disconnect()
```

This example provides a complete application structure that you can adapt for your specific needs.

## Further Resources

1. **BluePy Documentation**
   - [GitHub Repository](https://github.com/IanHarvey/bluepy)
   - [Wiki](https://github.com/IanHarvey/bluepy/wiki)

---

## Guides Intro

Welcome to the developer guides for [AutoPi](https://www.autopi.io). This section is designed to help you build,
integrate, and troubleshoot faster with practical documentation for real-world vehicle and fleet projects.

Whether you are developing custom workflows, integrating with backend systems, or working with advanced diagnostics,
these guides provide clear, actionable steps to help you move from setup to production.

## Most Used Developer Guides
- **Advanced diagnostics (DoIP):** Use the [DoIP hat](https://shop.autopi.io/products/doip-hat-v1-3) to expand diagnostic and maintenance capabilities. Start here: [How to set up DoIP](https://docs.autopi.io/developer_guides/setting-up-doip/)
- **Remote access:** Connect directly with [SSH to your device](https://docs.autopi.io/developer_guides/how-to-ssh-to-your-device/) or use [Tailscale](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/)
- **Containerized workloads:** Run services on-device with [Setting up Docker on your device](https://docs.autopi.io/developer_guides/setting-up-docker/)
- **Development setup:** Follow the [Local development workflow](https://docs.autopi.io/developer_guides/local-development-workflow/), power safely with an [external power supply](https://docs.autopi.io/developer_guides/using-the-autopi-with-an-external-power-supply/), and use the [AutoPi Local API overview](https://docs.autopi.io/developer_guides/local-api-overview/)
- **Data routing and broker integration:** Send data to your own infrastructure with [Configuring MQTT](https://docs.autopi.io/developer_guides/configuring-mqtt/)
- **Power and wake control:** Access sleeping devices remotely with [Remotely waking up your device](https://docs.autopi.io/developer_guides/remotely-waking-up-your-device/)
- **Troubleshooting and recovery:** Collect diagnostics with [AutoPi Logs](https://docs.autopi.io/developer_guides/autopi-logs/) and recover devices with [Reflashing your device](https://docs.autopi.io/developer_guides/reflashing-your-device/)
- **Hardware extensions:** Add peripherals with [Installing a camera on your AutoPi](https://docs.autopi.io/developer_guides/installing-a-camera-on-your-autopi/) and configure BLE workflows via [How to use bluepy with AutoPi edge devices](https://docs.autopi.io/developer_guides/how-to-use-bluepy-with-autopi-edge-devices/)

## New Developer Guides
- [Accessing Raw GPS Data](https://docs.autopi.io/developer_guides/accessing-raw-gps-data/)
- [Build Grafana Dashboard](https://docs.autopi.io/developer_guides/build-grafana-dashboard/)
- [How to Create a Custom Event](https://docs.autopi.io/developer_guides/how-to-create-custom-event-for-custom-logger/)
- [Remote CAN Access](https://docs.autopi.io/developer_guides/can-bridge/)
- [RFID Integration](https://docs.autopi.io/developer_guides/rfid-integartion/)

These and other guides are intended to help you unlock the full technical potential of your AutoPi deployment.
If you have questions or feedback, contact us at support@autopi.io.

## Get Your Device Today and Get Started!

[![](/img/hardware/autopi_mini/AutoPi_Mini_5_Top_right.png) **AutoPi Mini** Build for fleet volume scaling and ease of install. CAN bus ready with support for legacy protocols. Support wide range of OEM Parameters. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-mini)

[![](/img/hardware/autopi_tmu_cm4/TMU_Floating_Topside_V1_scaled.png) **AutoPi TMU CM4** Based on Raspberry Pi Compute Module 4. Best for custom solutions requiring large computation power and expansion options. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-telematics-unit-cm4-4g-lte-edition)

[![](/img/hardware/autopi_canfd_pro/canfd_pro_trans.png) **AutoPi CAN-FD Pro** Based on Raspberry Pi Compute Module 4. Our most powerful device to date, designed for full speed automotive datalogging of dual CAN-FD channels. See price.](https://shop.autopi.io/products/autopi-can-fd-pro)

[![](/img/shared/autopi_devices_trans.png) **Comparison of all AutoPi devices** Compare our devices and find the best fit for your requirements.](https://www.autopi.io/hardware/compare/)

---

## Installing a Camera on Your AutoPi

---

This guide will explore how you can attach an external USB camera to your [AutoPi](https://www.autopi.io) device and make some use out of it.
There is one prerequisite however - you need to be able to SSH into your dongle. We already have a guide on that which you can
take a look at [here](/developer_guides/how-to-ssh-to-your-device/).

Firstly, we need to do some initial setup to get the [AutoPi](https://www.autopi.io) ready to use an external USB web camera. Let's start with the
software that we're going to use:

1. [motion](https://motion-project.github.io/motion_guide.html) - Motion is a daemon service that is responsible for communicating
with the camera. It'll setup the devices (`/dev/video*`) and get them started.

2. [motionEye](https://github.com/ccrisan/motioneye) - MotionEye is a web based frontend for motion. It provides an
easy to use interface to setup configuration for each camera and also shows what the cameras are currently seeing.

Installing both of them should be as easy as installing any other package on a debian system. We will use the `apt` command.
The next command installs motion daemon and its dependencies:

```
$ sudo apt install motion
```

Let's now prepare for the installation of motioneye - there are some dependencies that need to be installed:

```
$ sudo apt install python-dev libssl-dev libcurl4-openssl-dev libjpeg-dev libz-dev
```

Now that we've got the dependencies installed, let's install motioneye itself:

```
$ sudo pip install motioneye
```

**Note**: If pillow installation fails, you can try installing it from official repos using `apt install python-pillow`.

After successfully installing motion and motioneye we now need to prepare some directories for them to use.
The next two commands will create the motioneye configuration directory and copy the default configuration file in that directory:

```
$ sudo mkdir -p /etc/motioneye
$ sudo cp /usr/local/share/motioneye/extra/motioneye.conf.sample /etc/motioneye/motioneye.conf
```

Now, let's create the directory in which motioneye will save our video files to:

```
$ sudo mkdir -p /var/lib/motioneye
```

Finally, let's create a service file for motioneye so that the system can automatically start it up:

```
$ sudo cp /usr/local/share/motioneye/extra/motioneye.systemd-unit-local /etc/systemd/system/motioneye.service
$ sudo systemctl daemon-reload
$ sudo systemctl enable motioneye
$ sudo systemctl restart motioneye
```

At this point, the web interface should be running on the device, however you probably won't be able to access it from your computer or
mobile phone. Instead, it's only accessible from the device itself. This is because there are some firewall settings that have been
implemented on the device and we need to add a new exception. We can do that by navigating to the Device > Advanced Settings in [my.autopi.io](https://my.autopi.io).
There, one of the inner tabs called System should contain an entry called Network > Firewall. Let's add the following new entry to the list:

```
-A INPUT -s 192.168.4.0/24 -i uap0 -p tcp --dport 8765 -j ACCEPT
```

**NOTE**: 8765 is only the default port for MotionEye. If you happen to change the port number, please make sure to add the rule
with the respective new port number.

What this entry will do is allow all TCP traffic that comes from the [AutoPi](https://www.autopi.io)'s WiFi network interface through port 8765 to be accepted.
This will allow you to navigate to the following link: local.autopi.io:8765. There you'll finally be able to see the MotionEye frontend interface.

At this point, you should be able to plug in the camera to your device's micro-usb, wait a few seconds and see the video feed on your screen.
You should also be able to see the settings for the camera by clicking on the 'burger-menu' button on the top left of the website. If
you're unable to see a long list of settings, try reloging as an admin. If this still doesn't do the trick, try restarting the motion and
motioneye services using the following commands:

```
sudo systemctl restart motion motioneye
```

Now we will move on to some pointers on how to get started with certain, popular projects.

### Setting up Basic Camera Settings

Sometimes the image on the camera can be very dim or with a low resolution as a default. The general settings for the camera can be found under
the "Video Device" section. Settings such as brightness, contrast, sharpness and video resolution can be set up there. This should allow you to
fine tune your camera for the environment you're looking to use it in. There is also the ability to automatically set the brighness and exposure
of the camera. 

Furthermore, you're also able to change the default location of where the video files (recordings) are saved. The default location is
`/var/lib/motioneye/Camera1`, however you can change that by going under the "File Storage" section.

There you're also able to setup a webhook or a command to be called whenever a new file has been saved on the file system.

### Recording All the Time

Setting up a constantly recording camera is very simple. All you need to do is to go to your motioneye website
(local.autopi.io:8765 while connected to the [AutoPi](https://www.autopi.io) device hotspot) and open the settings for the camera. In the list there should be a section
called "Movies". You will need to turn on the movies section (which will enable the camera to record). In the Recording Mode field, select
"Continuous Recording" (It's of course also possible to have the recording based on motion detection). The rest of the settings can be selected
based on personal preference. 

### Motion Detection

Apart from the ability to record only when the camera detects motion, you can also do some other cool things. For example, you
can set up a mail notification or a webhook to be called whenever there is some motion. There is also the option to execute a
command on the [AutoPi](https://www.autopi.io) either when a motion is detected or when the motion ends. That is to say, after the camera has started
detecting motion, it can also execute a command when there is no more motion detected by it.

You can find those settings under the "Motion Detection" and "Motion Notification" settings. In the Motion Detection section you can
fine tune how you would like the motion to be detected, with higher or lower thresholds, for specific amount of frames and so on.
"Motion Notifications" section is where you can setup the triggers to be executed whenever a motion is detected (or after).

### Extra Fine Tuning

For the more tech-savvy or adventurous people out there, there is also some configuration options that work directly with motion.
Remember that MotionEye is actually a front-end application that communicates directly with motion. This means that all the options
that are available on MotionEye are also available on Motion, however much more detailed. For example, there are more events that can
be used with Motion than there are with MotionEye. One really good example is `on_camera_lost` which will trigger whenever a camera
can't be found or when a camera is lost during its work, which allows you to set a notification if your camera stops working.

You can look at all the configuration options available for Motion in [this](https://motion-project.github.io/motion_config.html) link.
The documentation can be a bit overwhelming at first, however the developers have set it up in a neat way where there is a list of
all the options in alphabetical order first and then a list of the same options based on category.
Afterwards, there is a long list of the description of each option.

---

## Jumpers

---

## Overview

A **jumper** is a small electrical connector used to short two header pins on a PCB. When installed, it electrically connects the pins and changes the behavior of the circuit by enabling or disabling specific hardware functions.

On AutoPi devices, the jumper is used to **override the Smart Power Manager (SPM)** and force the internal Raspberry Pi compute module to receive a constant **5 V supply**.

This configuration is primarily intended for:
* Developing firmware interacting with the SPM
* Debugging unexpected shutdowns or sleep events
* Running long development workloads
* Testing boot processes or system initialization
* Performing low-level hardware diagnostics.

Because this configuration bypasses the normal power management mechanisms, it should **only be used for development purposes**.

---

## Power Architecture Context

AutoPi devices receive power from the **vehicle battery through the OBD-II interface**. Under normal operation, power flows through the **Smart Power Manager (SPM)** before reaching the Raspberry Pi compute module.

### Normal Power Path
Vehicle Battery -> Smart Power Manager (SPM) -> 5V Regulator -> Raspberry Pi Compute Module

The **SPM** is responsible for:

* Ignition state detection
* Sleep and wake transitions
* Battery protection
* Power state management.

### Power Path with Jumper Installed

When the jumper is installed, the Smart Power Manager is bypassed:

Vehicle Battery -> 5V Regulator -> Raspberry Pi Compute Module

In this configuration, the Raspberry Pi receives **constant power**, independent of ignition state or SPM control logic.

---

## Installing the Jumper

To use a jumper, you will need to open up your AutoPi device. On the inside of the device, you'll see two boards connected to each other. One of them being the Raspberry Pi and the other - the AutoPi board. On the AutoPi board, you should be able to see two pins on one of the four corners, next to which is written 'FORCE 5V'.

To see how you can attach a jumper to your specific device view the following pages for:
* [Generation 2 devices](/hardware/legacy_devices/autopi_dongle/#jumper)
* [Generation 3 devices](/hardware/legacy_devices/autopi_dongle_gen3/#jumper)

The **FORCE 5V** jumper forces the device to maintain a constant 5 V supply to the Raspberry Pi compute module. Installing the jumper electrically bypasses the SPM power gating circuitry.

* Recommended - Use the jumper when:
    * SSH sessions are interrupted by device sleep.
    * Running long debugging sessions.
    * Developing new system services or kernel modules.
    * Investigating boot-time issues.

* Do **not** leave the jumper installed in production environments because:
    * Battery protection mechanisms are bypassed.
    * Sleep mode is disabled.
    * Vehicle battery drain may occur.

### Required Component

A standard **2.54 mm (0.1 inch) jumper cap**.

### Locating the Jumper Pins

To locate the jumper pins:

1. Open the AutoPi enclosure.
2. Inside the enclosure there are typically two stacked boards:
   * Raspberry Pi Compute Module
   * AutoPi carrier board
3. Locate the **two-pin header labeled `FORCE 5V`** on the AutoPi board. Here is an example from our AutoPi CAN-FD Pro device installed inside the IP67 casing: 
    

The exact location may vary slightly depending on device model.

### Installation Procedure

1. Power off the AutoPi device.
2. Open the device enclosure.
3. Locate the header labeled **FORCE 5V**.
4. Place the jumper cap across the two pins.
5. Reassemble the enclosure.
6. Power the AutoPi device again.

### Effects of Installing the Jumper

When the jumper is installed:
* Smart Power Manager power control is **disabled**.
* The Raspberry Pi receives **continuous power**.
* Automatic **sleep and hibernation are disabled**.
* Ignition signals no longer control the device power state. 

This mode ensures the system remains powered during development or debugging sessions.

---

## Removing the Jumper

To restore normal power management behavior:

1. Power down the AutoPi device.
2. Remove the jumper cap.
3. Close the enclosure.
4. Reconnect power.

After removal, the Smart Power Manager will again control power states.

### Side Effects

Because the SPM is bypassed, several protections and behaviors are disabled.

Potential side effects include:

* The device **will not enter sleep mode**.
* The device **may drain the vehicle battery**.
* Ignition state changes **will not affect power state**.

For this reason, the jumper should **not be used in production deployments**.

---

## Summary

| Feature | Normal Mode | Jumper Installed |
|:--------:|:-------------:|:------------------:|
| Smart Power Manager active | Yes | No |
| Sleep mode | Enabled | Disabled |
| Ignition control | Yes | No |
| Continuous power | No | Yes |
| Recommended for production | Yes | No |

The `FORCE 5V` jumper is a hardware override that disables the Smart Power Manager and supplies constant power to the Raspberry Pi compute module. This mode is useful for development and debugging but should not be used during normal device operation.

---

## AutoPi Local API Overview

---

# AutoPi Local API Overview

The AutoPi Local API provides a set of REST endpoints to interact with your local AutoPi device. The API is typically accessible on port `9000` of the device.

---

## Authentication

### `POST /auth/login/`

Returns a static token and information about the local user and device.

**Curl Example:**

```bash
curl -X POST http://<device-ip>:9000/auth/login/
```

**Response:**

```json
{
  "token": "<jwt_token>",
  "user": {
    "pk": 0,
    "username": "local user",
    "has_devices": true,
    "is_local": true,
    "devices": [
      {
        "unit_id": "<uuid>",
        "display": "Local device"
      }
    ],
    "timezone": "UTC"
  }
}
```

---

## Device Info

### `GET /`

Returns the device's unique unit ID.

**Curl Example:**

```bash
curl http://<device-ip>:9000/
```

**Response:**

```json
{
  "unit_id": "<uuid>"
}
```

---

### `GET /dongle/devices/`

Returns a list of available local devices.

**Curl Example:**

```bash
curl http://<device-ip>:9000/dongle/devices/
```

**Response:**

```json
[
  {
    "unit_id": "<uuid>",
    "display": "Local device"
  }
]
```

---

## Log File Download

### `GET /download_log/?file=<filename>`

Downloads a specified log file from the device.

**Query Parameters:**

- `file`: Name of the log file to download (e.g., `syslog`, `salt/minion`)

**Curl Example:**

```bash
curl -O http://<device-ip>:9000/download_log/?file=syslog
```

---

## Command Execution

### `POST /dongle/<unit_id>/execute/`

Executes a structured command on the device.

:::tip 
The reason that you need the unit_id is because we need to make sure that the request is actually meant for that specific device when using the endpoint from another connected device, like when using the local configuration tool.

The unit_id can be retrieved one of the following ways 
A.	Calling the root route
```
GET localhost:9000
```

B.	Reading it from the file 
```
/etc/salt/minion_id
```
:::

**Request Body:**

```json
{
  "command": "cmd.run",
  "arg": ["ls", "-l"],
  "kwarg": {}
}
```

**Curl Example:**

```bash
curl -X POST http://<device-ip>:9000/dongle/<unit_id>/execute/ \
  -H "Content-Type: application/json" \
  -d '{"command": "cmd.run", "arg": ["ls", "-l"], "kwarg": {}}'
```

**Response:**

Returns the command output as JSON.

:::tip
The above commands can also be executed in raw format using the below endpoint.
:::

---

### `POST /dongle/<unit_id>/execute_raw/`

Executes a raw command string.

**Request Body:**

```json
{
  "command": "cmd.run ls -l"
}
```

**Curl Example:**

```bash
curl -X POST http://<device-ip>:9000/dongle/<unit_id>/execute_raw/ \
  -H "Content-Type: application/json" \
  -d '{"command": "cmd.run ls -l"}'
```

**Response:**

Returns the command output as JSON.

---

### Saving and applying WiFi networks

To save WiFi credentials on the device:

**Command:**

```json
{
  "command": "grains.set",
  "arg": ["wpa_supplicant:networks", [
    { "ssid": "Network-1", "psk": "password1", "priority": 2 },
    { "ssid": "Network-2", "psk": "password2", "priority": 1 }
  ]],
  "kwarg": {
    "destructive": true,
    "force": true
  }
}
```

**Curl Example:**

```bash
curl -X POST http://<device-ip>:9000/dongle/<unit_id>/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "command": "grains.set",
    "arg": ["wpa_supplicant:networks", [
      { "ssid": "Network-1", "psk": "password1", "priority": 2 },
      { "ssid": "Network-2", "psk": "password2", "priority": 1 }
    ]],
    "kwarg": { "destructive": true, "force": true }
  }'
```

Then, to apply the changes and reconfigure the WiFi service:

**Command:**

```json
{
  "command": "state.sls",
  "arg": ["network.wlan.client.config"],
  "kwarg": {}
}
```

**Curl Example:**

```bash
curl -X POST http://<device-ip>:9000/dongle/<unit_id>/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "command": "state.sls",
    "arg": ["network.wlan.client.config"],
    "kwarg": {}
  }'
```

---

## APN Settings

### `GET /dongle/<unit_id>/settings/apn/`

Retrieves current APN settings.

**Curl Example:**

```bash
curl http://<device-ip>:9000/dongle/<unit_id>/settings/apn/
```

**Response:**

```json
{
  "apn": "internet",
  "user": "user",
  "pass": "pass",
  "pin": "0000",
  "mtu": 1280
}
```

---

### `PUT /dongle/<unit_id>/settings/apn/`

Updates the APN configuration.

**Request Body:**

```json
{
  "apn": "internet",
  "user": "user",
  "pass": "pass",
  "pin": "0000",
  "mtu": 1280
}
```

**Curl Example:**

```bash
curl -X PUT http://<device-ip>:9000/dongle/<unit_id>/settings/apn/ \
  -H "Content-Type: application/json" \
  -d '{"apn": "internet", "user": "user", "pass": "pass", "pin": "0000", "mtu": 1280}'
```

**Response:**

Returns the updated APN configuration.

Then, to apply the changes and reconfigure the QMI service:

**Command:**

```json
{
  "command": "state.sls",
  "arg": ["network.wwan.qmi.config"],
  "kwarg": {}
}
```

**Curl Example:**

```bash
curl -X POST http://<device-ip>:9000/dongle/<unit_id>/execute/ \
  -H "Content-Type: application/json" \
  -d '{
    "command": "state.sls",
    "arg": ["network.wwan.qmi.config"],
    "kwarg": {}
  }'
```

---

## Error Responses

All endpoints return structured error responses if something goes wrong.

**Example:**

```json
{
  "error": "unit_id does not match the id configured on this device"
}
```

---

---

## Local Development Workflow

---

When you build or debug modules, speed matters. A cloud-only workflow is reliable for deployment, but it is often too slow for everyday development.

Typical cloud-only loop:

1. Make changes.
2. Push/sync changes to the device.
3. Restart services.
4. Execute module.
5. Repeat.

For active development, a local workflow gives a much faster feedback loop and a better developer experience. In this guide, you will learn:

* When to use cloud vs local workflows.
* How to develop directly on the device over SSH.
* How to develop locally and sync changes to the device (recommended).
* How to choose between refreshing modules and restarting the minion.

:::note 
Recommended workflow - use the **[AutoPi Cloud](https://www.autopi.io/software-platform/cloud-management)** for fleet management, configuration, and final rollouts.
Use **local or SSH-based workflows** for rapid iteration, debugging, and testing.
:::

---

## Before you begin

Make sure you have the following:

* SSH access to the device, see: [How to SSH to Your Device](https://docs.autopi.io/developer_guides/how-to-ssh-to-your-device/).
* A local development environment (recommended).
* Basic familiarity with AutoPi modules and Salt structure.

When syncing from the Cloud, the modules will be put in the following directories, based on the type:

* `/opt/autopi/salt/modules`
* `/opt/autopi/salt/returners`
* `/opt/autopi/salt/utils`
* `/opt/autopi/salt/engines`
* `/opt/autopi/salt/states`

:::warning
Cloud sync can overwrite local edits on the device without prompting.
If you develop directly on the device, keep backups or version-control your files locally.
:::

---

## Option 1: Edit directly on the device (SSH)

This is the fastest setup for small fixes or quick validation.

You can connect to your AutoPi device in several ways, depending on your setup:

* Connect Screen and Keyboard to Device. 
* Connect to the device hotspot: [Connect to the hotspot of your AutoPi device](https://docs.autopi.io/developer_guides/how-to-ssh-to-your-device/#step-1-connect-to-the-hotspot).
* Connect through your local Wi-Fi network: [Connect through your home Wi-Fi to AutoPi device](https://docs.autopi.io/developer_guides/how-to-ssh-to-your-device/#connect-through-your-home-wi-fi).
* Connect using Tailscale: [Connect to Tailscale on your AutoPi device](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/).
* Connect using WireGuard: [Connect to WireGuard on your AutoPi device](https://docs.autopi.io/developer_guides/how-to-ssh-to-your-device/#connect-using-wireguard).

**Steps for development through SSH:**

1. SSH into the device.
2. Edit files in the relevant `/opt/autopi/salt/...` directory.
3. Reload modules or restart the minion.
4. Run your test command and validate the result.

**To apply changes after editing:**

* Faster method (may not pick up every change):
    ```python
    autopi saltutil.refresh_modules
    ```

* More reliable method during development:
    ```python
    autopi minionutil.restart
    ```

---

## Option 2: Remote development - develop locally and sync to device 

Alternatively, another workflow can be to have a script on your development machine that copies the files to the device via [scp](https://www.computerhope.com/unix/scp.htm), that way you can make the changes in your favorite editor. This usually provides the best productivity: local editor, version control, and fast deployments.

### Example deployment script

Create a small script on your development machine to copy files and restart services:

```python
#!/usr/bin/env bash
set -euo pipefail

DEVICE_HOST="pi@local.autopi.io"
LOCAL_FILE="./my_module.py"
REMOTE_FILE="/opt/autopi/salt/modules/my_module.py"

scp "$LOCAL_FILE" "$DEVICE_HOST:$REMOTE_FILE"
ssh "$DEVICE_HOST" "autopi minionutil.restart"
```

You can extend this script to sync multiple files and run a smoke test command after deployment.

### Suggested iteration loop

1. Edit code locally.
2. Run local quality checks (lint/tests where applicable).
3. Deploy with your sync script.
4. Restart the minion or refresh modules.
5. Execute and verify behavior on the device.

---

## Keep in mind 

**Choosing between refresh and restart:** 
* Use `autopi saltutil.refresh_modules` for faster reloads when changing simple module code.
* Use `autopi minionutil.restart` when behavior is inconsistent or when changing deeper dependencies.

If you are unsure, restart the minion service for a clean reload. You can also read more here: [Minionutil Commands](https://docs.autopi.io/core/commands/core-commands-minionutil/).

**Common pitfalls:**
1.  * **Issue:** Local changes disappear after cloud sync.
    * **Solution:** The cloud-synced version has replaced your device-local file. Keep local backups, use version control, and avoid editing the same files directly on the device right before a cloud sync.

2. * **Issue:** Changes do not apply immediately after editing.
    * **Solution:** Reload modules with `autopi saltutil.refresh_modules` or run `autopi minionutil.restart` for a clean reload.

3. * **Issue:** The development loop feels slow.
    * **Solution:** Reduce manual cloud sync steps during active coding. Develop locally, sync with a script, and use cloud deployment only once changes are stable.

**When to switch back to cloud deployment?**

Once development is stable: 
    1. Commit and review your code.
    2. Push via your standard cloud workflow.
    3. Validate on target devices.

For additional implementation support, see our [Development Voucher](https://shop.autopi.io/products/development-voucher).

---

## Modbus Server

---

The AutoPi device can function as a Modbus server (slave), exposing vehicle data — including OBD-II readings, Diagnostic Trouble Codes (DTCs), and other logged values — as Modbus registers. Any standard Modbus client (such as a PLC, SCADA system, or HMI) can read these registers over TCP, UDP, or serial. This enables direct integration with industrial control systems, fleet monitoring platforms, and IoT applications without additional middleware.

## Overview 
### What is Modbus?

Modbus is a widely-adopted, open-source industrial communication protocol designed for reliable supervisory control and data acquisition (SCADA). Originally developed for serial communication, Modbus has been extended to support TCP/IP networks. Key characteristics include:

- **Simplicity** — Easy to implement and integrate across diverse systems
- **Standardization** — Supported by thousands of industrial devices (PLCs, HMIs, sensors, gateways)
- **Flexibility** — Works over serial (RTU/ASCII), TCP, and UDP transports
- **Scalability** — Suitable for both small local systems and large remote deployments

When the AutoPi acts as a Modbus server, it makes vehicle data available using the standard Modbus register protocol, allowing existing industrial systems to consume real-time vehicle information.

### Redis Cache on the AutoPi

Redis is an in-memory data store used internally by the AutoPi to cache real-time vehicle data. Here's how it works:

- **Data Storage** — Loggers (OBD, GPS, CAN, etc.) continuously write their data to Redis instead of a slow database
- **Low Latency** — In-memory storage ensures sub-millisecond read/write performance, critical for real-time vehicle monitoring
- **TTL (Time-to-Live)** — Each cached value automatically expires after a configurable duration (default: 60 seconds), ensuring fresh data is always served
- **Returner Integration** — The Modbus server reads directly from Redis cache when clients request data, providing immediate responses

This architecture decouples data collection from data delivery, allowing multiple applications (like Modbus, cloud APIs, and local services) to access the same live vehicle data without conflicts.

---

## How It Works

1. Loggers (e.g. OBD) run on the device and continuously write values to an internal cache.
2. When a Modbus client requests a register, the Modbus server reads the corresponding value from that cache.
3. You define which Modbus register address maps to which data field.

No polling is required from the client side — the device keeps the cache up to date based on the configured logger intervals.

---

## Setup

### Step 1 — Enable the Modbus Server Engine

Navigate to **Device → Advanced Settings → Modbus** and enable the `modbus_server` engine.

Once enabled, the `modbus_server` will be available as a data returner for loggers. This means you can configure loggers to send their data directly to the Modbus server, where it will be stored in Redis cache.

![Modbus Advanced Settings](/img/guides/modbus/enable_modbus.png)

**Optional Advanced Settings:**

If needed, you can adjust additional parameters under the same settings:
- **Bind** — Configure the address and port for the Modbus server
- **Redis Cache** — Adjust connection timeout, database, host, and port settings
    - **TTL** — Data retention time in Redis (default: 60 seconds). This ensures clients receive current data, not stale values. 

![Extra Advanced Settings](/img/guides/modbus/extra_advanced_settings.png)

---

### Step 2 — Configure the Register Map

Navigate to **Device → Advanced Settings → Modbus → Register Map**. This is where you map Modbus register addresses to vehicle data fields from your loggers.

#### Default Registers

If no custom register map is configured, the following defaults apply:
- Register 0 → Engine RPM
- Register 1 → Vehicle speed

#### Field Reference:

| Field | Description |
|:---:|:---:|
| `register` | Modbus register address (0-based) |
| `redis_key` | Data field name from the logger |
| `default_value` | Fallback value if data is unavailable (default: `0`) |

All register values are stored as `uint16` (range: 0–65535). Floating-point values are rounded automatically.

#### Adding Custom Registers

To expose additional data, add new register mappings:

1. Click **Add New**
2. Enter the mapping using this format:

   **Generic format:**
   ```python
   {"register": <address>, "redis_key": "<data_field>", "default_value": <fallback_value>}
   ```
   
   **Example (Engine RPM):**
   ```python
   {"register": 0, "redis_key": "obd.rpm", "default_value": 0}
   ```

3. Click **Save**

> **Important:** Each register mapping can reference only one `redis_key`. Ensure the `redis_key` matches the logger's output field name exactly. Logger field names typically follow the format `obd.loggername` (e.g., `obd.rpm`, `obd.speed`). For multi-word logger names, use lowercase with no spaces. 

#### Example on AutoPi Cloud

Below is an example of a complete register map with multiple signals configured. This demonstrates how to properly set up several common vehicle data points:
![Example of Register Maps](/img/guides/modbus/modbus_advanced_settings.png)

In this example:
- Register 0 exposes engine RPM
- Register 1 exposes vehicle speed
- Register 2 exposes intake temperature
- Register 4 exposes coolant temperature ...

Each Modbus client request for a specific register will return the corresponding vehicle data value from Redis cache.

---

### Step 3 — Verify Loggers Are Running

Register values depend on active loggers. The `redis_key` in your register map must match the output field name of the corresponding logger.

Common OBD `redis_key` values:

| redis_key | Description |
|:---:|:---:|
| `obd.rpm` | Engine RPM |
| `obd.speed` | Vehicle speed |
| `obd.coolant_temp` | Coolant temperature |
| `obd.fuel_level` | Fuel level |
| `obd.throttle_pos` | Throttle position |

Logger update intervals determine how frequently register values are refreshed. To adjust the interval, navigate to **Loggers → `Logger Name`** and update the configuration for the relevant PID logger.

---

## Exposing Diagnostic Trouble Codes (DTCs)

To expose DTCs over Modbus, you must reserve a block of registers: one for the DTC count, followed by one register per DTC value.

**Setup DTCs:**

1. **Create a DTC Logger**

   * Navigate to **Device → Loggers → Create**
   * Create a new logger with these settings as shown on the picture below:
     - **Name:** `GET_DTC`
     - **Converter:** `dtc`
     - **Returner:** `modbus_server`
   * Click **Save**

    ![Create a DTC Logger](/img/guides/modbus/get_dtc_logger.png)
    

2. **Configure DTC Register Map**
   - Navigate to **Device → Advanced Settings → Modbus → Register Map**
   - Add the following mappings to expose DTC data:
     1. **DTC Count** — Insert this to track the total number of active codes:
        ```
        {"register":12,"redis_key":"obd.dtc.count","default_value":0}
        ```
     2. **DTC Code** — Insert this to expose the first DTC code:
        ```
        {"register":13,"redis_key":"obd.dtc.0","default_value":0}
        ```
   - To add additional DTC slots, increment both the register address and DTC index (e.g., `{"register":14,"redis_key":"obd.dtc.1","default_value":0}`)
   - Click **Save**
   
    ![DTC Setup](/img/guides/modbus/dtc_setup.png)

   > **Note:** In this example, the register allocation is as follows:
   > - **Registers 0–11** — Reserved for vehicle signal loggers (RPM, speed, temperature, etc.)
   > - **Registers 12–17** — Reserved for DTC data (register 12 for DTC count, registers 13–17 for up to 5 individual DTC codes).
   > 
   > Adjust these register numbers based on your actual setup. If you have more or fewer signal loggers, shift the DTC registers accordingly.

**DTC Encoding**

DTC codes are encoded as integers because Modbus does not support alphabetic characters. Use this encoding scheme:

| Category | Prefix | Example DTC | Encoded Value |
|:---:|:---:|:---:|:---:|
| Powertrain | P | P0301 | 10301 |
| Body | B | B1234 | 21234 |
| Chassis | C | C1234 | 31234 |
| Network | U | U9999 | 49999 |

- A value of `0` indicates an empty slot.

---

## Connecting a Modbus Client

Connect your Modbus client to the device's IP address on port `5020` (or whichever port you configured in Advanced Settings).

The following Modbus function codes are supported:

- **Function Code 3** — Read Holding Registers
- **Function Code 4** — Read Input Registers

Both function codes return the same register values.

#### Python Example

```python
from pymodbus.client.sync import ModbusTcpClient

# Connect to the AutoPi device
client = ModbusTcpClient("192.168.4.1", port=5020)
client.connect()

# Read registers 0 and 1 (RPM and speed)
result = client.read_holding_registers(0, 2, unit=1)
print(result.registers)  # Output: [rpm_value, speed_value]

client.close()
```

---

## Move Device to a Dedicated Environment

---

In this short guide we will talk about how you can move your device from the default production
environment to your dedicated environment provided by [AutoPi](https://www.autopi.io). Unfortunately, this process moves
only one device at a time, so you will need to repeat the steps for each device you need to move.

## 1. First We Need to Change the Host to Which the Device Connects.
How this is done depends on what version of the core you have on your device.

:::tip
Find the version currently deployed on your device by going to the "Software Updates" page.
:::

### A. For Versions **AFTER** 2021.08.05

For all versions after **2021.08.05**, you will only need to run the *change_master* command.

```bash
# First we change the master host.
$ minionutil.change_master yourcompany.autopi.io confirm=True

# Then we restart the minion
$ minionutil.restart
```

### B. For Versions **BEFORE** 2021.08.05

This version of the core also requires you to modify the `/boot/host.aliases` file to
point to your dedicated environment. Firstly, we need to change the master URL to point to your
dedicated server, in this example it is `yourcompany.autopi.io`.

```bash
$ cmd.shell 'echo "hub yourcompany.autopi.io" > "/boot/host.aliases"'
```

Next, we need to make sure that the master is specified correctly in the salt-minion configuration
file:

```bash
$ minionutil.change_master hub confirm=True
```

The above command will ensure the salt-minion configuration is set correctly and restart the
salt-minion.

## 2. Accepting the Device In the Dedicated Environment.

Lastly, we need to accept the new device's keys. You can do that by logging in to your
webpage (https://dedicated.autopi.io/#account/devices) and registering your device if it isn't
already.

Once you have it registered and you have brought the device online, accept the key under the device settings.

![Key state denied](/img/cloud/device_management/move_to_dedicated_environment/key_state_denied.png)

:::tip
When accepting the key you might receive a 404 error saying that the key for that device was not
found. If that's the case, most likely your device was unable to get connected to the environment
yet. Make sure that you have internet connection and that you have typed in the URL of your dedicated
environment correctly.
:::

When that is done, you'll need to restart the salt-minion once more, either by waiting for it to go to sleep, or by issuing the following command:

```bash
# if running the command directly on the device (e.g. SSH)
$ sudo systemctl restart salt-minion

# if running the command through a web terminal
$ minionutil.restart
```

## 3. Re-Applying Any Custom Settings.

Since you just moved the device from one environment to another, it is important that you recognize that any settings that was applied on the old environment, will not be migrated automatically unless we explicitly let you know this has been done.

This means that you must ensure that the device is using the right settings for your use case.
To make sure that the device has all the right configuration applied (They might differ between environments), you should go to the `Software Updates` page, and reapply the current version, by clicking `enqueue update`, that way you ensure that the device is fully in sync with the current environment.

You should now be able to make configuration changes, execute commands and so on.

---

## Reflashing Your Device

---

This guide explains how to reflash your AutoPi device with a fresh AutoPi OS image. Reflashing is useful for recovery and troubleshooting, but it changes low-level device software and should be performed carefully. Before you begin, confirm your device version, use the correct image, and follow each step in order to reduce the risk of configuration issues or data loss.

:::warning
Only use this guide if you are comfortable working directly with device firmware. Reflashing should not be performed on a fully operational production device unless necessary. If you are unsure about any step, contact our [Support team](mailto:support@autopi.io) before proceeding.
:::

The reflashing process varies slightly depending on your AutoPi hardware version and host operating system. The steps in this guide were verified on Pop!_OS 6.1 (Debian-based) and Windows 10.

**Reflashing Quick Start Summary:**

1. Download the AutoPi OS image.
2. Set up Balena Etcher (or an alternative tool).
3. Connect the device storage media:
    - Pre-CM4 devices (versions 3.0-6.3)
    - CM4 devices (version 7.x+)
4. Flash the image.
5. (Optional) Ensure your device is connecting to the correct environment.
6. Complete initial device setup.
7. Update your device from the Cloud.

---

## 1. Download the [AutoPi](https://www.autopi.io) OS Image

:::warning
Make sure you select **the correct image** for your device. In the AutoPi Cloud, find your board version under **Device > Overview > Device Specifications > Board Version:**
![Board Version of the Device](/img/guides/reflashing/board_version.png)
:::

After confirming your board version, download the matching image from the table below:

| Generation | Board Version | Release Page | Image Link |
|:------------:|:------------:|:-----------: | :------------------------------------------------------:|
|      2     | 3.2        | v27.05.20 | https://github.com/autopi-io/autopi-core/releases/tag/v27.05.20 |
|      2     | 3.4        | v27.05.20 | https://github.com/autopi-io/autopi-core/releases/tag/v27.05.20 |
|      2     | 3.4.1      | v27.05.20 | https://github.com/autopi-io/autopi-core/releases/tag/v27.05.20 | 
|      2     | 3.4.2      | v27.05.20 | https://github.com/autopi-io/autopi-core/releases/tag/v27.05.20 | 
|      2     | 4.0        | v27.05.20 | https://github.com/autopi-io/autopi-core/releases/tag/v27.05.20 | 
|      3     | 5.0        | v1.21 | https://github.com/autopi-io/autopi-core/releases/tag/v1.21     |
|      3     | 5.1        | v1.21 | https://github.com/autopi-io/autopi-core/releases/tag/v1.21     | 
|      3     | 5.2        | v1.21 | https://github.com/autopi-io/autopi-core/releases/tag/v1.21     |
|      3     | 6.0        | v1.21 | https://github.com/autopi-io/autopi-core/releases/tag/v1.21     |
|      3     | 6.1        | v1.22 | https://github.com/autopi-io/autopi-core/releases/tag/v1.22     | 
|      3     | 6.2        | v1.22 | https://github.com/autopi-io/autopi-core/releases/tag/v1.22     | 
|      3     | 6.3        | v1.22 | https://github.com/autopi-io/autopi-core/releases/tag/v1.22     | 
|      4     | 7.0        | v1.22.9 | https://github.com/autopi-io/autopi-core/releases/tag/v1.22.9 |
|      4     | 7.1        | v1.26.0 | https://github.com/autopi-io/autopi-core/releases/tag/v1.26.0 |
|      4     | 7.1 (CAN-FD Pro only)    | v1.28.0 | https://github.com/autopi-io/autopi-core/releases/tag/v1.28.0 |

You may also check the [autopi-core releases page](https://github.com/autopi-io/autopi-core/releases) for a newer **board-version-compatible** image.

---

## 2. Set Up Balena Etcher (or an Alternative)

We recommend [Etcher](https://etcher.io) because it can flash the compressed `.gz` image directly.
* On **Windows**, install Etcher through the standard `.exe` installer.
* On **Linux**, follow the instructions in [Balena's Etcher repository](https://github.com/balena-io/etcher?d_id=fae0960a-c0ca-432e-af94-7e81c00d32a9&s_id=1677580787961#debian-and-ubuntu-based-package-repository-gnulinux-x86x64). If the first command fails, run `sudo apt update` and try again.
    > **Note for Linux users** - on Linux, this guide uses the Balena package repository and a package manager install, but an `.AppImage` is also available on [Balena's website](https://www.balena.io/). 

---

## 3. Connect the Device Storage Media

AutoPi devices come in two types based on board version, each with a different storage setup. Follow the subsection that matches your device's board version (determined in Step 1):

* **Pre-CM4 devices** (Board Versions 3.0-6.3): use an internal SD card.
* **CM4 devices** (Board Version 7.x+): use onboard eMMC flash storage.

### 3.a. Pre-CM4 Devices (Board Versions 3.0-6.3)

Pre-CM4 devices use an internal SD card with AutoPi Core preinstalled.

1. Open the device enclosure and remove the SD card.
2. If needed, follow [Upgrade/Replace Your Raspberry Pi Computer](/developer_guides/upgrading_your_raspberrypi.mdx) for disassembly guidance.
3. Insert the SD card into an SD card reader and connect it to your computer.
4. Navigate to next step: 4. Flash the device. 

### 3.b. TMU CM4 Devices (Board Version 7.x+)

CM4 devices do not use an SD card. The operating system is stored on onboard eMMC flash, so setup differs from pre-CM4 devices.

> Note: altough possible to do on a Windows machine, it's highly recommended to use Linux instead, as the utility for accessing the Raspberry Pi's flash memory s easier to set up and is more stable on Linux.

You must:

1. Set up `rpiboot` on your host computer using Windows or Linux.
2. Put the device into **EMMC FLASHING** state.
3. Connect the device to your computer over micro-USB.

#### Step 1: Set Up rpiboot

`rpiboot` is a Raspberry Pi utility that enables read/write access to the CM4 flash chip. Most of this setup is one-time per host computer.

**Set Up `rpiboot` on Windows**

* Download the [rpiboot installer](https://github.com/raspberrypi/usbboot/raw/master/win32/rpiboot_setup.exe) 
* Complete the installation. 
* Then run `rpiboot` from the Start menu.

> Note: For more details, see the complete guide: [Raspberry Pi Windows installer documentation](https://www.raspberrypi.com/documentation/computers/compute-module.html#windows-installer). When that documentation refers to jumper cables, on AutoPi hardware this corresponds to changing device state using the side button.

**Set up `rpiboot` on Linux**

* Follow the setup steps in the [Raspberry Pi usbboot documentation](https://github.com/raspberrypi/usbboot). 
* Once `rpiboot` is running, your computer will start waiting for a connected CM4 device.
    ![rpiboot setup](/img/getting_started/developer_guides/reflashing_your_device/rpiboot_setup.png)

#### Step 2: Put the Device Into EMMC FLASHING State

The device must be powered on from a vehicle or external power supply with adapter cable. Do not use the micro-USB port for power. 

> Note: For button location and full state transition details, see [AutoPi TMU CM4 LED and button behavior](https://docs.autopi.io/hardware/autopi_tmu_cm4/led-and-button/).

Quick sequence:

1. If the device was just powered on, wait for the blue LED to become solid.
2. Short-press the side button (located in one of the holes on the side of the device) to initiate a gentle shutdown.
3. Wait until the LED becomes dim (hibernation).
4. Long-press once to enter **USER SETUP** (slow blink, about 1 blink/second).
5. Long-press again to enter **EMMC FLASHING** (rapid blink).

#### Step 3: Connect the Device With a Micro-USB Cable

:::warning
Do not use the rear USB Type-A ports for flashing.
:::

With `rpiboot` running and the device in **EMMC FLASHING** state:

1. Connect the micro-USB end to the side micro-USB port on the device.
2. Connect the other end to your computer.
3. Wait for `rpiboot` to detect the device and expose partitions (if present).

At this point, you can access the internal file system through mounted drives. On Windows, at least one partition should appear in File Explorer. On Linux, typical mount points are `/media/<user>/boot` and `/media/<user>/rootfs`: 

![device detected output](/img/getting_started/developer_guides/reflashing_your_device/device_detected.png)

---

## 4. Flash the Device

**Flashing steps**

In Balena Etcher (or your preferred tool):
    * Select the image downloaded in Step 1.
    * Select the correct target storage device.
    * Start flashing and wait for completion.
    ![balena configured with image and device](/img/getting_started/developer_guides/reflashing_your_device/configured_balena.png)

If flashing **fails** on the first attempt, retry once before troubleshooting further.

:::warning
Do not remove power while the device is running or booting. The safest time to disconnect power is immediately after unmounting storage.
:::

**After flashing**

* Unmount the storage device.
* For pre-CM4 devices: remove the SD card from the reader and reinstall it in the device.
* For [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) devices: disconnect the USB cable, press the button to return to hibernation, then short-press to boot.

---

## 5. Optional: Ensure Your Device is Connecting to the Correct Environment

    > Complete this step only if your company uses a dedicated AutoPi environment.

If your portal URL is not `my.autopi.io` (for example, `my_company.autopi.io`), follow [Move to a Dedicated Environment](/developer_guides/move-to-dedicated-environment).

---

## 6. Set Up the Device

After reflashing, complete device connectivity and key acceptance in [AutoPi Cloud](https://my.autopi.io/#/login).

### 6.1. Bring the Device Online and Configure APN

1. Power on the device and confirm internet connectivity. See **Verify Connectivity** in [Getting Started Guide](https://docs.autopi.io/getting_started/autopi_tmu_cm4/#8-verify-connectivity).
2. If you use an AutoPi-provided SIM, configure APN:
   * Follow **Setup APN** in [Getting Started Guide](https://docs.autopi.io/getting_started/autopi_tmu_cm4/#7-connect-to-local-administration).
   * Use APN string: `nxt20.net` (AutoPi SIM cards).
3. Sign in to [my.autopi.io](https://my.autopi.io/#/login).

### 6.2. Accept the Device Key

The device's encryption key requires acceptance in Cloud before it can authenticate.

**Finding the Key Status:**

1. Open the device page. The Key Status widget shows the current state:
   ![Key Status unaccepted](/img/guides/reflashing/device_with_unaccepted_key.png)

**Accepting the Key:**

1. Click **Edit device** (top-right corner).
2. Locate the **Key state** field. It will display **Your key is not accepted**:
   ![Key State Not Accepted](/img/guides/reflashing/accept_keystate.png)
3. Click **Accept**.
4. Click **Save** to apply the change.

**Verification:**

The Key state will update to accepted and device overview now shows:

![Key State Accepted](/img/guides/reflashing/device_with_accepted_key.png)

### 6.3. Configure Wi-Fi Hotspot

When the device comes online for the first time, the Wi-Fi hotspot is configured as:
* **SSID**: AutoPi-Initial  
* **Password**: autopi2018

:::tip
For security reasons, change the hotspot password immediately:
**Devices > [your device] > Advanced settings > WIFI > Hotspot**
:::

---

## 7. Finalize by Updating the Device

After reflashing, update the device from AutoPi Cloud > [Software Updates](https://docs.autopi.io/cloud/device_management/software-updates/) page. This ensures all configuration values are reapplied (including Wi-Fi settings) and that the correct authentication token is in place for data upload.

To confirm the update completed successfully:

1. Open **Software Updates** in AutoPi Cloud.
2. Open your latest release attempt.
3. Verify that a **success** result is shown for that attempt, as in the example below:
    ![Software update release attempt status](/img/guides/reflashing/software_updates.png)

For more information, see also: [How to update your device](https://docs.autopi.io/cloud/device_management/software-updates/).

:::note
If the update initially fails after reflashing, let the device run for a few minutes. The device will retry the update automatically, and it can succeed after a short stabilization period.
:::

---

## CAN Bridge Over the Internet

---

This guide explains how to create a **CAN bridge over the Internet** using AutoPi devices. It shows how **two AutoPi Pro devices** can be used to securely bridge a vehicle CAN bus to **any third-party CAN based diagnostic tool**, regardless of physical location.

> **Note:** Make sure to contact our sales team at sales@autopi.io in order to have this new add-on "Remote CAN" enabled for your account.

A practical example of a remote CAN access setup is demonstrated in our YouTube video: [AutoPi CAN Bridge over the Internet](https://www.youtube.com/watch?v=8bIkRO_IYas).

<iframe width="560" height="315" src="https://www.youtube.com/embed/8bIkRO_IYas?si=3xu2AqqVqQUzovQJ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>

---

## Overview

A CAN bridge over the Internet allows engineers and technicians to access a vehicle’s CAN bus remotely while still using their preferred local diagnostic or test tools. Instead of connecting directly to the vehicle, CAN traffic is transparently bridged between two AutoPi Pro devices over a secure Internet connection.

This approach is especially useful for:

* Remote diagnostics and troubleshooting.
* Development and testing with third-party CAN or OBD-II tools.
* Supporting vehicles in the field without on-site access.
* Working with mixed vehicle fleets and platforms.

---

## What Is a CAN Bridge Over the Internet?

A CAN bridge over the Internet is a setup where CAN frames from a vehicle are forwarded in real time to a remote location, where they appear exactly as if the diagnostic tool were physically connected to the vehicle.

Traditionally, CAN or OBD-II diagnostics require:

* A physical connection to the vehicle.
* Local presence of a technician and test equipment.

With AutoPi, CAN traffic can instead be:

* Read directly from the vehicle CAN bus.
* Transmitted securely over the Internet.
* Exposed locally to a third-party CAN or OBD-II tool.

This makes it possible to perform diagnostics, analysis, and testing remotely, without changing existing workflows or tools.

---

## Using AutoPi CAN-FD Pro for CAN Bridging

AutoPi CAN-FD Pro devices combine native CAN access with cloud connectivity, making them well suited for Internet-based CAN bridging.

The main concept is simple:

* One AutoPi Pro connects to the vehicle acting as CAN master. 
* A second AutoPi Pro connects to the technician’s tools acting as CAN slave. 
* CAN traffic is bridged transparently between them. 

### Example Use Case: Secure CAN Bridge Over the Internet

Two **AutoPi Pro** devices are used to create a secure CAN bridge:

* **ON SIDE - AutoPi CAN-FD Pro as remote CAN master:**
    * Installed in the vehicle. 
    * Connected to the vehicle CAN bus.
    * Reads/writes CAN data in real time.

    ![Example of CAN master](/img/guides/remote_can_access/can_master_advanced_settings.png)

* **REMOTE SIDE - AutoPi CAN-FD Pro as remote CAN slave:**
    * Located with the technician. 
    * Connected to any third-party CAN based diagnostic tool.
    * Transmits/receives CAN frames from the vehicle and presents them locally as if directly connected to the vehicle. 

    ![Example of CAN slave](/img/guides/remote_can_access/can_slave_advanced_settings.png)

This setup allows technicians to use **standard third-party tools** such as OBD-II scan tools, CAN analyzers, diagnostic software, or custom test equipment without being physically near the vehicle.

---

## Supported Vehicles and Protocols

While some CAN solutions focus only on passenger vehicles using OBD-II, AutoPi supports a much wider range of platforms. Thanks to AutoPi hardware and adapter options, a CAN bridge over the Internet can be used with:
* Passenger vehicles using **OBD-II**. 
* Commercial and **heavy-duty vehicles**.
* **J1939 based trucks and machinery**. 
* Other **CAN-based vehicle** and equipment platforms. 

This flexibility makes AutoPi suitable for mixed fleets, industrial applications, and advanced automotive development scenarios.

---

## Requirements

Before setting up a CAN bridge over the Internet, ensure you have:
* Two AutoPi CAN-FD Pro devices available on our [Webshop](https://shop.autopi.io/products/autopi-can-fd-pro). 
* Internet connectivity for both AutoPi devices, we recommend using WiFi connection. 
* Access to the AutoPi Cloud. 
* A third-party CAN based diagnostic tool. 

![Example Setup of the remote CAN access](/img/guides/remote_can_access/setup_for_remote_can_access.png)

---

## Device Configuration for CAN Bridging

To enable CAN bridging, both AutoPi CAN-FD Pro devices must be configured through the **AutoPi Cloud**.

> **Note:** Exact configuration options depend on your use case and vehicle platform. The steps below describe the general approach. However, contact our support team for more information at support@autopi.io.

### Configuration via AutoPi Cloud

Using AutoPi Cloud, you can:

* Enable and configure the CAN channels on each device.
* Set CAN bus parameters such as bitrate and interface selection.
* Define secure communication between the two AutoPi Pro devices.
* Control how CAN frames are forwarded or logged.
* Manage authentication and access permissions.

These settings allow you to fully control how CAN traffic is bridged, logged, or exposed to external tools.

---

## Example CAN Bridge Setup and Demonstration

A practical example of a CAN bridge over the Internet is demonstrated in our YouTube video: [AutoPi CAN Bridge over the Internet](https://www.youtube.com/watch?v=8bIkRO_IYas). 

In the video, you can see:

* An AutoPi Pro connected to a vehicle and reading CAN data.
* CAN frames being transmitted securely over the Internet. 
* A remote AutoPi Pro exposing the CAN bus to local diagnostic tools. 
* Live vehicle data being read in real time.

The key takeaway is that **CAN data can be accessed in real time from anywhere**, while still using familiar third-party tools fully remotely.

---

## Summary

A CAN bridge over the Internet with AutoPi devices enables secure, real-time access to vehicle CAN buses from anywhere in the world. By using two AutoPi Pro devices, you can:

* Bridge a vehicle CAN bus to a remote location.
* Use any third-party CAN based diagnostic tool.
* Support multiple vehicle types and CAN protocols, including J1939.
* Eliminate the need for physical access to vehicles.

This makes AutoPi a powerful solution for engineers, technicians, and fleet operators working with modern CAN-based systems.

---

## Next Steps

* Watch the full YouTube demonstration to see the CAN bridge in action: [AutoPi CAN Bridge over the Internet](https://www.youtube.com/watch?v=8bIkRO_IYas)
* Explore AutoPi Cloud configuration options for CAN bridging. 
* Adapt the setup for diagnostics, development, or fleet support use cases.

---

## Remotely Waking up Your Device

---

When a vehicle is parked and the ignition is turned off, the AutoPi device will automatically go to sleep to reduce power consumption and protect the vehicle battery. If you are working on a project remotely and need to access your AutoPi device while the vehicle is off, it is possible to wake the device from sleep remotely.

## Overview
AutoPi devices enter sleep mode when the ignition is off. While asleep, the device is offline and consumes minimal power. For many development, diagnostics, or fleet use cases, however, it can be necessary to regain access without physically interacting with the vehicle. AutoPi supports SMS-based wake-up, allowing the device to be woken remotely by sending a text message to the SIM card installed in the device. You can find all the information under Device > Overview > AutoPi SIM. 

## Waking Up the Device via SMS
To wake up an AutoPi device from sleep:
* Send a TEXT/SMS to the phone number associated with the SIM card installed in the AutoPi device.

Upon receiving the SMS, the device will wake up and reconnect. No specific message content is required—the arrival of the SMS itself triggers the wake-up.

### Reading SMS Messages on the Device
Depending on the hardware version of your AutoPi device, SMS messages can be listed or read directly from the device.

* **Pre-CM4 Devices using ecx2 module (AutoPi Dongle, AutoPi Dongle Gen3, AutoPi Socket CAN)** - SMS messages can be listed using the `ec2x` module. 

    Run the following command from the terminal:
    ```python
    ec2x.list_sms
    ```

    This can be useful when using prepaid SIM plans or when checking message status. However, you can also browse other commands here: [Ec2X Manager](https://docs.autopi.io/core/services/core-services-ec2x-manager/). 

* **CM4 Devices (AutoPi CAN-FD Pro, AutoPi TMU CM4)** - SMS messages can be read using the `modem` module:
    ```python
    modem.read_sms
    ```

    You can also browse other commands here: [Modem](https://docs.autopi.io/core/commands/core-commands-modem/).
---

## Troubleshooting SMS Wake-Up Issues
If your AutoPi device does not respond to an SMS wake-up, check the following:
1. Modem Power Save Mode

    The modem can be configured to enter a **Power save** mode during sleep. When this mode is enabled, SMS wake-up is not possible. Check the setting in AutoPi Cloud:
        * Go to Device → Advanced Settings → Power → Modem.
        * You can also adjust other settings under Advanced Settings → Power; such as sleep timers or wake trigger.

    ![Power Save Modem](/img/guides/advanced_settings_modem.png)

2. SIM Card SMS Storage Limit

    Modems and SIM cards have a limit on how many unread SMS messages they can store. If the storage is full, new SMS messages (including wake-up messages) may not be received. You can clear stored messages using the following commands: 
    * Pre-CM4 devices: 
    ```python
    ec2x.query 'AT+CMGD=1,4'
    ```

    * CM4 devices: 
    ```python
    modem.connection execute AT+CMGD=1,4
    ```

:::warning
Remotely waking up the device is not possible if the device is in hibernation (deep sleep). Hibernation occurs when the vehicle battery voltage drops below 12.2 V. This is a precautionary safety measure to ensure that AutoPi will never drain the vehicle battery.
:::

:::note
For **AutoPi Mini devices**, remote wake-up via SMS or terminal commands is not supported.
These devices cannot be woken from sleep remotely and require ignition or physical interaction to become active again.
:::

---

SMS based wake-up allows you to regain access to your AutoPi device remotely while the vehicle is parked and ignition is off. This is especially useful for development, diagnostics, and fleet operations.

Key points:
* Wake-up is triggered by sending an SMS to the device SIM.
* Commands differ between pre-CM4 and CM4 devices. 
* Modem power-saving settings can disable SMS wake-up.
* Deep sleep (hibernation) cannot be overridden remotely.
* AutoPi Mini devices do not support remote wake-up.

---

## RFID Reader Integration

---

This guide explains how to integrate a USB RFID reader with your [AutoPi](https://www.autopi.io) device and configure RFID-based access tracking in [AutoPi Cloud](https://my.autopi.io).

With this setup, drivers or operators scan an RFID card or chip before using a vehicle. AutoPi Cloud then records the authentication attempt in Access Control and System Events, giving you clear visibility into who used which vehicle, when, and for how long.

Typical benefits include:
- Better vehicle accountability.
- Easier investigation by linking incidents to specific drivers or operators.
- More accurate tracking of working hours based on scan history.

:::tip
Connect the RFID reader over USB and use a model that behaves as a keyboard input device (HID). Other reader types may work, but HID readers are the officially verified option.
:::

---

## Quickstart

Follow these steps for a fast setup:

1. Enable RFID in Device > Advanced Settings > RFID.
2. Add the reader Vendor ID and Product ID.
3. (Optional) Configure the `rfid_manager` service.
4. (Optional) Configure a worker and reactor.
5. Assign RFID tokens to users.
6. Assign drivers to vehicles.
7. Scan cards and monitor Access Control and Events.

---

## Step 1: Enable RFID in Advanced Settings

![Advanced Settings for RFID](/img/guides/rfid_reader/advanced_settings_rfid.png)

1. Open your device in [AutoPi Cloud](https://my.autopi.io).
2. Go to Device > Advanced Settings > RFID.
3. Configure the fields below and save.

### Advanced Settings Field Reference

- **Authorized token regexes**: a list of regex patterns used to match RFID tokens. Example: `*`
- **Authorized tokens**: a list of RFID authentication tokens in `timestamp,duration,rfid` format. Example: `2021-11-23T09:50:00,7200,0011252203`
- **Enabled**: turns RFID functionality on or off. When enabled, `rfid_manager` becomes available in Services.
- **Keep login context**: if enabled, RFID tokens used for login are saved and the device tracks login status.
- **Reader Vendor Product Id**: the `vendor_id:product_id` identifier of your RFID reader.

:::note
If RFID does not appear in Advanced Settings, contact [support@autopi.io](mailto:support@autopi.io). The feature can be enabled for your account at no additional cost.
:::

---

## Step 2: Find Vendor ID and Product ID

1. Connect the RFID reader to the device over USB and power on the device.
2. Run the command below:

```python
usbutil.devices
```

3. Find your RFID reader in the output and note the vendor and product values.
4. Enter the values in Advanced Settings as vendor_id:product_id (for example, 2c7c:0125).
5. Save settings. The device will synchronize settings and restart.

---

## Step 3: Configure the RFID Manager Service (Optional)

The core service for RFID handling is rfid_manager. It becomes available under Services after RFID is enabled in Advanced Settings.

![RFID_manager in Services](/img/guides/rfid_reader/rfid_manager_services.png)

You can extend this service with workers, reactors, hooks, and custom settings. For full command coverage, see [RFID Manager documentation](https://docs.autopi.io/core/services/core-services-rfid-manager/).

---

## Step 4: Worker and Reactor Configuration (Optional)

The worker and reactor are enabled by default when you activate RFID in Advanced Settings. In most cases, you do not need to perform any additional configuration.

However, if the worker and reactor are not present, or if you want to customize them to fit your use case, follow the instructions below.

### Create Worker

![Create Worker for RFID Reader](/img/guides/rfid_reader/rfid_reader_worker.png)

1. Go to Device > Services > `rfid_manager`.
2. Open the Workers tab and select Create.
3. Configure the worker with these values:
   - Name: rfid_reader
   - Interval: 0
   - Loop: -1
   - Handler: reader
   - Trigger: rfid_read
4. Save.

### Create Reactor

![Create Reactor for RFID Reader](/img/guides/rfid_reader/rfid_reader_reactor.png)

1. In `rfid_manager`, open the Reactors tab and select Create.
2. Configure the reactor with these values:
   - Name: `authenticate_rfid`
   - Regex: `^system/rfid/(?P<rfid>[0-9]*)/read$`
   - Description: Authenticate RFID chip/card
   - Handler: `authenticate_rfid`
   - Args:
      ```json
      [
        "$match.group('rfid')"
      ]
      ```

3. Save.

:::tip
You can edit both the worker and reactor at any time to adjust them for your specific use case or requirements.
:::

---

## Step 5: Assign RFID Tokens to Users

Each user can have one or more RFID tokens.

1. Go to Users.
2. Open a user profile.
3. Scroll to RFID Tokens.
4. Add one or more tokens and save.

Only administrators with `account_administrator` permission can assign tokens.

You can also create users without email addresses. These users cannot sign in to AutoPi Cloud, but you can still link RFID tokens and track activity.

---

## Step 6: Assign Drivers to Vehicles

Each vehicle can have multiple assigned drivers.

1. Go to Vehicles.
2. Select one or more vehicles.
3. Click on Assign drivers.
4. Choose one or more drivers.
5. Save.

> Note: the Assign drivers button appears only after at least one vehicle is selected.

To review all vehicles assigned to a specific driver, open Users > select the user and check the Assigned Vehicles tab.

---

## Access Control Overview

The Access Control page provides a complete history of RFID access attempts.

It includes:
- **User name**: who attempted access.
- **Token used**: which RFID token was scanned.
- **Timestamp**: when the attempt happened.
- **Vehicle**: which vehicle was accessed.
- **Status**: approved, rejected, or logged out.

![Access Control Table](/img/guides/rfid_reader/access_control_table.png)

You can also assign drivers to vehicles directly from this page. Also each vehicle can have multiple assigned drivers.

---

## RFID Events

Each card scan generates system events that you can review under [System Events](https://docs.autopi.io/cloud/device_management/events/cloud-events-system/#rfid-events).

Event topics:
- `system/rfid/<rfid_token>/read`: a new RFID token was read.
- `system/rfid/<rfid_token>/rejected`: a scanned token was rejected.
- `system/rfid/<rfid_token>/authenticated`: a scanned token was authenticated.

Example from the Events tab in AutoPi Cloud:

![Rfid Reader Events](/img/guides/rfid_reader/rfid_events.png)

> Tip: If you are unsure about the Token ID of the rfid card/chip, you can scan it and in the events tab, you will be able to see the ID of this card. 

---

**Next steps:**

* If your account does not include one or more RFID features shown in this guide and you would like to enable them, please contact AutoPi [support@autopi.io](mailto:support@autopi.io).
* If you need assistance selecting a compatible RFID reader, contact AutoPi support for recommendations on tested and supported RFID hardware.
* You can create custom triggers based on RFID events. For example, when a token is rejected, AutoPi can automatically trigger actions such as sending an email notification, logging the event, activating an alert, or notifying a fleet administrator. This allows you to immediately detect and respond to unauthorized access attempts. Read more about custom triggers in this guide: [Custom Triggers](https://docs.autopi.io/cloud/device_management/a-guide-to-triggers/). 
* Use the AutoPi template feature to save RFID-related configurations and quickly apply them to new devices across your fleet. This simplifies deployment and ensures consistent configuration management. Read more in this guide: [Templates](https://docs.autopi.io/cloud/device_management/templates/). 

**Benefits of Using RFID Readers with AutoPi Devices**

Integrating RFID readers with AutoPi devices enables a wide range of security, fleet management, and operational use cases, including:

* Driver identification — ensure that only authorized drivers can start or operate a vehicle.
* Access control — prevent unauthorized vehicle usage by requiring valid RFID authentication.
* Fleet accountability — track which driver used a specific vehicle and when.
* Theft prevention — receive immediate alerts if unauthorized RFID tokens are used or access attempts are rejected.
* Equipment and Asset tracking — use RFID tags to identify trailers, tools, or attached equipment.
* Simplified Fleet deployment — apply RFID configurations through templates for faster rollout across multiple vehicles.

RFID integration provides an additional layer of security and automation while improving visibility and operational control across your vehicle fleet.

---

## Setting Up Docker on Your Device

---

:::tip New to Docker on AutoPi?
For an introduction to what Docker support is, why to use it, and example use cases, see [**Docker on AutoPi**](https://docs.autopi.io/cloud/docker-on-autopi/) before following this setup guide.
:::

## Overview

This guide explains how to set up Docker on your AutoPi device and deploy containers through the AutoPi Cloud. It also covers registries, projects, releases, optional features, runtime configuration, and troubleshooting.

AutoPi devices support running Docker containers directly on the unit. This enables you to deploy applications such as:
* AI/ML services  
* Custom scripts or backend services  
* Data processing pipelines  
* Communication bridges or MQTT processors  

The deployment flow works like this:

1. Build and store your container in a **Docker registry**.
2. Group your container builds in an AutoPi **project**.
3. Create a **release** that defines how the container should run.
4. Deploy the release to your AutoPi **device**.

---
## Understanding Registries, Projects, and Releases

:::note
The CRUD endpoints all return “201 Created” or “200 OK” when an entity is created or modified, and the body of the response will contain the created or modified entity. The DELETE method will return “204 No content” on success.
:::

### Docker Registries
A registry should be created to allow the device to authenticate against a custom docker registry. The model contains the url and credentials for the custom docker registry. When added, devices will automatically log in to the registry if not already logged in, on startup, and thereby be ready to pull images.

#### Create Docker Registries
1. Using AutoPi Cloud 
* When creating a registry in the **AutoPi Cloud**, you can configure:
  * Authentication (if needed)
  * Registry type
  * Additional metadata
  * Optional features supported by the image

  ![Create Docker Registry](/img/guides/docker/create_registry.png)

2. Using **API endpoint**
* You can also create a registry by using this API endpoint: [Docker_registries_create](https://api.autopi.io/?_gl=1*yvyxyh*_ga*MTY3MDAyMDE4Mi4xNzQ5MTEwNDIx*_ga_DB2BZPKYN9*czE3NjQwODMwNDgkbzIzMSRnMSR0MTc2NDA4MzA0OSRqNTkkbDAkaDA.#/docker/docker_registries_create)

  ```
  POST /docker/registries/
  ```

:::note
If the image should be pulled through a custom registry, the registry needs to be referenced when creating the container.
:::

---

###  Projects
A **project** groups all releases of your application, think of it as your application's home inside AutoPi. The project endpoint is a wrapper for releases, so to create any releases you must first create a project.

A project can contain:
- Development releases  
- Production releases  
- Multiple container versions  

#### Create Projects
1. Using AutoPi Cloud
* When creating a project in the **AutoPi Cloud**, you can configure:
  * Name
  * Description
  * Registry
  * Selection of Devices 

  ![Create Docker Project](/img/guides/docker/create_project.png)

  :::note
  When including your AutoPi devices, make sure you have the Docker enabled in the advanced settings.
  :::

2. Using **API endpoint** 
* You can also create a project by using our API endpoint: [Project_create](https://api.autopi.io/?_gl=1*1225mqr*_ga*MTY3MDAyMDE4Mi4xNzQ5MTEwNDIx*_ga_DB2BZPKYN9*czE3NjQwODMwNDgkbzIzMSRnMSR0MTc2NDA4MzA0OSRqNTkkbDAkaDA.#/docker/docker_projects_create)

  ```
  POST /docker/projects/
  ```

---

### Releases
A release represents a specific version of your container deployment. The release endpoint is used to create new releases, and contains a list of containers each with metadata and runtime properties for that specific container.

A release defines:
- The image name and tag  
- Startup parameters  
- Networking mode  
- Restart behavior  
- Environment variables  

Every time you push a new Docker image, you can create a new release pointing to that version.

#### Create Releases

1. Using AutoPi Cloud
* When creating a release in the **AutoPi Cloud**, you can configure:
  * Version
  * Device selection
  * Containers - Name, Tag, Image, Registry, Startup parameters, Purge data

![Create Docker Release](/img/guides/docker/docker_create_new_release.png)

2. Using **API endpoint** 
* You can also create a registry by using our API endpoint: [Release_create](https://api.autopi.io/?_gl=1*vll328*_ga*MTY3MDAyMDE4Mi4xNzQ5MTEwNDIx*_ga_DB2BZPKYN9*czE3NjQwODMwNDgkbzIzMSRnMSR0MTc2NDA4MzA0OSRqNTkkbDAkaDA.#/docker/docker_projects_releases_create)

  ```
  POST /docker/projects/{project_pk}/releases/
  ```

### Applying release 
After a release is created, each device associated to the release will receive the release information, and the release will be applied the next time the device is about to go to sleep, as the device in that situation is considered to be idle. Logging in to registries, removing images, pulling new images, starting containers etc.

The release can also **be triggered** by executing the following command via the execute endpoint on the devices you want to deploy to.
```
state.sls docker.release
```

---

### Optional Features (Advanced)

Some Docker images include additional features for performance or hardware acceleration, such as:

- GPU acceleration  
- CPU instruction optimizations  
- Debug builds  
- Extra Python packages  

You can configure these when setting up the registry or release, depending on the image.

Reference example: [Tensorflow example](https://hub.docker.com/r/tensorflow/tensorflow#optional-features)

---

### Container Runtime Configuration

AutoPi allows customizing the container at runtime, including:

- Environment variables
- Network mode (`host`, `bridge`, etc.)
- Restart policy
- Privileges
- Volumes

For example configurations, see: [Tensorflow example](https://hub.docker.com/r/tensorflow/tensorflow#running-containers)

---

## Deploying a Docker Container to Your AutoPi Device

:::note
Before you start implementing a Docker container on your AutoPi device, make sure the following requirements are completed:

1. **Docker add-on is enabled**  
   Docker support is an optional add-on that needs to be enabled for your Customer's account. 
   Contact our sales team at **sales@autopi.io** to enable this functionality on your account.

2. **Docker is enabled in advanced settings**  
   In the AutoPi Cloud, navigate to: Advanced Settings → Docker. Ensure that **Docker is enabled** for the device you want to use.
:::

### 1. Build and Push Your Docker Image

```
docker build -t my-registry/my-image:latest 
docker login my-registry
docker push my-registry/my-image:latest
```

### 2. Create a Release in AutoPi Cloud

Steps to create a new release: 
* Navigate to **Docker** page and create or select an already existing Project; this will navigate you to a new page called Releases. 

![Releases Page](/img/guides/docker/releases_page.png)

* In order to add a new release, click on "Create" button. 
* Choose  the version and select devices. 
* Enter container settings:
  * Image name + tag
  * Include the image 
  * Optionally fill out the rest of the parameters. 
* Press "Save". 

### 3. Deploy to Devices

Select which devices the release should be deployed to.
AutoPi will:
* Pull the image
* Start the container
* Auto-restart it based on your policy

#### Example Release Payload
This is an example release payload:
```python
    {
      "version": "1.0.0",
      "devices": [
        "device_id"
      ],
      "containers": [
        {
          "name": "hello_word",
          "image": "hello-world",
          "tag": "latest",
          "required_tags": [],
          "startup_parameters": {
            "privileged": false,
            "environment": [],
            "network_mode": "host",
            "restart_policy": "always"
          },
          "purge_data": false,
          "fully_qualified_name": "test-arm_hello-1.0.7"
        }
      ],
      "remove_containers": [
        "hello_world"
      ]
    }

```

**Special Fields**
| **Name** | **Required** | **Description** |
|:-----:|--------|--------|
|remove_containers	| No	| Explicitly names the containers which should be handled as ‘initial containers’. On release it will attempt to stop each container, run deployment, and if successful the containers will be removed, or on failure, they will be restarted. |
|version_hash	|Readonly	|Alternative autogenerated field (readonly) only used for referencing a release by a generated version.|
|successful_deployments |	Readonly	|Will include only devices which has successfully deployed the release.|

---
## Troubleshooting

### Container fails to start
1. Check container logs in Device → Logs. 
2. Ensure the image and tag exist in your registry. 
3. Verify networking mode does not conflict with other services. 

### Image Cannot Be Pulled
1. Ensure the device can access the registry. 
2. Confirm the image is public or authentication is configured.
3. Check for typos in image/tag names. 

### Container Keeps Restarting
1. Review application logs inside the container. 
2. Confirm environment variables are set correctly.
3. Temporarily set `restart_policy` to `on-failure` when debugging.

### Permission Issues
1. Only use privileged: true if absolutely required.
2. Verify required volume mount paths.
3. Some applications may need root permissions—verify documentation.

### Networking Problems
1. Use `network_mode`: `host` if interacting with: CAN, GPS or other hardware interfaces.
2. Ensure no port conflicts with existing services.

---

**You are all set!**

With Docker support on the AutoPi device, you can deploy powerful and flexible applications at the edge. Using registries, projects, and releases ensures a clean and maintainable deployment workflow.

---

## Setting up DoIP

---

:::caution Before proceeding with the install
The DoIP solution described here only works with the [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4).

When installed, the Ethernet port on the AutoPi device will internally be used for DoIP. Do not connect anything to the Ethernet port. 

Never install the upgraded device in a vehicle that does not support DoIP. Using an Ethernet based protocol in a vehicle that only supports CAN can affect the performance of the vehicle.   
:::

## Introduction
DoIP is a modern protocol used in the automotive industry for diagnostics and communication between vehicle components and external diagnostic equipment. This technology plays a crucial role in diagnosing and maintaining vehicles, ensuring they operate efficiently and safely.
As vehicles become more connected and complex, the need for advanced diagnostic capabilities increases. DoIP provides a robust framework that allows for faster, more reliable data transmission compared to older protocols. 

## Contents
This guide covers configuring Diagnostics over IP on the AutoPi [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4/) or [CAN-FD Pro](https://www.autopi.io/hardware/autopi-canfd-pro/) devices. Paired with the AutoPi [DoIP HAT](https://shop.autopi.io/products/doip-hat-v1-3), these devices can be upgraded to support DoIP. See this guide on how to install the [`DoIP HAT`](/hardware/accessories/doip-install/). It's also possible to order the device pre-installed with the DoIP Solution. 

## Ethernet pin assignment of the OBD-II connector
After installing the DoIP HAT your AutoPi device is capeable of communication over an Ethernet based protocol instead of a CAN based protocol. This is a protocol used in some newer vehicles. The standard pinout then changes in the 16 pin OBD-II connector.   

After the upgrade, four pins are used for Ethernet communication and one pin is used for DoIP activation. Two different DoIP pinout configurations are supported by the AutoPi HAT. Only the Ethernet Rx lines change places between the two configurations.

### DoIP main pinout

  

| **OBD pinout**         | **DoIP usage** |
|------------------------|------------|
| Pin 3  | Ethernet Rx (+)    |
| Pin 11 | Ethernet Rx (-)    |
| Pin 12 | Ethernet Tx (+)    |
| Pin 13 | Ethernet Tx (-)    |
| Pin 8  | DoIP Activation    |

### DoIP alternative pinout

  

| **OBD pinout**         | **DoIP usage** |
|------------------------|------------|
| Pin 1  | Ethernet Rx (+)    |
| Pin 9 | Ethernet Rx (-)    |
| Pin 12 | Ethernet Tx (+)    |
| Pin 13 | Ethernet Tx (-)    |
| Pin 8  | DoIP Activation    |

### Controlling the DoIP port
Through the AutoPi Core software, it is possible to control the pinout configuration to be used.

## Using the DoIP software

The AutoPi DoIP integration is based on the [udsoncan library](https://github.com/autopi-io/py-udsoncan). The integration implements all the services and helper classes from the [library](https://udsoncan.readthedocs.io/en/latest/) and thereby also support UDS (Unified Diagnostic Services).

### Enable DoIP on your AutoPi device

Before you are able to fully use the DoIP software you need to set up some settings on your AutoPi device. 

Steps to get into advanced settings for DoIP:
* Go to the Devices section in the menu.
* Select the device you want to work with.
* Click on Advanced settings.
* Click on Doip. 

![DoIP Advanced settings](/img/guides/doip_settings.png)

If you want to enable DoIP on your Autopi device you will need to configure these fields: 
* **Default Pin Setup** - this setting changes the setup of the pins. You can read more about [DoIP main pinout](https://docs.autopi.io/developer_guides/setting-up-doip/#doip-main-pinout) and [DoIP alternative pinout](https://docs.autopi.io/developer_guides/setting-up-doip/#doip-alternative-pinout) in this guide above. By default this setting is set to main pinout as that one is used more frequently. 
* **Enabled** - this setting allow you to enable the DOIP UDS service. By default it is disabled but if you want to start using DoIP, enable it here. 
* **Host** - specify the hostname or IP of the TCP endpoint of the vehicle to connect to.
* **No Gateway** - do not use the "eth0" interface as a default gateway.
* **Port** - specify the port number of the TCP endpoint. The default value is set to `13400`. You can however change this if the port number is different for your endpoint. 
* **Timeout** - timeout of the TCP connection. The default value is set to `0.1` and should be changed only if you experience problems with connection timeouts. 

### DoIP activation 

:::note
This activation needs to be set up every time the device boots up.
:::

After you have finished setting up the Advanced Settings for your device, you will need to run a command to set the DoIP activation pin high. This will signal to the car that the DoIP connection should be made active.

The DoIP HAT works in conjunction with specific software components on the AutoPi device:​
* `doip_manager`: A background service managed through the AutoPi Cloud that handles DoIP communication.​
* `doip`: A command module that allow users to manage the DoIP connection and perform diagnostics using UDS.​

#### Steps to activate the DoIP interface:
1. Activate the DoIP interface by running the command: `doip.interface activate`
2. Connect the DoIP endpoint of the vehicle by running the command: `doip.interface connect`
3. Get more information about available UDS commands by running: `doip.uds help`
4. Once you have found the UDS command you want to use, you can run the additional help command to receive more information, for example: `doip.uds help change_session`
5. Finally you can run an UDS command like this: `doip.uds change_session 1`

You can read about more commands in our [DoIP commands guide](https://docs.autopi.io/core/commands/core-commands-doip/).
For DoIP manager service commands, see [Core services: DoIP manager](https://docs.autopi.io/core/services/core-services-doip-manager/).

---

## Setting Up a Device with Verizon Wireless

---

We have had serveral different users report issues with setting up the 4G Dongle on Verizon Wireless.

The issue is that Verizon requires an IMEI number to register the SIM. And while the [AutoPi](https://www.autopi.io) does have an IMEI, this is just not recognized by Verizon’s system and the setup fails.

This is a verified method of setting it up:

1. If you have a brand-new SIM you must use another device (Tablet or smartphone) to register the SIM with Verizon. Use the IMEI from that device.
2. If you have a SIM that is already registered on Verizon’s network, you can go ahead and use the SIM.
3. Follow this guide for inserting the SIM in the device: https://www.autopi.io/getting-started
4. Instead of the preselected APN settings, use this string: vzwinternet

That's it! You should now be able to use your AutoPi device with Verizon Wireless.

---

## Upgrade/Replace Your Raspberry Pi Computer

:::caution Before proceeding with the upgrade
Please read the **whole guide** in order to have a good understanding of how all the components fit together.

You need to be careful not to tear or damage some of the cables when handling the casing of the device.
:::

### Disassembling the [AutoPi](https://www.autopi.io) Device

	
		Step 1: On the bottom side of the device,
		remove the screws that hold the casing in
		place.
	
	

	
		Step 2: Open the bottom casing on the
		side, just like a book. Be careful when
		doing this as there is a cable connection
		between the modem and the casing.
	
	

	
		Step 3: Remove all three cable
		connections from the modem module. The
		cables need to be pulled up to be removed
		from their sockets. There are two black
		cables on each side and one gray cable in
		the middle. We suggest using a pair of
		pliers to help you with this.
	
	

	
		Step 4: 
		Remove both shields from the
		back and the side. They just need to be
		slid up.
	
	

	
		Note: 
		At the front of the device, there is a plastic
		OBD connector. In the next step, you will
		need to grab the OBD connector and pull
		it up from the top casing.
	
	

	
		Step 5: 
		Slowly pull up the board by the
		OBD connector. Beneath, you will find a
		speaker and a yellow battery attached to
		the top casing. You will need to remove
		the cables of those two components from
		the board. To remove the cables, simply
		pull them out of their sockets.
	
	

	
		Note: 
		Once detached from the battery and the
		speaker, your [AutoPi](https://www.autopi.io) device will look like
		this, with the modem facing upwards.
	
	

	
		Step 6: 
		Turn the board around to reveal
		the Raspberry Pi. You can also see the
		memory card from this side. Next, remove
		the plastic screws that secure the
		Raspberry. Disconnect the USB
		cable.
	
	

	
		Step 7: 
		Gently pull out the Raspberry Pi
		from the board. All the GPIO pins from
		the Raspberry Pi get connected to the
		sockets on the board. You should be able
		to get them out of their sockets by either
		pulling firmly, or wiggling left to right.
	
	

### Assembling Back the [AutoPi](https://www.autopi.io) Device

	
		Step 8: 
		Grab your new Raspberry Pi board.
	
	

	
		Step 9: 
		Plug in your new Raspberry Pi
		into the board. The memory card slot
		should be facing the OBD connector. To
		plug in, simply align the GPIO pins with
		their respective sockets and push down.
	
	

	
		Step 10: 
		Plug in the USB cable. Don’t
		forget to plug in your memory card as
		well.
	
	

	
		Step 11: 
		Turn the device around and
		prepare the casing. You will need to
		connect the battery and the speaker cables
		first.
	
	

	
		Step 12: 
		Connect both cables to the board.
		The battery has a smaller connector, while
		the speaker has a bigger connector.
	
	

	
		Note: 
		The cables need to be connected like this.
		For both, the red cable always goes on the
		outside, the black cable goes on the inside.
	
	

	
		Step 13: 
		Tuck both cables beneath the
		device and place it back into the casing
		like this. The OBD connector has a thin
		cutout along the plastic of where the
		casing needs to fit in. However, make sure
		that the black and gray cables are sticking
		out from the side, as you will need to
		connect them to the modem in the next step.
	
	

	
		Step 14: 
		Connect the antennas by placing
		them on their sockets and the firmly
		pushing down until you hear a *click*
		sound. The black cable goes on the side
		while the gray one goes in the middle. In
		addition, you will also need to slide down
		the back shield and the lateral shield.
	
	

	
		Step 15: 
		Prepare the bottom casing and
		place it in the same position as when you
		took it out. You will then need to connect
		the black cable to the last remaining
		socket on the modem. Fold down the
		casing so the device completely seals.
	
	

	
		Step 16: 
		Finally, screw back in the four
		metal screws that you took out in the
		beginning. You don’t have to worry about
		where to put them as they all have the
		same dimensions.
	
	

	
		Step 17: 
		When you replace or upgrade your Raspberry Pi, the device generates a new UNIT ID. This new ID must be updated on AutoPi’s system. Please contact our support team at support@autopi.io and provide both your new and old UNIT IDs (Unit ID is the ID sticker on the side of your device.).
	

	
		Step 18: 
		Once you receive confirmation from support that your UNIT ID has been updated, you’ll need to accept the new key in the cloud:
		1. Go to Device.
		2. Click the Settings icon (top right corner).
		3. Select: Accept Key. 
	

	
		Step 19: 
		Finally, update your device to the latest software version:
		1. Navigate to the Software Updates tab. 
		2. Click Update.
		3. Wait till your device sync all changes and double check in Software Updates tab if the state of your device shows as UPDATED.
		

		Your device should now be fully operational!

---

## Using the AutoPi With an External Power Supply

---

AutoPi devices are preconfigured for in-vehicle use. For lab or bench setups, you can safely power the device with an external power supply through the OBD connector.

![AutoPi With External Power Supply](/img/guides/ssh_access/external_power_supply.jpeg)

:::tip Recommended for testing and troubleshooting
Using an external power supply is an excellent option when validating configurations, reproducing issues, and troubleshooting behavior outside a vehicle.
:::

## Setup Checklist

1. Always power the AutoPi through the OBD connector.
   Do not use the Raspberry Pi power inputs. This can cause AutoPi features to behave incorrectly and may damage the device.

2. Use a stable power source.
   AutoPi may power down automatically when voltage drops below 12.2 V to protect the vehicle battery. For lab use, provide at least 12.5 V and use a power supply rated for at least 2.5 A.

3. Be aware of sleep timer behavior.
   If no communication is detected on the vehicle CAN bus, a sleep timer may be triggered.

## Useful Commands

You can run AutoPi Core commands either locally on the device or over SSH, read more here: [How to SSH to Your Device](https://docs.autopi.io/developer_guides/how-to-ssh-to-your-device/).

* Local terminal format: `power.status`.
* SSH format: `autopi power.status`.

The `autopi` prefix works for all AutoPi Core commands. See the [commands documentation](https://docs.autopi.io/core/commands/) for a full reference.

### Sleep Timer Commands

Sleep timers are power-management timers that can put the AutoPi into sleep mode when no expected activity (such as CAN bus communication) is detected for a period of time.

* To inspect sleep timers, run `power.sleep_timer`.
* To clear all timers, run `power.sleep_timer clear=*`.

Read more in [Power Sleep Timer Commands](https://docs.autopi.io/core/commands/core-commands-power/#powersleep_timer) and the [Sleep Timers Guide](https://docs.autopi.io/core/power_management/core-power-sleep-timers/).

## Recommended Cable

For an easier connection to an external power supply, we recommend the OBD power cable available in our shop:
[OBD-II Power Cable](https://shop.autopi.io/en/products/obd-ii-power-cable-10/).

---

## Change Device Settings from the REST API

---

In this guide we'll explore how you can change your device's advanced settings directly through our
REST API, without having to go through the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) system to do it.

This guide will assume that you are able to log in to your account and receive a JWT token that you
can authenticate with to make the requests ([here's a section for that](/getting_started/api/index.md)).

:::note
Currently, the settings endpoints used in this guide aren't documented in our API documentation
[website](https://api.autopi.io).
:::

The rest of the guide also assumes that the API URL is `https://api.autopi.io/`. All the endpoints
that are described below require you to prepend this API URL in order for them to work properly. If
you are a business customer, you will need to prepend the respective URL for your dedicated
environment.

Lastly, for the most part, the API works with the primary key of the device instead of the unit id.
Although they have the same type (`UUID`), they aren't the same. You are able to retrieve the
device IDs of all your devices by making a `GET` request to [`/dongle/devices`](https://api.autopi.io/#/dongle/dongle_devices_list)
which retrieves all the devices you own and give you information about them including the "id" and
"unit_id" values. 

Let's get started.

## The Endpoints

There are three endpoints that you're looking at for the most part:
1. Retrieve all available configuration options available for a device
2. Retrieve current settings and their state for a specific device
3. Make changes to the state of the settings for a specific device

### Retrieve All Configuration Options

One of the more important parts of this whole process will be to actually see all available options
and their specific UUIDs, as this is what's going to be used to change them later on. The API
endpoint that you need to call is `/dongle/settings/schema/?device_id={{device_id}}` where
`{{device_id}}` is the primary key of your device. A successful request to that endpoint will
return an array of JSON objects, each object containing information for one configuration that you
can change. Let's take a look at an example configuration:

```json
...
    "system.logging.level": {
        "uuid": "9ae810c7-9069-4f7c-83b5-5f88f50aba4a",
        "default": "warning",
        "desc": "The log level of the Salt Minion log. Change if you want more detailed logging.",
        "choices": [
            "quiet",
            "critical",
            "error",
            "warning",
            "info",
            "profile",
            "debug",
            "trace",
            "garbage",
            "all"
        ],
        "type": "str",
        "sls": "minion.config"
    },
...
```

Above you can see the configuration object for the `system.logging.level` setting. It has a `uuid`
which is unique, some `default` value, a `desc`ription and the data `type` of the value which will
be important later on when you actually try to change it. The `sls` field is there for metadata on
how to handle that configuration internally.

The `choices` field isn't present in all settings, as not all settings are restricted to specific
values. In this case however, it is - you can only set the logging level to a known logging level.

There is another field, a `unit` field that's present in some integer type settings to define what
unit the setting is measured in. This is useful for example to distinguish between seconds and
milliseconds.

### Get the Current State of Configuration Options

Now that we're familiar with how to see basic information for all configuration options, it's time
to actually see the values that are saved for them. You can do that by making a `GET` request to
`/dongle/settings/?device_id={{device_id}}` and, same as before, `{{device_id}}` is the primary key
of your device. A successful request will return another array of JSON objects in the following
format:

```json
...
    "9ae810c7-9069-4f7c-83b5-5f88f50aba4a": {
        "state": "SYNCED",
        "value": "info"
    },
...
```

In this case, the UUID is the one for the `system.logging.level` setting. The `state` field
describes whether the change has been applied to the device. The `value` field is the currently
saved value for that setting.

### Change Settings and Synchronize Them With Your Device

Finally, after going through this information, we're able to make a request to change a setting.
This time, we're going to make a `POST` request to `/dongle/settings/?device_id={{device_id}}` with
a JSON body. It's also important to note here that you do need to set the `Content-Type` header to
`application/json` as the server will reject the request otherwise. Here's the JSON format:

```json
{
    "{{setting_uuid_1}}": {{new_setting_value1}},
    "{{setting_uuid_2}}": {{new_setting_value2}}
}
```

Let's take a look at an actual example:

```json
{
    "9ae810c7-9069-4f7c-83b5-5f88f50aba4a": "debug"
}
```
```curl
curl -X POST "https://api.autopi.io/dongle/settings/?device_id=YOUR_DEVICE_ID" \
     -H "Authorization: APIToken YOUR_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
          "9ae810c7-9069-4f7c-83b5-5f88f50aba4a": "debug"
     }'
```

This will ask the server to update the `system.logging.level` setting to a `debug` level. If we now
query the current settings for our device we can see that the data for that setting has changed:

```json
...
    "9ae810c7-9069-4f7c-83b5-5f88f50aba4a": {
        "state": "MODIFIED",
        "value": "debug"
    },
...
```

Now the setting is set to `debug`, however it's in the `MODIFIED` state which means that it hasn't
been synced to the device yet. To actually sync the changes, you need to make another `POST` request
to `/dongle/devices/{{device_id}}/execute/` with the following request body:

```json
{
    "command": "state.sls",
    "arg": ["pending"],
    "kwarg": {}
}
```

Also remember to set the `Content-Type` header to `application/json` for this request as well. This
will trigger the server to push those changes to the device and your device should update soon.

With this you should now be able to work with the API that controls the custom settings for your
devices.

---

## Command Webhook Callbacks

---

It is possible to get notified via webhook when a command completes on a device.

### Overview

1. Execute command through the API
2. If the device does respond, a webhook request is sent with the result of the command.
3. If the device does not respond, it will eventually time out (default timeout: 120 seconds), and this will cause a timeout request to be sent to your server. 

Note that if the device responds with a command result after the timeout, it will still send the `COMMAND_EXECUTED` payload, even after the `TIMEOUT` payload has been sent.

### 1. Executing a Command With Callback
The way this works is that if you specify the `callback_url` field when sending a request to the `/dongle/devices/{id}/execute/` or `/dongle/devices/{id}/execute_raw/` endpoint, the server will send a callback to the requested url when the server receives the response from the device.

:::note
The fields that contains the command and arguments for the two endpoints are a bit different, but the callback fields is the same for both of them. 

See the difference in the autogenerated [API documentation](https://api.autopi.io/#/dongle/dongle_devices_execute_command)
:::

**Request**
```json
POST /dongle/devices/{DEVICE_ID}/execute[_raw]/
{
    "command": "{COMMAND}",
    "callback_url": "{CALLBACK_URL}",
    "callback_timeout": 1-600 // default 120 seconds
}
```

**Response**
```json
{
    "jid": "{JOB_ID}",
    "minions": [
        "{UNIT_ID}"
    ]
}
```

### 2. Getting Notified by the Webhook Request.

The request sent to your server looks like this.

```json
HEADERS
{
    'Content-Type': 'application/json',
    'X-Request-Signature': {HMAC_SIGNATURE},
}

BODY
{
    "response": {
        "tag": "salt/job/{JOB_ID}/ret/{UNIT_ID}",
        "data": {
            "fun_args": [],
            "jid": "{JOB_ID}",
            "return": true,
            "retcode": 0,
            "success": true,
            "cmd": "_return",
            "_stamp": "2022-01-01T00:00:00.000000",
            "fun": "{COMMAND}",
            "id": "{UNIT_ID}"
        }
    },
    "jid": "{JOB_ID}",
    "state": "COMMAND_EXECUTED" | "TIMEOUT",
    "success": true,
    "device_id": {DEVICE_ID}
}
```

#### Verifying the Requests Using the HMAC Signature.

The response contains a HMAC sign in the `X-Request-Signature` header that can be used to verify the integrity of the webhook request.
The response json is signed with HMAC SHA-256 using the Authorization header used for executing the command (Without the 'APIToken' or 'Bearer' part).

Example python code that verifies the request.
```python
import hmac
import hashlib

secret = "API Token or JWT token without Bearer or APIToken postfix"
webhook_signature = "xxxxxxxxxxx"

json_body = "{}"

calculated_signature = hmac.new(hmac_secret.encode('utf-8'), json_body, hashlib.sha256).hexdigest()
valid = hmac.compare_digest(calculated_signature, webhook_signature)
```

:::note
Each response always includes a unique job id, so no two request signatures are the same.
:::

### 3. Debugging: Getting Information About the Scheduled Callback

The `/dongle/devices/{DEVICE_ID}/callback/{JOB_ID}/` endpoint allows you to get the callback object from our system.

Each callback will be stored in our system for 2 days before automatically expiring.

```json
GET /dongle/devices/{DEVICE_ID}/callback/{JOB_ID}/
{
    // Contains all requests that are sent to your server, it will retry the request up to 5 times.
    "sent_requests": [
        {
            "timestamp": "2022-01-01T00:00:00.000000Z",
            "state": "COMMAND_EXECUTED",
            "success": true,
            "response_statuscode": 200
        }
    ],
    "url": "{CALLBACK_URL}",
    "timestamp": "2022-01-01T00:00:00.000000Z",
    // uuid used internally for keeping track of the timeout task.
    "timeout_task_id": "UUID",
    // Information about the command executed
    "command": {
        "returner": null,
        "command": "{COMMAND}",
        "arg": []
    },
    // The timeout valud used for the callback.
    "timeout": 60,
    "device_id": "{DEVICE_ID}"
}
```

:::note
The response will look different based on what command was executed.

If you execute a module, the response will look like the above, but if you instead trigger a state run, like if you use want to sync the pending changes to the device `state.sls pending`, then the response will include the whole result of the pending states that was executed.
:::

---

## Export Data from API

---

Our REST API offers endpoints that let you retrieve all telemetry data from your device in the format that suits you best:
1. Aggregated Data – Simplified, high-level summaries for easier analysis.
2. Raw Data – Detailed, unprocessed data for deeper insights and customization.

## 1. Aggregated Data
This data is aggregated by interval and a method (average, min, max), and is among other
things used for the charts in our frontend dashboard.

The aggregated data can be retrieved by using this endpoint:

```
GET /logbook/storage/read/
```

Additional API documentation can be find here: Logbook - storage read list

The endpoint takes the following parameters:

| Parameter | Description  |
| -------------: | :---------- |
|  device_id | ID of the device **(not the unit_id)** |
|  field | The field that the value should be retrieved from. See 'Field' below |
|  field_type | The type of the field. See 'Field' below. [float, geo_point, string, long] |
|  from_utc | From time in UTC. ISO format. "2020-01-01T00:00:00.000Z" |
|  to_utc | To time in UTC. ISO format. "2020-01-01T00:00:00.000Z" |
|  interval | This is the interval to use when aggregating. ie. data for 24 hour queried with interval set to '1h' will return 24 data points, one for each hour. Ignored when aggregation is set to 'none' |
|  aggregation | Method used when aggregating data into the specified interval. [average, min, max, none]. |
|  size | Only used when aggregation is set to 'none', and will then return non aggregated values. |

### Examples

#### How get logged altitude aggregated into 1 minute average values

```
GET /logbook/storage/read/
    ?device_id=6a6c53b5-e18e-4301-9c95-2516006bf7c6
    &field=track.pos.alt
    &field_type=float
    &aggregation=avg
    &from_utc=2020-07-06T10:03:36.352Z
    &to_utc=2020-07-06T12:18:14.050Z
    &interval=1m
```

#### How get latest value (set aggregation = none, and to_utc can be omitted.

```
GET /logbook/storage/read/
    ?device_id=6a6c53b5-e18e-4301-9c95-2516006bf7c6
    &field=track.pos.alt
    &field_type=float
    &aggregation=none
    &from_utc=2020-07-06T10:03:36.352Z
```

### Importing JSON file
As mentioned above, you can get data from our REST API, in order for you to download them, you can use this Python 3 example: 
```
import requests # remember to install this package!
import json

# Define the endpoint and parameters
url = "https://api.autopi.io/logbook/storage/read/"
params = {
    "device_id": "6a6c53b5-e18e-4301-9c95-2516006bf7c6",
    "field": "track.pos.alt",
    "field_type": "float",
    "aggregation": "avg",
    "from_utc": "2020-07-06T10:03:36.352Z",
    "to_utc": "2020-07-06T12:18:14.050Z",
    "interval": "1m"
}

# Define the headers with the Authorization token
headers = {
    "Authorization": "Bearer YOUR_TOKEN_HERE"  # Replace with your actual token
}

# Make the GET request
response = requests.get(url, headers=headers, params=params)

# Check if the request was successful
if response.status_code == 200:
    # Parse the JSON response
    data = response.json()

    # Save the JSON data to a file
    with open("response_data.json", "w") as json_file:
        json.dump(data, json_file, indent=4)

    print("Data successfully saved to response_data.json")
else:
    print(f"Failed to retrieve data: {response.status_code}")
```

## 2. Raw Data
The raw data is not aggregated or treated in any way, it is in the same format as it was when it was sent by the device. Remember to keep the time frame of your search narrowed to be sure you'll get data back.

The aggregated data can be retrieved by using this endpoint:
```
GET /logbook/storage/raw/
```
Additional API documentation can be find here: Logbook - storage raw list

The endpoint takes the following parameters:
| Parameter       | Description  |
| -------------: | :---------- |
|  device_id | ID of the device **(not the unit id)** |
|  data_type | Optional. The datatype to retrieve. Will return all datatypes if omitted. See 'Field' below. |
|  start_utc | From time in UTC. ISO format. "2020-01-01T00:00:00.000Z" |
|  end_utc | To time in UTC. ISO format. "2020-01-01T00:00:00.000Z" |
|  use_upload_time | Optional. If false (default), *start_utc* and *end_utc* will mean 'period when the data was **recorded**'. If true, *start_utc* and *end_utc* will mean 'period when the data was **uploaded**'. |

### Example 
How get logged position objects raw

```
GET logbook/storage/raw/
    ?device_id=6a6c53b5-e18e-4301-9c95-2516006bf7c6
    &data_type=track.pos
    &start_utc=2020-11-24T10:13:21.276594Z
    &end_utc=2020-11-24T11:07:07.177850Z
```

### Importing JSON file
As mentioned above, you can get data from our REST API, in order for you to download them, you can use this Python 3 example: 
```
import requests # remember to install this package!
import json

# Define the endpoint and parameters
url = "https://api.autopi.io/logbook/storage/raw/"
params = {
    "device_id": "6a6c53b5-e18e-4301-9c95-2516006bf7c6",
    "data_type": "track.pos",
    "start_utc": "2020-11-24T10:13:21.276594Z",
    "end_utc": "2020-11-24T11:07:07.177850Z"
}

# Define the headers with the Authorization token
headers = {
    "Authorization": "Bearer YOUR_TOKEN_HERE"  # Replace with your actual token
}

# Make the GET request
response = requests.get(url, headers=headers, params=params)

# Check if the request was successful
if response.status_code == 200:
    # Parse the JSON response
    data = response.json()

    # Save the JSON data to a file
    with open("raw_data.json", "w") as json_file:
        json.dump(data, json_file, indent=4)

    print("Data successfully saved to raw_data.json")
else:
    print(f"Failed to retrieve data: {response.status_code}")
 ```   

## Field

To know which fields you can retrieve data from, you can get the list from the following endpoint Logbook - storage fields list

This will return all the available fields that can be queried, including the type of the field.
The data type can be derived from the fields, like so:

| Field | Datatype |
| :---- | :------- |
| obd.speed.value | obd.speed |
| obd.bat.level | obd.bat |

etc.

**This is the list of data types currently available from a standard device:**

| Datatype       | 
| :------------- |
| acc.xyz |
| ec2x.data_usage |
| obd.ambiant_air_temp |
| obd.bat |
| obd.coolant_temp |
| obd.engine_load |
| obd.fuel_level |
| obd.intake_temp |
| obd.rpm |
| obd.speed |
| rpi.temp |
| track.pos |

---

## Getting Started

---

You are able to use the [AutoPi REST API](https://api.autopi.io) with your browser, which will display our
auto-generated documentation portal.

![api_frontpage](/img/getting_started/api/api_intro/api_frontpage.jpg) 

## Authentication
If you want to test the endpoints, you can authenticate in the API documentation portal by setting the token to use
when authenticating. In the picture above you can see there is a green 'Authorize' button which you need to press.
This is where you'll be pasting your token.

It is possible to authenticate using two different tokens or sending the request manually using Postman (or similar).

### 1. API Tokens

Authentication should be done with the API tokens. These tokens can be generated in the account page. The expire date is optional. The tokens can then be used in external systems to authenticate the requests. To use the token, you simply set the Authorization header to the following value, when sending HTTP requests to the API:

```
Authorization: APIToken YOUR_TOKEN
```

#### Creation of the API Token

You can **generate the new API Token** in the AutoPi [Cloud](https://my.autopi.io). Clicking on the in the *Account tab* in the side menu gets you to the *Account Page*.

On the *Account* Page you may see an API Tokens *tab* which gets you to the API Token creation part. 
Here you are able to create a new API Token by giving it a name and there is an *option* to set an expiration date for the token if you need and clicking the *Create* button.

![account_page](/img/getting_started/api/api_intro/account_overview.png)

### 2. JWT Token

This token is the one used by the frontend when logging in. It expires relatively shortly and you need to enter you username and password to acquire the token.

#### Receiving the JWT Token

You can get the JWT token in two different ways:

    * **Capture the Token by Using the Browser Developer Tools** - the easiest way is to capture the token by logging into the [Cloud](https://www.autopi.io/software-platform/cloud-management), with the developer tools open in your favourite
    browser, with the network tab open, and then skip to step 6 in the below step by step guide.
    * **Manually Call the Auth Endpoint to get the Token.** - you can follow the steps below to call the login endpoint manually.

        * Click the "auth" app to fold out the available endpoints.
        * Click the "/auth/login/".
        * Click the "try it out" button to the right.
        * Change the payload to look like this (remove the username field, and fill out the email and password fields, like so:
            ```
            {
                "email": "your_email",
                "password": "your_insanely_complex_password"
            }
            ```
        * Click the blue "execute" button.
        * Now you can copy the entire token.
        * Now click the green "Authorize" button in the top right of the page and paste the token in the field. Remember to write "Bearer" in front of the token - like so:

            ```
            Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.4pXwtyQKCwSrYfcj9O7MGVv5ustPbx0GmYY7jHZL8es
            ```

        * After clicking close, you should now be able to call the other authenticated endpoints.

### 3. Sending the Requests Manually Using Postman or Similar
Alternatively, if you are unable to use the above portal, or if you'd rather use something like Postman or similar,
you can still see the requests and parameters in the portal, but to call them manually, see the below steps.

**Authenticating manually w/o interactive API documentation portal** - you can do the above steps manually by following these steps:

1. Authentication
    To obtain an authentication token, send a post request to https://api.autopi.io/auth/login/
    with header

    ```
    Content-Type: application/json
    ```
    and body

    ```
    { "email": "your email address", "password": "your password" }
    ```

    In the response, you will find the token used to authenticate the below requests

2. To request data from our API, the authorization header should be set.

    You will need to set the "Authorization" header on the requests. To set the header, use the below values.

    * If you're using a JWT token: 
    ```
    Authorization: Bearer YOUR_TOKEN
    ```

    * If you're using an API token: 
    ```
    Authorization: APIToken YOUR_TOKEN
    ```

:::tip
If you find something where you are unsure how to proceed, you can log in to my.autopi.io and use the developer tools
of your favourite browser to see the requests and parameters sent by the application, and if you are still experiencing
issues, you can send us an email to support@autopi.io
:::

## Telemetry data examples
Accessing data from a device is done by calling the logbook endpoint.

**Logbook Storage Read Parameters:**
* **device_id:** ID of the device you want to retrieve data from.
* **field:** Name of the field you want to retrieve the value from.
* **field_type:** type of the field
* **from_utc:** ISO Datetime string
* **to_utc:** ISO Datetime string
* **aggregation:** Aggregation method (AVG, MIN, MAX, SUM)
* **interval:** Data is aggregated based on the aggregation method specified, the interval specifies how many groups the data is grouped into. For example, getting data for a 10 hour period, with the interval set to 1h, you will get back 10 values, one value per hour.

### 1.Getting positions
    ```
    GET /logbook/storage/read/
    ?device_id=DEVICE_ID
    &field=track.pos.loc
    &field_type=geo_point
    &from_utc=2020-01-01T00:00:00.000Z
    &to_utc=2020-01-01T01:00:00.000Z
    ```

Example response:
        ```
        [
            {
                    "ts": "2020-07-09T10:11:53.811839Z",
                    "location": {
                            "lat": 57.04699,
                            "lon": 9.93909
                    }
            },
            {
                    "ts": "2020-07-09T10:11:59.248421Z",
                    "location": {
                            "lat": 57.04697,
                            "lon": 9.93808
                    }
            }
        ]
        ```

### 2. Battery Voltage readings
```
GET /logbook/storage/read/
?device_id=DEVICE_ID
&field=obd.bat.voltage
&field_type=float
&aggregation=avg
&from_utc=2020-01-01T00:00:00.000Z
&to_utc=2020-01-01T01:00:00.000Z
&interval=10m
```

Example response:
```
[
	{
    	    "max_ts": 1594289021415,
    	    "ts": "2020-07-09T10:03:37.566Z",
    	    "value": 13.5
	},
	{
    	    "max_ts": 1594289026525,
    	    "ts": "2020-07-09T10:13:45.378Z",
    	    "value": 13.600000381469727
	}
]
```

## Sending CAN Bus commands examples
Through the API it's possible to send CAN bus commands directly to the vehicle. See the crude example of how to that:

```python
import os
import time
import requests
from typing import Any, Dict, List, Optional

class AutoPiClient:
    def __init__(self, api_token: str, base_url: str = "https://api.autopi.io"):
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        # AutoPi API token auth header format:
        # Authorization: APIToken YOUR_TOKEN
        self.session.headers.update({"Authorization": f"APIToken {api_token}"})

    def list_devices(self) -> List[Dict[str, Any]]:
        url = f"{self.base_url}/dongle/devices/"
        r = self.session.get(url, timeout=30)
        r.raise_for_status()
        return r.json()

    def execute(
        self,
        device_id: str,
        command: str,
        arg: Optional[List[Any]] = None,
        kwarg: Optional[Dict[str, Any]] = None,
    ) -> Dict[str, Any]:
        """
        Executes an AutoPi command on a device via:
        POST /dongle/devices/{device_id}/execute/
        Body format follows the standard command envelope:
          {"command": "...", "arg": [...], "kwarg": {...}}
        """
        url = f"{self.base_url}/dongle/devices/{device_id}/execute/"
        payload = {
            "command": command,
            "arg": arg or [],
            "kwarg": kwarg or {},
        }
        r = self.session.post(url, json=payload, timeout=120)
        r.raise_for_status()
        return r.json()

def non_obd2_can_query_example() -> None:
    """
    Example based on the docs' 'Non-OBD2 Queries' obd.query example:
      obd.query PROPRIETARY_SPEED header=1AA mode=00 pid=01
        can_flow_control_filter=2AA,7FF
        can_flow_control_id_pair=1AA,2AA
        force=True
        formula='bytes_to_int(message.data)'
    """
    api_token = os.environ["AUTOPI_API_TOKEN"]
    client = AutoPiClient(api_token=api_token)

    devices = client.list_devices()
    if not devices:
        raise SystemExit("No devices found on this account.")

    # Pick the first device. Adjust selection logic as needed.
    device_id = str(devices[0]["id"])
    print(f"Using device_id={device_id} (unit_id={devices[0].get('unit_id')})")

    # Non-OBD2 query parameters (headers are examples from the docs)
    result = client.execute(
        device_id=device_id,
        command="obd.query",
        arg=["PROPRIETARY_SPEED"],
        kwarg={
            "header": "1AA",
            "mode": "00",
            "pid": "01",
            "can_flow_control_filter": "2AA,7FF",
            "can_flow_control_id_pair": "1AA,2AA",
            "force": True,
            "formula": "bytes_to_int(message.data)",
        },
    )

    print("Raw execute response JSON:")
    print(result)

if __name__ == "__main__":
    # Usage:
    #   export AUTOPI_API_TOKEN="...your token..."
    #   python autopi_can_query.py
    non_obd2_can_query_example()
```

---

## Send Device Data to Own Server

---

In this guide we will explore how you can setup your own server that accepts data from your [AutoPi](https://www.autopi.io) device. We won't get in too many
details, but we will explore the very basics that are needed, namely:

1. How to setup the device to send data to a server different from the default one
1. What format of the data to expect from the device
1. Code examples of a very basic REST endpoint (in NodeJS with the ExpressJS framework)

Since we will be building the server with NodeJS, this guide requires you to have a very basic familiarity with Javascript syntax, however it
shouldn't be too hard to follow if you have used other programming languages. Also, you will need to have `node` and `npm` command line tools
installed on your workstation. You can download the full NodeJS package from [here](https://nodejs.org/en/download/).

## Set Device's [Cloud](https://www.autopi.io/software-platform/cloud-management) API Url
Firstly, we need to make sure that the device will connect to your own server. For this, we do have a very neat option that can
be changed from the [AutoPi Cloud](https://my.autopi.io) website. You need to navigate to Devices > Select Device > Advanced Settings > Cloud Storage where
you will be able to see a screen like the following:

![cloud_api_uri](/img/getting_started/api/send_device_data_to_own_server/cloud_api_url.png) 

The Url field, under the Endpoint subsection, points to where the device should send data. By default, obviously, it points to [AutoPi](https://www.autopi.io)'s servers. You need to point
instead to a URL that is resolvable from your [AutoPi](https://www.autopi.io) device.

## Device Communication
Before we begin building our server, let's talk about the basic structure of the data that [AutoPi](https://www.autopi.io) devices send out. All data is sent in JSON format.
More specifically an array of JSON objects. Let's look at an example:

```json
[
    // ...
    {
        "utc": "06:02:24",
        "cog": 140.22,
        "nsat": 9,
        "alt": 34,
        "@ts": "2020-09-03T12:38:24.374314Z",
        "@t": "track.pos",
        "sog": 0,
        "loc": {
            "lat": 57.02241,
            "lon": 9.89919
        }
    },
    // ...
]
```

The most important pieces of information in this are the `@t` and `@ts` fields. They are the type and timestamp fields. The rest of the fields are depending
on what type of data is being sent. Due to this, you are also able to decern what data fields you will receive based on the type that is provided. At the
[end](#device-data-examples) we will provide you with more example data sets.

It is also important to mention what the device will do when you send back a response. 2xx response codes like 200 OK will notify the device that the data
has been saved properly and in turn the device will delete the data that was just sent. 4xx and 5xx response codes will let the device know that the
data wasn't correctly saved, so the device will try sending the data again later.

## Let's Build a Server
As mentioned in the introduction, this guide we will be using NodeJS with the ExpressJS framework. Although we are using NodeJS in this guide,
this is entirely possible to do with any other language that has such capabilities, like Python, .NET, Java and so on.

Before we begin writing any code, we need to bootstrap our work environment. Let's begin by setting up an npm environment:

```
npm init
```

This command will ask you for some details about the new environment that you will be working in. You don't need to be too specific.
After you have initialized your environment, we should install the express framework:

```
npm install --save express
```

:::note
By default, with version npm 5.0+ npm install adds the module to the dependencies list in the package.json file; with earlier versions of npm,
you must specify the --save option explicitly. Then, afterwards, running npm install in the app directory will automatically install modules
in the dependencies list.
:::

Now that we have it installed, we can finally start writing code by creating an `index.js` file, or whatever you set the entry point to
be named, in the root directory, or if you'd prefer, create a directory where you will keep your source code and create it there.

Firstly, we start off by creating an express application:

```javascript
// index.js

const express = require('express');
const app = express();
```

The express application object will be used to setup the configuration for our API routes. We can use the `get`, `post`, `put` and `delete`
methods of the `app` object to build up the routes which will be available on your server. Let's look:

```javascript
// index.js

app.get('/', (req, res) => {
    res.send('Hello world!');
});
```

The above example simply allows clients to make a `GET` request to your server and will respond with a 'Hello world!' message. Express
automatically sets the response code to 200 OK with the [`send`](https://expressjs.com/en/4x/api.html#res.send) method unless specified
otherwise. Now that we have our first API endpoint specified, it is time that we started the server up:

```javascript
// index.js

const port = 8000;
app.listen(port, () => {
    console.log(`Example express application listening on port ${port}`);
});
```

With this, we are ready to test out our application. Run `node index.js` in your command line and after you see the console message appear,
navigate your browser to `localhost:8000`. You should be able to see the 'Hello world!' message appear on your screen.

Let's now work with a more specific example. As expected, your device will be trying to send data over to your server. This data will be
sent through `POST` requests, which means that we will need to change the method which the server recognizes and extract the data from the
request body. Since the device will send data over in JSON format, you will also need to use a body parsing middleware such as
[`express.json()`](https://expressjs.com/en/4x/api.html#express.json). Make sure to add the new code before you call the `listen`
method on your express application.

```javascript
// index.js

const express = require('express');
const app = express();

app.use(express.json());

app.post('/', (req, res) => {
    // this is the data that was sent by the device
    const data = req.body;

    // work with data in some way
    console.log(data);

    res.response(200).end();
});

app.listen(/* ... */);
```

## Authentication
Of course, it would be nice if there is some type of authentication happening, instead of letting everyone send data over to your server.
You can do that by adding a middleware function that will authenticate based on the token that is being sent by the device. You can find the token
your device uses by navigating over to [AutoPi Cloud](https://my.autopi.io) > Device > Advanced Settings > Cloud Storage. One of the first fields there should be the
Auth Token field. The token will be sent in the `Authorization` HTTP header in the following format:

```
Authorization: Bearer AUTH_TOKEN
```

Now that we know what the token is, we can write a middleware function that we can later use to authorize client requests. We can get the `Authorization`
header's data by using the [`req.get()`](https://expressjs.com/en/4x/api.html#req.get) method inside the middleware:

```javascript
// authenticate.js

module.exports = function authenticate(req, res, next) {
    const authorizedToken = "SOME TOKEN PASTED IN HERE OR SOMEWHERE ELSE";
    const token = req.get('Authorization');
    
    if (token !== `Bearer ${authorizedToken}`) {
        // token is invalid, bail out
        res.status(401).end();
        return
    }

    // token is valid, call next middleware function
    next();
}
```

One thing that we can notice in the `authenticate` function is that it accepts the same arguments as the function that we created for the router,
`req` and `res`. Those are the same request and response objects that are passed on all middleware functions with data for the specific request
that is being processed at the time. The `next` parameter is an extra parameter that is also passed to each middleware function. Its purpose is
to pass the flow to the next middleware function. If the `next` function is called without any arguments, the next middleware function will be
called, if it is called with any argument, for example a string or an `Error` object, it will return a 500 status code to the users and finally,
if it isn't called at all the flow will stop at the current middleware function. More information on middleware functions can be found
[here](https://expressjs.com/en/guide/writing-middleware.html).

After implementing `authenticate`, you can attach it to the already existing router:

```javascript
// index.js

const express = require('express');
const app = express();

// import the authenticate function
const authenticate = require('./authenticate.js');

app.use(express.json());

// add it as an argument to the post method, right before the actual receiver of the data
app.post('/', authenticate, (req, res) => {
    const data = req.body;
    // work with data in some way
    res.response(200).end();
});

app.listen(/* ... */);
```

With all this setup, your server should be ready to accept data from your device. Of course, this code example is not going to store any of the data
that is being sent from the device, but you are able to manipulate, store or do anything else you'd like with your data the way you prefer to.

## Final Thoughts
It should be fairly simple to get a server up and running to accept data from any [AutoPi](https://www.autopi.io) device. This guide went into brief details on how to implement such a
server in NodeJS, however implementing a REST API server is very simple with any other modern programming language. As usual, if you have any questions in regard
to this, feel free to contact our support team on support@autopi.io and they will be more than happy to give you guidance.

## Full Example Code
```javascript
// authenticate.js

module.exports = function authenticate(req, res, next) {
    const authorizedToken = "SOME TOKEN PASTED IN HERE OR SOMEWHERE ELSE";
    const token = req.get('Authorization');

    if (token !== `Bearer ${authorizedToken}`) {
        // token is invalid, bail out
        res.status(401).end();
        return
    }

    // token is valid, call next middleware function
    next();
}
```

```javascript
// index.js

const express = require('express');
const app = express();
const authenticate = require('./authenticate.js');

const port = 8000;

app.use(express.json());

app.post('/', authenticate, (req, res) => {
    const data = req.body;

    // work with data in some way
    console.log(data);
    res.response(200).end();
});

app.listen(port, () => {
    console.log(`Example AutoPi clone is running on ${port}`);
});
```

## Device Data Examples

Following are some example data sets that [AutoPi](https://www.autopi.io) devices send regularly.

#### GPS Position
```json
[
    // ...
    {
        "utc": "06:02:24",
        "cog": 140.22,
        "nsat": 9,
        "alt": 34,
        "@ts": "2020-09-03T12:38:24.374314Z",
        "@t": "track.pos",
        "sog": 0,
        "loc": {
            "lat": 57.02241,
            "lon": 9.89919
        }
    },
    // ...
]
```

#### OBD Voltage Level
```json
[
    {
        "voltage": 15.4,
        "@ts": "2021-02-24T09:03:09.310362Z",
        "state": "overcharging",
        "level": 100,
        "@t": "obd.bat",
    },
    // ...
]
```

#### SIM Card Data Usage
```json
[
    {
        "sent": 2695,
        "@t": "ec2x.data_usage",
        "recv": 4742,
        "@ts": "2021-02-24T09:03:02.570313Z",
    },
    // ...
]
```

#### Events
```json
[
    {
        "@tag": "system/minion/online",
        "@t": "event.system.minion",
        "@ts": "2021-02-24T09:02:12.192479Z",
    },
    // ...
]
```

Note that there are some events that do send out some data along, for example:

```json
[
    {
        "trigger": "stn",
        "awaken": "sleeping",
        "@ts": "2021-02-24T09:02:02.532461Z",
        "@tag": "system/power/on",
        "@t": "event.system.power",
    },
    // ...
]
```

---

## 4G Internet Setup Troubleshooting

---

This guide helps you diagnose and resolve common 4G connectivity issues on your [AutoPi](https://www.autopi.io) device. If you cannot access the internet while connected to the device hotspot, follow the steps below in order.

:::tip Our support team is here to help you.
If you need assistance, contact support@autopi.io.
:::

### Prerequisites
Before starting, complete the initial [setup guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/).

---

### Check SIM Card

* Confirm that your SIM card is enabled for mobile datta. Test the SIM in another device (for example, a smartphone) and verify that internet access works.
* If you are using a data-only SIM, confirm with your carrier that the data plan is active and roaming is enabled when required.
* Verify that the SIM card is not PIN-locked. If it is PIN-locked, enter the correct PIN in the device settings.
* Remove and reinsert the SIM card, and inspect both the SIM and slot for physical damage. Bent contacts, debris, or a loose SIM slot can prevent modem detection.
* Make sure the SIM orientation is correct. The text side of the SIM card must face up, and the triangle end must point into the device.

    :::caution
    When inserted correctly, you should hear a small click as the card locks into position.
    Do not force the SIM card out after the click, as this can damage the slot.
    Always verify orientation before insertion.
    :::
---

### Check Modem Detection (Hardware)

* Connect to the device hotspot and open [AutoPi Local](http://local.autopi.io).
* Open the terminal and run:

    ```python
    cmd.run "lsusb"
    ```

* The output of the command should be similar to this:

    ![lsusb](/img/getting_started/autopi_tmu_cm4/4g_internet_setup_troubleshooting/lsusb.jpg)

* The important part to look for is the Modem. The ID will be different depending on which modem your device is equipped with:

    | **Modem Manufacturer** | **USB ID** |
    |:------------------------:|:------------:|
    | Quectel                | `2c7c:0121` |
    | Telit                  | `1bc7:1031` |

* If you ordered a 4G edition and you don't find the modem in your list, then please contact support@autopi.io. 

---

### Check Modem Setup

#### Check PDP Context

PDP context controls how the modem connects to the mobile network. Incorrect values can prevent data sessions from starting.

For software version `1.22.7 or newer`:

```python
modem.connection pdp_context
```

For `older versions`:

```python
modem.connection execute AT+CGDCONT?
```

Expected output is either:

```python
**data: '+CGDCONT: 1, "IPV4V6","",0,0,0,0'**  
```
or
```python  
**Data:**   
**- '+CGDCONT:1,"IPV4V6","",0,0,0,0'**   
**- '+CGDCONT:2,"IPV4V6","ims","",0,0,0,0'**
```

If the dual-context result causes connectivity issues, reconfigure with:

```python
cmd.run "systemctl stop qmi-manager"
modem.connection execute AT+CGDCONT=2
cmd.run "systemctl restart qmi-manager"
```

Run the PDP command again to confirm the result.

#### Check Firmware Switch

An incorrect firmware switch setting can prevent the modem from connecting to the network correctly.

For software version `1.22.7 or newer`:

```python
modem.connection active_firmware_image
```

this should return a message that looks like this.  
```python
**_stamp: "the curent date"**  
**_type: active_firmware_image**  
**net_conf:global**  
**storage_conf: ram**  
```
Here we are looking to see if the `net_conf` is set to global.

For `older versions`:

```python
modem.connection execute AT#FWSWITCH?
```

Expected output:

```python
FWSWITCH:40:1
```

If the value does not start with `40`, configure it manually:

```python
modem.connection execute AT#FWSWITCH=40,1
```

Restart the device and verify again.

:::tip
For additional modem commands and examples, see [Core Commands - Modem](https://docs.autopi.io/core/commands/core-commands-modem/).
:::

---

### Check APN Configuration

A missing or incorrect APN can block internet access even when the modem is detected.

:::note
If you are using the AutoPi SIM card (included with monthly cloud subscription), APN is pre-configured on newly shipped devices.
In most cases, you can skip this section.
If you want to verify manually, APN should be set to **nxt20.net**.
:::

Check the current APN:

```python
modem.connection pdp_context
```

If APN is missing and your carrier requires it, set it manually:

```python
modem.connection execute AT+CGDCONT=1,"IPV4V6","<your-apn>"
```

Then restart the manager:

```python
cmd.run "systemctl restart qmi-manager"
```

:::tip
If you do not know your APN, check your carrier documentation or support channel.
:::

---

### Check qmi-manager Status

`qmi-manager` maintains the cellular data connection.

Check status:

```python
cmd.run "qmi-manager status"
```

Expected output: 

![qmistatus](/img/getting_started/autopi_tmu_cm4/4g_internet_setup_troubleshooting/qmistatus.jpg)

If needed, restart it:

```python
cmd.run "systemctl restart qmi-manager"
```

---

### Restart the Network Interface

If `qmi-manager` is running but internet is still unavailable, cycle the interface:

```python
cmd.run "qmi-manager down"
cmd.run "qmi-manager up"
```

If SIM detection fails on `up`, power down the device, check SIM orientation and seating, then try again.

Check interface state and IP address:

```python
cmd.run "ip link show wwan0"
cmd.run "ip addr show wwan0"
```

If `wwan0` has no IP address, the mobile session is not established.

---

### Adjust the MTU Setting

If connection is unstable (drops, intermittent cloud status), tune MTU. Based on your board version, the default MTU is either `1500` or `1280`.

If your default is `1280`, change it to `1500` and check whether the device comes online.
If your default is `1500`, change it to `1280` and check whether behavior improves.
This quick comparison helps confirm whether MTU is causing the issue.

Apply MTU:

```python
grains.set qmi:mtu <value>
state.sls network.wwan.qmi.config
```

Verify:

```python
grains.get qmi:mtu
cmd.run "cat /etc/udhcpc/qmi.override"
```

Confirm that both outputs match the configured MTU.

:::note
* **US Verizon**: start with MTU `1428`.
* **Other carriers**: start with MTU `1280`.
:::

---

### Check Internet and Cloud Connectivity

Test internet over cellular:

```python
cmd.run "ping -c 5 -I wwan0 google.com"
```

Test AutoPi Cloud access:

```python
cmd.run "curl -v my.autopi.io"
```

If ping works but cloud access fails, test DNS:

```python
cmd.run "nslookup my.autopi.io"
```

If DNS fails, try a temporary public DNS value:

```python
cmd.run "echo 'nameserver 8.8.8.8' > /etc/resolv.conf"
```

Then re-run ping and curl.

---

### Collect Logs for Support

If the issue persists, collect logs before opening a support request.
Follow this guide to export relevant logs: [AutoPi Logs Guide](https://docs.autopi.io/developer_guides/autopi-logs/)

---

### Summary

By this point, you should have verified:

1. SIM compatibility, orientation, and slot condition.
1. Modem detection and modem configuration (PDP and firmware switch).
1. APN settings.
1. `qmi-manager` and `wwan0` status.
1. MTU tuning and DNS/cloud connectivity tests.

:::note
If you open a support case, include the full output from all commands used in this guide, along with the collected [Logs](https://docs.autopi.io/developer_guides/autopi-logs/).
:::

---

## Accessing files via SFTP/SCP on AutoPi

---

:::note
If you want to use scp on Windows to download files from the autopi, you need to set up openssl.  
:::

## Option 1: Accessing files via SFTP

### Prerequisites 
1. **Username**: `pi`.  
2. **Password**: The password for the `pi` user (Available in advanced settings panel).  
3. **Network Connection**: Ensure the AutoPi and your computer are on the same network (via one of the methods below).  
4. **Software**:  
   - *GUI Tool*: [Cyberduck](https://cyberduck.io/)(free).  
   - *CLI Option*: Use `scp` or `sftp` commands in Terminal (macOS/Linux) or PowerShell/WinSCP (Windows).  

---

### Step 1: Determine the Device’s IP Address  
Choose your connection method:  
  * **1. Local WiFi Hotspot**  
    - Ensure the device is connected to the hotspot.  
    - The IP is often static (e.g., `192.168.1.1` or `10.0.0.1`).  

  * **2. WiFi Client Network**  
    - Connect the device and your computer to the same WiFi network.  
    - Find the device’s IP:  
      - Check your router’s DHCP client list (e.g., `192.168.0.100`).  
      - In the terminal on AutoPi's cloud, run this command:
        ```python 
        hostname -I
        ```  

  * **3. Ethernet (Direct Connection)**  
    - Connect the AutoPi to your computer via Ethernet.  
    - The IP may be assigned via DHCP (check router) or use a static IP like `169.254.x.x`.  

  * **4. Tailscale (VPN)**  
    - Ensure Tailscale is installed and activated on both the AutoPi and your computer. You can read more at this guide: [How to connect to Tailscale on your AutoPi device](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/)
    - On the AutoPi, run `tailscale ip` to get its Tailscale IP (e.g., `100.x.x.x`).  

:::note
If tailscale is setup on the device, you can use the IP address in the tailscale configuration to download from anywhere, this setup is equivalent to using the local IP.
:::

### Step 2: Connect Using Cyberduck
1. Open Cyberduck and click **Open Connection**.  
2. Configure settings:  
   - **Protocol**: SFTP (SSH File Transfer Protocol).  
   - **Server**: Enter the IP address (from Step 1).  
   - **Username**: `pi`.  
   - **Password**: Enter the `pi` user’s password.  
   - **Port**: `22` (default for SSH/SCP).  
   - *(Optional)*: Save the password in your keychain.  

   Read more here: [Cyberduck Documentation](https://docs.cyberduck.io/protocols/sftp/)  

3. Click **Connect**.  

### Step 3: Access Files 
- After connecting, navigate to:  
  ```plaintext
  /opt/autopi/can0/   # For CAN0 bus data  
  /opt/autopi/can1/   # For CAN1 bus data  
  ```  
- **Upload/Download**: Drag and drop files between Cyberduck and your computer.  

---

## Option 2: Connect via Command Line (SCP)

Use `scp` to transfer files directly.  

#### **Download a File**  
```bash  
scp pi@[IP_ADDRESS]:/opt/autopi/can0/filename.txt /local/destination  
# Example:  
scp pi@192.168.0.100:/opt/autopi/can0/log.csv ~/Downloads  
```  

#### **Upload a File**  
```bash  
scp /local/file.txt pi@[IP_ADDRESS]:/opt/autopi/can1/  
```  

---

## Troubleshooting  

- **Connection Failed?**  
  - Verify the AutoPi and your computer are on the same network.  
  - Ensure SSH is enabled on the AutoPi by checking the advanced settings or running this command in the terminal:
    ```python 
    sudo systemctl enable ssh
    ```  
  - Check firewall/antivirus settings (allow port 22).  
- **Tailscale Issues?**  
  - Confirm both devices are logged into the same Tailscale account.  
  - Restart Tailscale by running this command: 
    ```python 
    sudo systemctl restart tailscaled
    ``` 

---
:::note
**Security**: For Tailscale, no need to open port 22 on your router—traffic is encrypted through the VPN.  
**Default Paths**: Double-check `/opt/autopi/can0` or `/can1` for your specific files. 
:::

---

## Data Troubleshooting

---

You are experiencing issues with getting the data out of your [CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro)? This guide help you step-by-step to identify and resolve common problems related to wrong configurations on device, configurations to CAN Loggers, verification of CAN channels, nominal voltage detection, and internet connectivity issues. 

:::tip Our support team is here to help you.
Get in touch here or send an email to support@autopi.io
:::

### Prerequisites:
Before following this guide, you must have completed the initial [Setup guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/).

### Why am I not seeing any data? 
If you've followed the [Getting Started Guide](/getting_started/autopi_canfd_pro/index.md)
and tested your [AutoPi](https://www.autopi.io) [CAN-FD Pro](https://www.autopi.io/hardware/autopi-canfd-pro) device during vehicle operation, but are not recording any data, this guide will help you identify and resolve common issues. 

This guide is organized as a checklist, detailing potential reasons why your vehicle
data might not be recorded. It is only intended for the
[AutoPi](https://www.autopi.io) [CAN-FD Pro](https://www.autopi.io/hardware/autopi-canfd-pro) device.  

## Common causes and solutions for no data recorded

### 1. Identify the current state of the device

Check the two LEDs on the side of the device. Both the green and blue LEDs should be lit. If the green LED is off and the blue LED is “breathing” or fully dimmed the device is either sleeping or hibernating. To resolve this re-plug or push the button on the side of the device to boot it up again.

For more details on LED status meanings, refer to this guide: [LED and button states](https://docs.autopi.io/hardware/autopi_canfd_pro/pro-led-and-button/)

### 2. Check the CAN loggers

Run the `logger.status` command on the device to see the status of data logger(s).

1. If the device is connected to the Internet it can be done through the cloud terminal on [AutoPi cloud](https://my.autopi.io/).
2. Or alternatively if you have direct SSH access [How to SSH to your device](https://docs.autopi.io/developer_guides/how-to-ssh-to-your-device/) to the device via LAN or VPN (for Tailscale, you can read more at this guide: [How to connect to Tailscale](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/)) you can use the `autopi` terminal command.
3. Or if you are nearby the device and can connect to it's local WiFi hotspot you can do it from the local admin UI on local.autopi.io. Here is a guide: [Local development workflow](https://docs.autopi.io/developer_guides/local-development-workflow/). 

Regardless of which of the above methods you use, you must run the command: 
```python 
logger.status
```

Below is an example of the output of the command: 

```
channels:
  can0:
    interface:
      autodetect:
        in_progress: false
        last_results:
          any_passive:
            bitrate: 500000
            frames_per_second: 710
            has_11bit_identifiers: true
            has_29bit_identifiers: false
            performed_at: '2025-05-07T09:50:43.347462'
            success: true
      bitrate: 500000
    loggers:
      raw:
        current_fps: 584.95
        decoders:
          dbc:
            failed_messages_count: 140000
            output_file_pattern: /opt/autopi/can0/loggers/raw/decoders/dbc/output/{input:}.jsonl
            output_handlers:
            - destination_path: s3://my-datalogger/a1eeabbd-cffa-f7c4-31a5-49b2c2340d3d/can0/decoded
              uploaded_files_count: 2
            total_messages_count: 140000
            type: STANDARD
        output_file_pattern: /opt/autopi/can0/loggers/raw/output/{ts:%Y%m%d%H%M}.log
        output_handlers:
        - destination_path: s3://my-datalogger/a1eeabbd-cffa-f7c4-31a5-49b2c2340d3d/can0/raw
          uploaded_files_count: 2
        received_error_frames_count: 613
        received_frames_count: 111101
  can1:
    interface:
      autodetect:
        in_progress: false
        last_results:
          any_passive:
            bitrate: 500000
            frames_per_second: 544
            has_11bit_identifiers: true
            has_29bit_identifiers: false
            performed_at: '2025-05-07T09:50:44.198244'
            success: true
      bitrate: 500000
    loggers:
      raw:
        current_fps: 586.66
        decoders:
          dbc:
            output_file_pattern: /opt/autopi/can1/loggers/raw/decoders/dbc/output/{input:}.mf4
            total_messages_count: 0
            type: ASAMMDF
        output_file_pattern: /opt/autopi/can1/loggers/raw/output/{ts:%Y%m%d%H%M}.log
        received_error_frames_count: 613
        received_frames_count: 113725
disks:
  /:
    free_space: 3 GB
    housekeeper:
      deleted_files_count: 0
      total_space_freed: 0 bytes
```

### 3. CAN bus detection

Verify the settings of the CAN channels. Configuration of the device is done through the [AutoPi cloud](https://my.autopi.io/). 

### 4. Nominal voltage detection

When the device boots it attempts to autodetect the nominal voltage.

* **Auto-detect voltage:** This is a new feature that comes enabled by default on all [AutoPi](https://www.autopi.io) [CAN-FD Pro](https://www.autopi.io/hardware/autopi-canfd-pro) devices. That means you do not need to configure the nominal voltage manually - your device will automatically detect it. The result of autodetection of nominal voltage is available below the Events tab.
If you want to double check if this feature is enabled, Go to Devices > Choose Device > Settings > Vehicle Editor to see if the Auto-Detect Voltage is enabled.

    ![Autodetect feature](/img/getting_started/autopi_canfd_pro/autodetect_voltage.png)

* **Manual configuration:** If the device is unable to autodetect the nominal voltage on the vehicle, you might need to configure it manually. Go to Devices > Choose Device > Settings > Vehicle Editor > Nominal Voltage > click on the field and choose from 12V or 24V. Make sure the correct configuration is set from the dropdown.  

    ![Manual configuration of nominal voltage](/img/getting_started/autopi_canfd_pro/nominal_voltage.png)

### 5. Internet connectivity issues 

Ensure your device is connected to the internet. If there are connectivity issues,
follow the steps outlined in our [4G Internet Setup and Troubleshooting Guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-4g-internet-setup-troubleshooting/).

### 6. Verify bitrates 

Ensure the correct Bitrate is set for your vehicle, you can follow this guide: [Find the correct Bitrate for your vehicle](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/#step-4-try-bitrates-or-use-fixed-bitrate). The default list for Try Bitrates includes some of the most common used bitrates to make this process easier for you. This step allows you to make sure that you can receive any data by listening to these settings. 
* You have 2 options here: 
  * **1. Try bitrates (auto mode):**
      If you are unsure about your vehicle’s bitrate, this is the best choice.
        The device will automatically scan through a list of common CAN 2.0 and CAN FD bitrates.
  * **2. Fixed bitrate (manual mode):**
    If you know the exact bitrate for your vehicle you can input it directly to skip scanning. 

**Autodetect** feature under CAN Channel settings, is used to figure out how to find the correct bitrate using 3 different detection strategies to ensure there is data incoming. You can read more in this guide, on [How to find the correct bitrate](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/#step-3-autodetect-how-to-find-the-correct-bitrate). Every time the autodetection is performed, it triggers an **event** that can be seen in the events section on [AutoPi cloud](https://my.autopi.io/) -> go to devices > pick the device > events. This should help you to understand a little better what is happening on a device. These are some of the examples for the events that can be used for verifying the bitrates: 
- `vehicle/bus/can0/autodetected`
- `vehicle/bus/can0/autodetect/any_passive/successful` 
- `vehicle/bus/can0/autodetect/any_passive/unsuccessful` 

### 7. Make sure you are receiving data

**Step 1: Configure output handlers:**
* To ensure your device sends data to the correct destination, you need to set up output handlers properly. This step is essential for reliable communication between your device and the receiving service.
* Follow the instructions in the guide here: [How to set up Output Handlers](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/#step-4-outputs). 

**Step 2: Verify file access via Wi-Fi hotspot:**
* Once your output handlers are configured, verify that you can access the files from the device. This is important to confirm your setup is working correctly.
* Follow the instructions in the guide here: [Accessing files via SFTP/SCP on AutoPi](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/)

---

## How to connect to Tailscale on your Autopi device

---

Tailscale makes creating software-defined networks easy: securely connecting users, services, and devices. Your [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) has already [Tailscale](https://tailscale.com/) installed, however it is not active just yet. You have full control over this! If you want to connect to Tailscale on your device follow this guide.

You can also use this video for [**Tailscale quickstart video guide**](https://youtu.be/sPdvyR7bLqI).

### 1. Enable Tailscale on your device
Steps to enable Tailscale on your device: 
* Navigate to Devices section on [Autopi cloud](https://my.autopi.io/).
* Click the device you want to enable Tailscale on.
* Go to advanced settings > Tailscale. 
* Check if Tailscale is already enabled on your device. If it is, you're all set! This is how it looks like: 
    
![Tailscale enabled](/img/getting_started/autopi_canfd_pro/tailscale_enabled.png)

* If Tailscale is not enabled, go ahead and enable it.
Once enabled, your device will create a pending sync which needs to be synced to a device before the Tailscale is fully enabled. You can check this by clicking the "Pending" icon at the bottom right side of the platform. Pending sync look like this: 

![Tailscale pending sync](/img/getting_started/autopi_canfd_pro/pending_sync.png)

* Make sure the device has synced the change. You can do that by clicking sync button above the created pending sync. 

### 2. Create a tailnet
Go to [tailscale.com](https://tailscale.com/) and select Get Started. Alternatively, you can download and install the Tailscale client on your device, then sign up.

### 3. Open tailscale on your computer

There are few ways on how to open tailscale on your computer: 
* On Windows/macOS/Linux: Open the Tailscale app from the system tray or menu bar.
* On Android/iOS: Open the Tailscale app from your app drawer.
* On CLI (Linux/macOS/Windows Command Prompt/PowerShell): Open a terminal and type:
    ```python 
    tailscale up 
    ```

### 4. Log in to [Tailscale](https://login.tailscale.com/start) on your computer 

* If you're not already logged in, the app will prompt you to authenticate.
* Click "Log in", and a browser window will open.
* Choose your authentication method (Google, Microsoft, GitHub, or custom SSO).
* After logging in, allow the request to connect your device to the network.

### 5. Generate auth key for your device
* Use this link to generate auth key: [Generate auth key](https://login.tailscale.com/admin/settings/keys)
* Option 1: Insert Auth Key in Advanced settings on your device: 
    - Navigate to Devices section on [Autopi cloud](https://my.autopi.io/)
    - Click the device you want to insert the auth key on. 
    - Go to advanced settings -> Tailscale.
    - Fill out the Auth key. Make sure the tailscale is enabled. 

* Option 2: Run up command with auth key in terminal: 
    ```python 
    cmd.run 'tailscale up --authkey=tskey-KEYKEY-KEYKEYKEYKEY'
    ```

:::note
Make sure you use the key that was generated in the first step of this section and replace it accordingly in the command with your auth key.
:::

### 6. Confirm connection 

* Once logged in, your device should appear in the [Tailscale admin panel](https://login.tailscale.com/admin/machines)
* In the Tailscale app, you should see "Connected" with an assigned Tailscale IP (e.g., 100.x.x.x).
* If using CLI, check your connection with: 
    ```python 
    tailscale status 
    ```

### 7. Test your connection 

* Check your [Tailscale admin panel](https://login.tailscale.com/admin/machines) - to make sure you are able to see both your device and your computer in this list. This gives you an indication that you have everything set up correctly.
* After finishing the whole process, you can SSH from your computer to a device - this gives you the full access to Tailscale. 

### 8. Optional: Enable exit node (if needed)

If you want to route all traffic through another device on your Tailscale network:
* Open the Tailscale app.
* Click "Use Exit Node" and select a device.
* On CLI, use:
    ```python 
    tailscale up --exit-node=100.x.x.x 
    ```

### 9. Disconnect when needed
To disconnect from Tailscale:
* In the Tailscale app, click "Disconnect".
* In CLI, run:
    ```python 
    tailscale down 
    ```

:::note
There is also a way to permanently disable and stop the tailscale service (to prevent the big data usage on your device). This is how you can do so: 

* Disable + stop tailscale service (tailscaled) so it will not automatically start on boot: 
    ```python
    cmd.run 'systemctl disable tailscaled'
    cmd.run 'systemctl stop tailscaled'
    ```

* Enable + start: 
    ```python
    cmd.run 'systemctl enable tailscaled'
    cmd.run 'systemctl start tailscaled'
    ```
:::

That's it! Your [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) is now connected to [Tailscale](https://tailscale.com/). Enjoy secure and remote access to your [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro).

---

## Getting started(Getting_started)

---

:::note
The device comes pre-assembled with the SD card inside and requires just a few steps to complete the installation.

1. **Power Off the Vehicle**: When inserting the device for the first time, ensure that the vehicle is powered off.
2. **Vehicle Must Be Parked**: When working on and customizing your device, make sure your vehicle is in the parked position.
3. **Do Not Remove the AutoPi While Driving.**
4. **Power Source**: The device can only be powered through the OBD-II port.
     Powering the Raspberry Pi directly is not supported and may cause issues.
5. **Advanced Settings Caution**: When updating the Advanced settings, ensure you understand what you
     are doing, as changes can affect the performance of your car and its battery.  

:::

## [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) Quick Start Summary
* Step 1: Set up your account on [AutoPi Cloud](https://my.autopi.io/), you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#1-setting-up-user-account).
* Step 2: Register your device on [AutoPi Cloud](https://my.autopi.io/), you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#2-register-your-device). 
* Step 3: SIM card installation (if you did not purchased one from us), you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#3-ensure-sim-connectivity).
* Step 4: Attach the External Antenna Kit to your AutoPi CAN-FD Pro device, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#4-attach-the-external-antenna-kit).
* Step 5: Locate an OBD port in your vehicle/equipment, you can read more about tips and tricks [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#5-locate-obd-port).
* Step 6: Device installation to your vehicle's OBD-II port, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#6-installation).
* Step 7: Connect your device to the [AutoPi Cloud](https://my.autopi.io/), you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#7-connect-to-wifi). 
* Step 8: Connect to Local Administration on your device, and set up APN User and MTU, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#8-connect-to-local-administration). 
* Step 9: Verify connectivity to ensure your APN setting is set properly, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#9-verify-connectivity). This setting is only for users using their own SIM card, if you have purchased a device with AutoPi SIM, you can skip this step. 
* Step 10: Change your password, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro/#10-finalization).
* Step 11: Set up output handlers for data (where do you want the captured data to be send to), you can read more [in this guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/#step-4-outputs).
* Step 12: Access the files remotely, you can read more [in this guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/).

---

## Getting started
This step-by-step guide will help you set up your AutoPi CAN-FD Pro. 

## 1. Setting Up User Account

Once you have received your AutoPi device it is important to associate it with Cloud Platform.
Go to [my.autopi.io](https://my.autopi.io/) and click “Sign up”. In the pop-up, 
add the e-mail address you want to associate with your account and create a password. 
You can also expand the form to add additional details like your country and full name, 
though this can be done later. Click “Create account”.

![AutoPi sign up](/img/getting_started/getting_started/sign_up.png)

## 2. Register Your Device

After creating an account, you can access the Cloud Platform features for fleet and device management.
The next step is to register your device to unlock the platform’s full potential.  

To add a device to your account, follow one of these methods:  

**Option 1: Via Device Management**
1. See the “Device Management” section of the Platform. 
2. Click on “Devices”. 
3. Find and click the “Register Device” button in the upper right corner. 

**Option 2: Via the Accounts Tab**
1. Navigate to the “Accounts” tab at the bottom of the left side menu on the Platform.
2. Select “Devices”. 
3. Locate and click the “Register Device” button in the upper right corner.

After clicking the “Register Device” button, the registration tab will appear. Enter all necessary information: 

![Register Device](/img/getting_started/getting_started/register_new_device.png)

- **Unit ID**: This is the number on the side of your device. You can also find it in the.
    document attached in the email you received when the device was shipped. 
- **Vehicle Information**: Optionally include the make, model and year of the vehicle.
- **Vehicle Type**: Choose the type of vehicle (ICE, Battery [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini), Hybrid [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini), or Plug-in Hybrid [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini)).

Once all information is entered, click the “Register Device”. Your newly registered device 
will now appear in the list under “Vehicles” in the Fleet Management section and under 
“Devices” in the Device Management section of the Platform.

## 3. Ensure SIM Connectivity

:::note
If you have purchased the AutoPi TMU CM4 with monthly cloud subscription, 
your SIM card is already assembled in the device, so you can skip this step. 
:::

If you have purchased the hardware-only version, you will need to insert your SIM card 
into your AutoPi before connecting the device to your vehicle. The AutoPi uses nano SIM sizes. 
The location of the SIM card slot is shown in the picture below.  

When inserting the SIM card, it’s important to ensure it is installed correctly. 
The picture below shows the proper orientation of the SIM card. 
Please note that the text side of the SIM card must face up and the “triangle” end point into the device. 

![AutoPi.io - SIM card location](/img/getting_started/getting_started/sim_card.png)

:::caution
**Please notice:** When the SIM card is inserted correctly, you will hear a small "click" when the
card is in position. Don't try do force the SIM out after the click as this will damage the device.
Make sure the orientation is correct before inserting the SIM. Wrong orientation could potentially
damage your device.
:::

:::caution
**Please notice:** The SIM card needs to be compatible with ipv4, for the device to establish a 4g/LTE connection. 
:::

Here's a list of the US based SIM providers that we recommend to be used with the AutoPi:
1. AT&T
2. T-Mobile
3. Any MVNO provider that is roaming the networks of the providers above

## 4. Attach the External Antenna Kit
Each device comes with a labeled sticker showing which antenna connects to each port, making installation simple and error-free.
Your AutoPi CAN-FD Pro includes the following antennas:
* 2 × 4G antennas
* 1 × GPS antenna
* 1 × Wi-Fi antenna (2.4G)

	

To attach the antennas, gently screw each one into its corresponding port by hand. There’s no need for tools, just make sure each antenna is firmly and securely fastened.
Below, you can see examples of the device with and without the external antenna kit installed.

AutoPi CAN-FD Pro without the external antenna kit installed: 
![Pro without external antenna kit](/img/hardware/shared_devices/side_look_device_sticker_antenna_smaller.png)

AutoPi CAN-FD Pro with the external antenna kit installed:
![Pro with external antenna kit](/img/hardware/shared_devices/side_look_device_4in1_antenna.png)

## 5. Locate OBD Port

Next step is to locate your OBD port in your car, it is usually found underneath the dashboard and
looks something like this:

  ![AutoPi.io - OBD port](/img/getting_started/getting_started/obd_location.jpg)

The location of the OBD port varies from make and model, but is typically fund in one of the
locations shown below:

![AutoPi.io - OBD port location](/img/getting_started/getting_started/TMU_placement_dashboard_v1_finecut-01.jpg)

## 6. Installation

When installing the AutoPi, always make sure that the device is positioned with 
the logo facing upwards towards the sky. This orientation is crucial because the GPS antenna 
is located within the device, and incorrect positioning may result in a weak GPS signal. 

If the OBD port is in an inconvenient spot or gets in the way, 
you can buy some **Accessories** from our [AutoPi shop](https://shop.autopi.io/): 
    * [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable?pr_prod_strat=jac&pr_rec_id=f2111200b&pr_rec_pid=8619775328605&pr_ref_pid=14961336746333&pr_seq=uniform) – add extra reach for flexible placement.
    * [Dual Lock Extreme Velcro Strip](https://shop.autopi.io/products/dual-lock-extreme-velcro) – secure, vibration-resistant mounting anywhere.
    * [DoIP HAT](https://shop.autopi.io/products/doip-hat-v1-3) - the DoIP HAT is a highly advanced interface module designed to enhance vehicle diagnostics using the DoIP protocol (Diagnostics over Internet Protocol).  
    * [OBD-II Power Cable](https://shop.autopi.io/products/obd-ii-power-cable?pr_prod_strat=jac&pr_rec_id=17052e989&pr_rec_pid=8619774050653&pr_ref_pid=8609919074653&pr_seq=uniform) - power the AutoPi CAN-FD Pro device with any 12-24 volt DC power supply.
    * [OBD-II Splitter Cable](https://shop.autopi.io/products/obd-ii-splitter-cable?pr_prod_strat=jac&pr_rec_id=70ef610e3&pr_rec_pid=8619777327453&pr_ref_pid=8619774050653&pr_seq=uniform) - use this Y-splitter cable if you need to connect an additional OBD-II device at the same time as your AutoPi CAN-FD Pro.
    * [Tesla OBD-II Adapter Cable for Model 3 and Y](https://shop.autopi.io/products/tesla-obd2-adapter-cable-for-model-3-and-y) - add an OBD-II port to your Tesla Model 3 or Model Y with this adapter cable.
    * [CAN Bus Testing/Loop Cable](https://shop.autopi.io/products/can-bus-testing-cable) - the CAN Bus Testing Cable is a cable designed for internal communication testing between two CAN bus systems.
    * [Micro USB-A Adapter Cable](https://shop.autopi.io/products/micro-usb-to-usb-a-adapter-cable)- this Micro USB to USB-A adapter cable is made to fit perfectly with the external Micro USB port on the AutoPi CAN-FD Pro device.
    * [OBD-II to dual DB9](https://shop.autopi.io/products/obd2-to-dual-db) - connect two CAN bus nodes to the OBD2 port of the AutoPi CAN-FD Pro.

### Tips on getting the best performance of your device:

- Make sure that the AutoPi logo is facing the sky.
- Antennas should also face the sky to ensure a strong signal. 
- Try to avoid installing the device in direct sun. Direct sun will heat up the device and,
  in the summertime, this can cause the CPU to throttle down, if the temperature gets too hot. 
- When powering the device, make sure you only power it through the OBD connector.
  The device cannot be powered through any of the other ports. 
- Proper installation makes all the difference in performance. Follow the steps above for correct device mounting.
- The device contains a GPS antenna inside. 
  Make sure there is no metal covering the device as this can affect its performance. 

## 7. Connect to WiFi

After installing your AutoPi device into the OBD port, you will need to connect it to the AutoPi Cloud.
To do this, you will temporarily use the device’s Wi-Fi hotspot. 

The hotspot is named autopi-XXXX, where "XXXX" represents the unique ID of your device.
The **password** for this Wi-Fi hotspot is the **first 13 characters of your Device ID**. 
You can find your Device ID either by navigating to Devices > Select your device > Overview: Device specifications; or in the documentation 
attached to your shipping email. 
Additionally, you can access Wi-Fi information directly from the AutoPi Cloud. 
To do this, navigate to Devices > Select Your Device > Advanced Settings > Wi-Fi. 
Here, you will find the Wi-Fi hotspot's password and SSID credentials. 
![Wifi settings](/img/getting_started/getting_started/wifi_settings.png)

When the device is powered on, a blue light will appear on the side, indicating 
that it has power. When the device successfully connects to the AutoPi Cloud, 
a green light will be visible. If the device is not connected, the light will be flashing. 

For a detailed description of the two status LEDs, please refer to the [LED and Button States on AutoPi CAN-FD Pro](https://docs.autopi.io/hardware/autopi_canfd_pro/pro-led-and-button/).

## 8. Connect to Local Administration

:::note
If you’ve purchased the AutoPi TMU CM4 with a monthly cloud subscription, your SIM card
is pre-installed in the device, and no additional action is required for SIM connectivity. 
The APN settings are already configured for you. Please be aware that the SIM card 
has a monthly data cap, so it's recommended to limit the use of the device’s hotspot 
for connecting your phone or notebook.
:::

:::note
If you need to know the APN string for the pre-installed SIM card, it is **nxt20.net**. 
:::

:::note
If you are using a **Verizon Wireless** SIM card, please follow the dedicated setup guide:
[Setting Up Your Device with Verizon Wireless](https://docs.autopi.io/developer_guides/setting-up-a-device-with-verizon-wireless/).
:::

If you are using your own SIM card, you may need to configure the APN settings after 
connecting to the device’s Wi-Fi hotspot to ensure a seamless 4G/LTE connection. 
However, setting up the APN is not always necessary—it depends on your SIM provider. 
We suggest checking with your SIM provider directly or searching online for the correct APN settings. 

Here’s how you configure the APN settings: 

1. Go to my.autopi.io. If you're already logged in, please log out. 
2. On the login page, find the “Go Local” button at the bottom left side, 
   or alternatively, go directly to local.autopi.io.

    

This will connect you to the local device, and you should see a screen similar to 
the one shown in the image below, indicating that you're connected locally.
From here, you can log in without needing a username or password.

![AutoPi.io - Localhost login](/img/getting_started/getting_started/local.jpg)

Once the information is saved, it will be applied to the device, and you should 
see a notification when successfully saved. 

4G/LTE Settings 
![AutoPi.io - Settings Page](/img/getting_started/getting_started/apn_settings.png)

APN Presets List 
![AutoPi.io - Settings Page](/img/getting_started/getting_started/apn_settings_list.png) 

## 9. Verify Connectivity

To verify that you have set up your APN settings correctly, connect your phone 
to the AutoPi hotspot and use your browser to visit any webpage. 
If the page loads successfully, it means your device is online and has 
started uploading data to the AutoPi Cloud.

## 10. Finalization

Your device is now online and connected to the AutoPi Cloud. After completing 
the setup, it's important to change your device's WiFi password. 
The default password is intended for one-time use only, and it is strongly 
recommended to update it afterward. You can change the password through the 
AutoPi Cloud by navigating to **Devices** > **Advanced Settings** > **Wi-Fi** > **Pass**. 

To prevent excessive data usage, it's advisable to avoid using the device’s 
hotspot to connect your phone or tablet after the initial configuration is complete. 

## 11. Set up Output Handlers 

Your device can capture data, but you’ll need to choose where that data should be sent, also known as configuring an output handler. Currently, the AutoPi CAN-FD Pro supports output to an Amazon AWS S3 bucket. Setting this up is quick and straightforward, just follow the step-by-step guide here: [Amazon Web Services (AWS) S3 Bucket Creation](https://docs.autopi.io/getting_started/autopi_canfd_pro/set_up_AWS_S3_bucket/).

## 12. Access Files Remotely on AutoPi

You can also view and manage your captured data remotely from your AutoPi device. For detailed instructions on how to access your files using SFTP or SCP, check out this guide: [Accessing files via SFTP/SCP on AutoPi](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/). 

:::note
Remember to adjust the **sleep timers** according to your needs. You can easily change these settings anytime by navigating to:
Advanced Settings → Power → Sleep Timer.

By default, the device enters sleep mode when it receives the event:
`^vehicle/battery/(discharging|unknown)`

Sleep is prevented when any of the following events are active:
`^vehicle/battery/(charging_slow|charging|overcharging)`

:::

**You Are All Set!**

Congratulations! You've successfully set up your AutoPi device and connected it 
to the AutoPi Cloud. Your device is now ready to start gathering and transmitting data,
enabling you to take full advantage of the powerful features AutoPi offers. 
Take your device for a trip to start gathering data.

---

**What's Next?**

Now that your device is up and running, here are a few suggestions to help you 
get the most out of your AutoPi experience: 
- **Read our User guide**: dive into the CAN-FD Pro device and all of its functionalities in our [User guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/). 
- **Explore the AutoPi [Cloud](https://docs.autopi.io/cloud/)**: Dive into the [AutoPi Cloud platform](https://my.autopi.io/) to explore all 
  the features available to you, such as real-time vehicle monitoring, 
  advanced analytics, and customizable alerts. 
- **Check Out Our Documentation**: Our [documentation page](https://docs.autopi.io/) 
  is a great resource for learning more about advanced features, troubleshooting, 
  and getting the most out of your device. 
- **Build your Nested Accounts and Invite New Users**: AutoPi Cloud uses a multi-tenant architecture, which means multiple accounts (tenants) share the same platform and infrastructure, while all data, configurations, and user access remain securely isolated. You can read more here: [Account management](https://docs.autopi.io/cloud/accounts/).

---

## Amazon Web Services (AWS) S3 Bucket Creation

---
This guide will walk you through on how to create an Amazon Web Services (AWS) S3 bucket. If you want your data from AutoPi CAN-FD Pro device to be uploaded to Amazon S3 bucket, you will need to create a AWS account and S3 bucket and configure the settings for Output handlers in AutoPi cloud. 

**Quick Start Summary:**
1. Create an Amazon Web Services account.
2. Create an S3 Bucket. 
3. Create users and assign permissions. 
3. Create Access key and secret key to access the S3 bucket (make sure to save it). 
4. Fill in Access Key ID, Access Secret Key and Destination Path under CAN Logger on AutoPi cloud. 

---
## What is AWS S3?

Amazon S3 (Simple Storage Service) is a cloud-based storage service offered by Amazon Web Services (AWS). An S3 bucket is essentially a container where you can store and organize files (called "objects") such as logs, images, videos, backups, and more.
Each bucket can hold an unlimited number of files and is accessible over the internet, making it ideal for securely storing and retrieving data from anywhere.

:::note
If you need help, this guide can also be helpful: [Getting started with AWS](https://aws.amazon.com/getting-started/).
:::
---

## AWS Bucket Creation

Follow the steps below to create AWS S3 bucket.

### Step 1: Create an Amazon Web Services (AWS) account

* Open this link to access: [Amazon's AWS portal](https://signin.aws.amazon.com/signup?request_type=register).
* Sign up: fill out your email address and AWS account name and click on "Verify email address".
* Verification code is included in the auto-generated email and send to the email address you provided; 
* To complete the sign up process you need to follow the instructions provided in the email and finish up 5 steps: choose your password, fill in your contact information, fill in your billing information, confirm your identity and lastly select a support plan. 

![Sign up for AWS](/img/getting_started/autopi_canfd_pro/aws_creation/sign_up.png)

:::note
Once the sign up process is finalized the "root user" is created as an account owner on AWS. Make sure this a correct user as it will allow the user to access all AWS services and resources in the account.
:::

### Step 2: Create a Bucket

* Sign in to your AWS account.
* Open S3 console by navigating to "Services" and choosing "Storage".
* Click on "Create bucket" in the upper right corner.

![Create bucket](/img/getting_started/autopi_canfd_pro/aws_creation/create_bucket.png)

* Fill in all required fields: Bucket name and AWS Region (if not already set).

![Fill out the bucket form](/img/getting_started/autopi_canfd_pro/aws_creation/create_bucket_form.png)

* Optionally copy settings from existing bucket.
* Click on "Create bucket" at the bottom of the page. 

![Save changes for creating bucket](/img/getting_started/autopi_canfd_pro/aws_creation/save_bucket.png)

* Once created, the bucket can be seen in the buckets list. 

![Buckets list](/img/getting_started/autopi_canfd_pro/aws_creation/buckets_list.png)

:::note
Enter a globally unique bucket name following AWS naming conventions. You can read more here: [General purpose bucket naming rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html?icmpid=docs_amazons3_console).
:::

:::tip
(Optional) Upload a Test File: Open your new bucket and click "Upload" to add a file or folder to verify the bucket is working correctly.
:::

---
## Access Key and Secret Key Creation
In order to allow your AutoPi CAN-FD Pro device to send data to your S3 bucket you need to generate and store IAM (Identity and Access Management) credentials. 

### Step 1: Create Users with Correct Permissions
* Sign in to an existing AWS account by clicling [here](https://eu-north-1.signin.aws.amazon.com/oauth?client_id=arn%3Aaws%3Asignin%3A%3A%3Aconsole%2Fcanvas&code_challenge=2X8Gz8x64bnC_u1PtIKJ2ho3L1pQzeV000fZ2yzsH_g&code_challenge_method=SHA-256&response_type=code&redirect_uri=https%3A%2F%2Fconsole.aws.amazon.com%2Fconsole%2Fhome%3FhashArgs%3D%2523%26isauthcode%3Dtrue%26state%3DhashArgsFromTB_eu-north-1_217c4b6452c80190).
* Open IAM console by navigating to Services > All services > IAM. 

![IAM Console](/img/getting_started/autopi_canfd_pro/aws_creation/iam_console.png)

* Under "Access management" click on "Users".
* Either select an existing IAM user or create a new one.
* (Optional) To create a new user: 
     * Click "Create user".
    ![IAM users](/img/getting_started/autopi_canfd_pro/aws_creation/create_user.png)

    * Assign a meaningful user name. 
    * Click "Next".
    * Assign permissions: 
        * Option A: Add the user to an already existing group with S3 access or create a new group; or copy permissions. 
        * Option B: Attach policies directly.
    * Click "Next". 
    * Click "Create user".
    * Your user was succesfully created and is now shown in the users list.
    ![New user created](/img/getting_started/autopi_canfd_pro/aws_creation/users_list.png)

### Step 2: Create Access Key
* Navigate to Users list and click on the user you want to create access keys for. The new window will open: 

![Security credentials](/img/getting_started/autopi_canfd_pro/aws_creation/security_credentials.png)

* Navigate to Security credentials and click Create access key: 

![Create access key](/img/getting_started/autopi_canfd_pro/aws_creation/create_key.png)

* "Access key best practises & alternatives" page is open, select "Other" at the bottom of the page.
* (Optional) Specify the description tag.
* Click on "Create access key".
* Your Access and Secure Access keys are generated.
* Copy your Access Key ID and Secret Access Key. 

:::warning
**Once the access key and the secret access keys are generated, copy and paste them to a secure location, as you can view the Secret access key only once.**
:::

---

## Uploading Data to AWS S3 Bucket from AutoPi CAN-FD Pro

The AutoPi CAN-FD Pro device supports two types of data logging:
* Raw data – captures everything exactly as received. 
* Decoded data – data is processed and translated before storing. 

By default, all data is logged and stored locally on the device. However, you can easily configure the device to upload your logged data directly to an AWS S3 bucket (both Raw data and Decoded data). Here’s how to do it:
* On your Pro device, go to: CAN Logging → Loggers.
* Create a new logger or edit an existing one.
* Navigate to Step 4: Outputs. This is where you define where the logged data should be sent. You can also read more here: [Output handler configuration explained](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/#step-4-outputs). 

![Output handler for S3](/img/getting_started/autopi_canfd_pro/aws_creation/channel_s3_bucket.png)

* To upload to AWS S3, fill in the following fields:
    * Access Key ID – your AWS access key.
    * Secret Access Key – your AWS secret key.
    * Destination Path – the URL of your S3 bucket (e.g., s3://your-bucket-name/folder)
* (Optional) Configure Advanced Settings:
    * Exclude Patterns – to filter out specific data
    * Sync Interval – how often the device syncs data
    * Error Retry Interval – wait time before retrying a failed upload
    * Job Timeout – how long to wait before canceling a sync job
* Save your settings.

Once saved, your device will begin uploading data to the specified S3 bucket based on the configuration you've chosen.

:::note 
You can read more about advanced settings for S3 upload process here: [Advanced settings for Output Handler](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/#advanced-settings-for-output-handler)
:::

---

## User guide

---

Our newest [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) device has some new features that are not available on our other devices. This guide will walk you through everything you need to know about the CAN Logging feature on our AutoPi CAN-FD Pro device. Whether you're setting up your first logger or exploring advanced options, we've made it easy to follow and fully customizable to suit your needs.
:::note
**CAN Logging** on the AutoPi CAN-FD Pro is different from the Loggers feature available on our other device [AutoPi TMU CM4](https://shop.autopi.io/products/autopi-telematics-unit-cm4-4g-lte-edition). 
:::

**What is CAN Logging?**
CAN Logging captures traffic from your vehicle’s CAN bus using two dedicated interfaces: can0 and can1. These logs can include raw or decoded data, depending on your configuration.

![CAN logging](/img/getting_started/autopi_canfd_pro/can_logging_tab.png)

**`logger.status` command**

This command is a great tool to see the current status of your data logger(s) in real time. You can run this command in 3 ways: 
* If the device is connected to the internet it can be done through the cloud terminal on AutoPi cloud.
* If you have direct SSH access to the device via LAN or VPN you can use the autopi terminal command.
  * You can check out this guide: [How to SSH to your device](https://docs.autopi.io/developer_guides/how-to-ssh-to-your-device/)
  * For using Tailscale, you can check out this guide: [How to connect to Tailscale](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/)
* If you are nearby the device and can connect to it's local WiFi hotspot you can do it from the local admin UI on local.autopi.io. Here is a guide: [Local development workflow](https://docs.autopi.io/developer_guides/local-development-workflow/)

Below is an example of the output of the command:
```python
channels:
  can0:
    interface:
      autodetect:
        in_progress: false
        last_results:
          any_passive:
            bitrate: 500000
            frames_per_second: 710
            has_11bit_identifiers: true
            has_29bit_identifiers: false
            performed_at: '2025-05-07T09:50:43.347462'
            success: true
      bitrate: 500000
    loggers:
      raw:
        current_fps: 584.95
        decoders:
          dbc:
            failed_messages_count: 140000
            output_file_pattern: /opt/autopi/can0/loggers/raw/decoders/dbc/output/{input:}.jsonl
            output_handlers:
            - destination_path: s3://my-datalogger/a1eeabbd-cffa-f7c4-31a5-49b2c2340d3d/can0/decoded
              uploaded_files_count: 2
            total_messages_count: 140000
            type: STANDARD
        output_file_pattern: /opt/autopi/can0/loggers/raw/output/{ts:%Y%m%d%H%M}.log
        output_handlers:
        - destination_path: s3://my-datalogger/a1eeabbd-cffa-f7c4-31a5-49b2c2340d3d/can0/raw
          uploaded_files_count: 2
        received_error_frames_count: 613
        received_frames_count: 111101
  can1:
    interface:
      autodetect:
        in_progress: false
        last_results:
          any_passive:
            bitrate: 500000
            frames_per_second: 544
            has_11bit_identifiers: true
            has_29bit_identifiers: false
            performed_at: '2025-05-07T09:50:44.198244'
            success: true
      bitrate: 500000
    loggers:
      raw:
        current_fps: 586.66
        decoders:
          dbc:
            output_file_pattern: /opt/autopi/can1/loggers/raw/decoders/dbc/output/{input:}.mf4
            total_messages_count: 0
            type: ASAMMDF
        output_file_pattern: /opt/autopi/can1/loggers/raw/output/{ts:%Y%m%d%H%M}.log
        received_error_frames_count: 613
        received_frames_count: 113725
disks:
  /:
    free_space: 3 GB
    housekeeper:
      deleted_files_count: 0
      total_space_freed: 0 bytes
```

---

## Channels
A channel is a pathway through which the device listens to or communicates on the CAN bus. Most vehicles have one or two CAN buses. The [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) supports two channels out of the box: **can0 and can1**.
CAN communication is based on an agreed bitrate (speed of the amount of data processed within one second). Think of it like tuning two radios to the same frequency—you need to match speeds to understand each other. If you don’t know the bitrate, [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) device has functionality to **Autodetect** to help you find the correct bitrate - by selecting one or more methods to detect the CAN bus and the active protocol(s). A passive method will only listen for broadcast traffic. An active method will attempt to send a request and then wait for a valid response. 

### How to Configure CAN Channels?
By default, can0 and can1 channels are preconfigured with standard values. But you can fully customize them. 

#### Opening the configuration of the CAN channel 
![Open configuration of the CAN channel](/img/getting_started/autopi_canfd_pro/configure_channel.png)

* Go to the Devices section.
* Click on the device you want to configure.
* Select the CAN Logging tab.
* Click on the channel you want to edit.
* Click the "Configure" button in the top-right corner.

#### Detailed description of steps to configuring/creating CAN channel
##### Step 1: Name & Description of the CAN channel
* **Name** the channel or update the existing name.
* Add a **description** to clarify its purpose.

![Name and description](/img/getting_started/autopi_canfd_pro/name_description.png)
      
##### Step 2: Enable or Disable CAN channel
* Use the checkbox to either **enable** or **disable** this channel. When disabled, CAN channel is not running and therefore not listening to CAN Bus. 

![Enabled channel](/img/getting_started/autopi_canfd_pro/user_guide/channel_enabled.png)

##### Step 3: Autodetect (How to find the correct bitrate)
* This is a way to detect the CAN Bus. Type of the CAN bus can different from vehicle to vehicle (with different bitrates (speed)). Therefore, we need to detect the correct type of CAN Bus but also find the correct bitrate before we can start recording data from the device. 
* Choose from three **detection strategies** to ensure there is data:
      * **Any (passive)** – Passively listens for CAN messages on the bus without actively sending any messages. This is set as default, as it is the safest strategy because you are just trying to find out if there is any activity on the bitrate.
      * **OBD (active)** – Sends an OBD-II PID request message and waits for a response to detect if the protocol is supported. If the response is received that means that the protocol is supported.
      * **J1939 (active)** – Sends a J1939 PGN request message and waits for a response to detect if the protocol is supported. If the response is received that means that the protocol is supported.

  ![Autodetect](/img/getting_started/autopi_canfd_pro/autodetect.png)

  :::warning 
  In some cases, the vehicle may produce MIL (malfunction indicator lamp) notifications on the dashboard when active strategies are used for protocols that are not supported by the vehicle.
  :::

Every time the Autodetection is used, it triggers an **events** that could be seen in the events section. This should help users to understand a little better what is happening on a device. These are some of the examples for the events: 
- `vehicle/bus/can0/autodetected`
- `vehicle/bus/can0/autodetect/any_passive/successful` 
- `vehicle/bus/can0/autodetect/any_passive/unsuccessful` 

##### Step 4: Try Bitrates or Use Fixed Bitrate
* As mentioned above, you need to find the correct bitrate for your vehicle. The deafult list for Try Bitrates includes some of the most common used bitrates to make this process easier for you. This step allows you to make sure that you can receive any data by listening to these settings. 
* You have 2 options here: 
  * **1. Try Bitrates (Auto Mode):**
      If you're unsure about your vehicle’s bitrate, this is the best choice.
        The device will automatically scan through a list of common CAN 2.0 and CAN FD bitrates.
        It opens one channel, listens for about a second, then tries the next—until it locks onto the right one, basically the device tries different bitrates until it finds the one that matches your vehicle.
![Try bitrates](/img/getting_started/autopi_canfd_pro/try_bitrates.png)

:::note
You can reorder the bitrate list and add your own based on your specific setup. Just use the 2 line icon on the left side.
:::

  * **2. Fixed Bitrate (Manual Mode):**
    Already know the exact bitrates for your CAN 2.0 and/or CAN FD? Just input them directly. This saves time and ensures consistent communication.
  ![Fixed bitrates](/img/getting_started/autopi_canfd_pro/fixed_bitrate.png)

##### Step 5: Advanced Channel Settings
![Advanced channel settings](/img/getting_started/autopi_canfd_pro/advanced_channel_settings.png)

Under **Advanced Settings** you’ll find a few more options for extra settings: 
* **Enable Termination** – Enables physical CAN bus termination of ~120 ohms for this channel. 
* **Allow Changing Interface** – Permit to make changes to the underlying CAN interface? This includes changing the bitrate and bringing the interface up and down etc. If disabled, the CAN interface will be used as is without any prior setup.
* **Allow Sending** – Permit sending of CAN frames for this channel. If disabled, an error will be returned when attempting to send a CAN message.
* **Receive Own Messages** – Allows the device to also listen to messages it sends (useful for testing/debugging).

---

## Loggers
Every channels can have one or multiple loggers set up. A CAN logger records all the CAN bus traffic detected through the can0 and can1 interfaces. This data can be raw or decoded, depending on how you configure the logger.

### How to create CAN Logger?
Setting up a CAN logger is easy and flexible. We’ve provided default values for most fields, but you can customize everything to match your specific requirements.

##### Step 1: General information
![General information](/img/getting_started/autopi_canfd_pro/general_information.png)

* Start by entering:
  * **Name** – the name you want to give to this logger.
  * **Description** (optional) –  helpful if you want to add details about the logger's purpose.
  * **Run At** - defines when this logger runs (e.g., at startup, on ignition on, on trip start or manually started).
  * **Use external dump process** - it is recommended to use the external dump process for improved performance.
  * **Worker Settings** (advanced) - 
    * **Interval** - you can specify the time period between reading out received CAN frames from the internal buffer.
    * **Start Delay** - amount of seconds before the worker starts execution.

##### Step 2: Filters 
Use filters to control which types of CAN frames are logged. This settings allow you to filter the type of data you want to be logged for your specific use case. 

:::note
  If you set up decoder for your CAN logger, the filters are automatically applied even tho they are not visible in this step. For this to work, it requires that it is enabled on the logger: `Automatically add pass filters for all DBC message identifiers`.  
  :::

**Scenario 1** - you have **enabled** the "Use external dump process" in the previous step and therefore your second step: Filters looks like this: 
![Filters with external dump enabled](/img/getting_started/autopi_canfd_pro/filters_externaldump_enabled.png)

Therefore in this step you can add any Pass and Block Filters: 
* **Add Pass Filter** - only CAN frames with identifiers that match a pass filter will be included. To add a new pass filter, you'll need to specify the identifier bit length, ID, and a mask. 

* **Add Block Filter** - only CAN frames with identifiers that match a block filter will be excluded. To add a new block filter, you'll need to specify the identifier bit length, ID, and a mask.

**Scenario 2** - you have **disabled** the "Use external dump process" in the previous step and therefore your second step: Filters looks like this:
![Filters with external dump disabled](/img/getting_started/autopi_canfd_pro/filters_externaldump_disabled.png)

Therefore in this step you can specify Allowed frame types and allowed identifier bits as well as add any Pass Filters: 
* **Allowed Frame Types** - choose from normal, error, and remote frames (all of the CAN messages has at least one of these frames). 
* **Allowed Identifier Bits** - supports both 11-bit (standard) and 29-bit (extended) identifiers. 
* **Add Pass Filters** (optional) - only CAN frames that match these filters will be logged.
    * To add a new filter, you'll need to specify the identifier bit length, ID, and a mask.

:::warning
If you don't know anything about a bit masking, it is better to use the default value inside the Pass Filters (there are different default values for 11 bit and 29 bits). 
:::

##### Step 3: Decoders
This step allows you to decode (translate) raw CAN data using Standard decoder or ASAM decoder. This step doesn't come up with pre-set default values, as this is fully customizable for user. Once you import a DBC file, you can set up some additional settings in order for your device to be able to decode the data based on your requirements. 

**How to setup decoding for your device?**

Follow these steps to configure CAN data decoding:
* Go to your Device and navigate to CAN Logging tab.
* Create a new logger or edit an existing one.
* Navigate to Step 3: Decoders.
* Select the decoder type you want to use (Standard or ASAM).
* Import your DBC file.
  * After importing the DBC file, select only the signals you want to decode from the list. This allows you to pick specific signals without needing to modify or split the DBC file.
  * Once the data is decoded, it can be accessed either locally on the device, or via an Amazon S3 bucket, depending on how you have configured the Outputs.

![Import DBC file](/img/getting_started/autopi_canfd_pro/user_guide/import_dbc.png)

AutoPi CAN-FD Pro supports **2 types** of decoders: 
1. Standard decoder - Using the standard decoder is faster than ASAM. Supported formats are CSV, JSONL and LOG. 
2. ASAM Decoder - The ASAM decoder is slower than the standard. Supported format is MDF4 - a binary file format for recording e.g. CAN and CAN FD data.
![Types of decoders](/img/getting_started/autopi_canfd_pro/decoders_type.png)

  **Option 1: Add Standard decoder** 

  ![Standard decoder](/img/getting_started/autopi_canfd_pro/standard_decoder.png)

    * **Decoder Name** - name your decoder.
    * **DBC Collection** - select the desired DBC file from the dropdown or use "Import" button to import a new file.
    * **Frame ID Mask** (optional) - help you determine how much needs to match before you have a match.
    * **Automatically add pass filters for all DBC message identifiers** (optional) - this setting adds pass filters to the logger for all the selected CAN messages in the DBC file. This way, only those messages that can be decoded are logged.
    * **Library File Path Pattern** (advanced) - the path to the message definition library file used for decoding the raw CAN messages.
    * **Strict mode** (advanced) - prohibits overlapping fields / multiplexing when rendering DBC file.
    
    After you **choose or import the DBC file** you are able to set up the CAN messages and signals based on your preference. After you validate the file, you will be presented with the list of CAN messages and signals. You can decide if you want to create or ignore the specific message or signal. If you create one that was already created, it will be updated. 

    Once you select the signal(s) you want to decode, you can configure the **aggregation interval** for each signal. The aggregation interval, measured in seconds, defines a time window during which all collected signal data is aggregated into a single averaged value before logging. For example, if you set an aggregation interval of 1 second, the system will collect all data points within that second, calculate their average, and log this result. When creating widgets in the AutoPi dashboard, you gain access to four distinct data representations for each signal: the **aggregated signal** (average), **maximum value**, **minimum value**, and **sample count** (the total number of data points collected within your specified aggregation interval). This flexibility allows you to create comprehensive visualizations tailored to your monitoring needs.

    There is also one important technical value that needs to be set correctly: **Frame ID Mask**. Frame ID Mask is a bitmask used to match the CAN message identifiers defined in the DBC file. **If this value is incorrect, no CAN messages will be decoded. For the J1939 protocol the recommended bitmask is ´1FFFFF00´.**

  **Option 2: Add ASAM decoder** 

    ![ASAM decoder](/img/getting_started/autopi_canfd_pro/asam_decoder.png)

    * **Decoder name** - name your decoder.
    * **DBC Collection** - select the desired DBC file from the dropdown or use "Import" button to import a new file.
    * **Automatically add pass filters for all DBC message identifiers** (optional) - this setting adds pass filters to the logger for all the selected CAN messages in the DBC file. This way, only those messages that can be decoded are logged.
    * **Library File Path Pattern** (advanced) - the path to the message definition library file used for decoding the raw CAN messages.
    * **Strict mode** (advanced) - prohibits overlapping fields / multiplexing when rendering DBC file.

    After you **choose or import the DBC file** you are able to set up the CAN messages and signals based on your preference. After you validate the file, you will be presented with the list of CAN messages and signals. You can decide if you want to create or ignore the specific message or signal. If you create one that was already created, it will be updated. There is also one important technical value that needs to be set correctly: Frame ID Mask. Frame ID Mask will help you determine how much needs to match before you have a match.

##### Step 4: Outputs
This step represent the settings for the output of your data. You can choose where do you want the data to be transferred to, and adjust the settings. At the moment we support upload to AWS S3 bucket but data are also stored locally on a device. 

Read more here: **[How to set up AWS S3 bucket](https://docs.autopi.io/getting_started/autopi_canfd_pro/set_up_AWS_S3_bucket).**

At the moment [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) is capable of getting data in 2 formats: Raw data - everything is logged; and Decoded data - data is translated before being transferred. Within both of these formats, data are logged and accessible locally on a device or could be set up to be transfered to a S3 bucket (read more below). 

![Output types](/img/getting_started/autopi_canfd_pro/outputs_types.png)

**Option 1: Raw data** 
**Raw data accessible locally on the device** - raw data are logged on a local disk. Logger will always log to local disk first (not possible to disable) before transferring the data to any other output. When Local Disk is running full, Disk Housekeeper is deleting these files (starting with the oldest) to free up the memory. 

  * You can however configure these settings: 
    ![Raw data accessible locally](/img/getting_started/autopi_canfd_pro/raw_local.png)

    * **Folder Pattern** - Local folder where the output files containing raw CAN frames are saved to. 
    * **File Name Pattern** - The format string used to name the output files in a consistent manner. Raw files will be named with using this pattern. This patern includes the timestamp (year, month, day, hour, minute), and therefore every time new file is made it has the timestamp as a name. 
    * **File Format** - by default it is set to log file, however we offer a different file formats to pick from: asc, blf, csv, db and jsonl. However, there are less formats available when external dump is enabled. 
    * **Max File Size Rollover Trigger** - The maximum allowed size before rollover of the output file. In order to avoid having big files, the default size is set - this is a recommended step. 
    * **Max File Age Rollover Trigger** - The maximum allowed age before rollover of the output file.

  :::note
  If you want to access the files through the wifi hotspot, you can follow this guide: [Accessing files via SFTP/SCP on AutoPi CAN-FD Pro device](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/). 
  :::

       
**Raw data accessible through Amazon S3 bucket** - raw data will be transferred and uploaded to a S3 bucket. 
  * Settings for setting up AWS S3 bucket: 
    ![Raw data accessible through AWS S3](/img/getting_started/autopi_canfd_pro/raw_s3.png)

    * **Access Key ID** - access key ID of AWS account to be used.
    * **Access Secret Key** - access secret key for the AWS account.
    * **Destination Path** - URL path to the S3 bucket container for storing output files. 
    * **Exclude Patterns** (advanced)- rule patterns used to exclude specific files or directories.
    * **Sync Interval** (advanced)- time gap between each sync operation, specifying how often files should be synchronized automatically.
    * **Error Retry Interval** (advanced)- period of time in seconds that the handler waits before retrying an operation after encountering an error.
    * **Job Timeout** (advanced) - maximum duration allowed for the output handler task to run before it is automatically terminated.

**Option 2: Decoded data**

**Decoded data accessible locally on a device** - decoded data are also stored on a local disk. Logger will always log to local disk first (not possible to disable). When Disk is running full, Disk Housekeeper is deleting these files (starting with the oldest). 
  * You can however configure these settings: 
    ![Decoded data accessible locally](/img/getting_started/autopi_canfd_pro/decoded_local.png)

    * **Folder Pattern** - local folder where the output files containing raw CAN frames are saved to. 
    * **File Name Pattern** - the format string used to name the output files in a consistent manner. Decoded files will be named with using this pattern. This patern includes the timestamp (year, month, day, hour, minute), and therefore every time new file is made it has the timestamp as a name. 
    * **File Format** - by default it is set to mdf4. 
    * **Worker Interval** (advanced) - time period between reading out received CAN frames from the internal buffer.
    * **Rollover Message Limit** (advanced) - the amount of decoded CAN messages before performing rollover of the output file.
    * **Duration Limit** (advanced) 
    * **Message Limit** (advanced)  
    * **Ignore "Message Not Found" in Error File** (advanced) - exclude message in error file when a CAN message is not found in the DBC file?
    * **Include stacktrace in Error File** (advanced) - also include stackstrace in the error file when decoding of a CAN message fails?

  :::note
  If you want to access the files through the wifi hotspot, you can follow this guide: [Accessing files via SFTP/SCP on AutoPi CAN-FD Pro device](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/). 
   :::

**Decoded data accessible through Amazon AWS S3 bucket** - decoded data will be uploaded to a S3 bucket. 
  * Settings that you need to set up for device to be able to upload the data to S3 bucket are these: 
    ![Decoded data accessible through AWS S3](/img/getting_started/autopi_canfd_pro/decoded_s3.png)
    * **Access Key ID** - access key ID of AWS account to be used.
    * **Access Secret Key** - access secret key for the AWS account.
    * **Destination Path** - URL path to the S3 bucket container for storing output files. 
    * **Exclude Patterns** (advanced)- rule patterns used to exclude specific files or directories. Put a comma seperated list or type and press enter to confirm individual strings.
    * **Sync Interval** (advanced) - time gap between each sync operation, specifying how often files should be synchronized automatically.
    * **Error Retry Interval** (advanced)- period of time in seconds that the handler waits before retrying an operation after encountering an error.
    * **Job Timeout** (advanced) - maximum duration allowed for the output handler task to run before it is automatically terminated.

**Decoded data accessible through Cloud Storage (HTTPS)** - decoded data can be streamed directly to the AutoPi Cloud, enabling seamless integration with AutoPi dashboards and widget creation. To use this output type, ensure you have selected the Standard decoder in Step 3: Decoders. Once configured, you can add a **Cloud Storage** decoded output in this step. The upload frequency for each signal is determined by the aggregation interval set for that signal in the Decoders ste. No additional settings are required.

![Decoded data accessible through Cloud Storage](/img/getting_started/autopi_canfd_pro/user_guide/cloud_returner_pro.png)

### How to edit CAN Logger?
Need to make changes to a CAN logger? No problem, it’s super simple. Just follow these steps:
* Go to the Devices section in the menu.
* Select the device you want to work with.
* Click on CAN Logging tab.
* Under Loggers, find the specific logger you’d like to edit.
* Click the three dots icon in the top-right corner of that logger.
* From the dropdown menu, select Edit.
  ![Editing logger](/img/getting_started/autopi_canfd_pro/editing_logger.png)
* Make your changes and save when you’re done.

---

## Queries
Queries allow the vehicle to request specific data points at a defined frequency. You can configure an interval that determines how often the vehicle should ask for and retrieve this data.

### How to create Query?
AutoPi CAN-FD Pro is supporting creation of different types of queries, including: 
* OBD-II PID 
* J1939 PGN 
* Raw

#### Create OBD-II PID Query 
![Create OBD-II PID Query](/img/getting_started/autopi_canfd_pro/queries_create_obd.png)

*Basic information:* 
* **Name** - name your query. 
* **Collection** (optional) - assign this query to a collection to keep related queries organized.
* **Description** (optional) - helpful if you want to add details about query specifications.

*Request specifications*
* **PID** - OBD-II Parameter ID
* **Interval** - amount of seconds between requests.
* **Run At** (advanced) - defines when this query runs (on startup, on ignition on, on trip start or manually). 
* **Start Delay** (advanced) - amount of seconds before executing a query.
* **Loop Count** (advanced) - number of times this query will execute before stopping. Set `-1` for unlimited loops.
* **Group** (advanced) - logical group that schedules queries sharing the same execution interval.

*Response specifications*
* **Converter** (advanced) - applies a transformation to the query response.
* **Triggers** (advanced) - specify one or more triggers that fire events based on the query response or converter result, if specified.
* **Filter** (advanced) - a filter can discard unwanted results.
* **Returners** - especify one or more returners that deliver results to other systems or services.

#### Create J1939 PGN Query

![Create J1939 PGN Query](/img/getting_started/autopi_canfd_pro/queries_create_j1939.png)

*Basic information:* 
* **Name** - name your query. 
* **Collection** (optional) - assign this query to a collection to keep related queries organized.
* **Description** (optional) - helpful if you want to add details about query specifications.

*Request specifications*
* **PGN** - identifier of the J1939 message (Parameter Group Number). 
* **Interval** - amount of seconds between requests.
* **Run At** (advanced) - defines when this query runs (on startup, on ignition on, on trip start or manually). 
* **Start Delay** (advanced) - amount of seconds before executing a query.
* **Loop Count** (advanced) - number of times this query will execute before stopping. Set `-1` for unlimited loops.
* **Group** (advanced) - logical group that schedules queries sharing the same execution interval.

*Response specifications*
* **Converter** (advanced) - applies a transformation to the query response.
* **Triggers** (advanced) - specify one or more triggers that fire events based on the query response or converter result, if specified.
* **Filter** (advanced) - a filter can discard unwanted results.
* **Returners** - specify one or more returners that deliver results to other systems or services.

#### Create Raw Query

![Create Raw Query](/img/getting_started/autopi_canfd_pro/queries_create_raw.png)

*Basic information:* 
* **Name** - name your query. 
* **Collection** (optional) - assign this query to a collection to keep related queries organized.
* **Description** (optional) - helpful if you want to add details about query specifications.

*Request specifications*
* Choose between 2 CAN protocols: 
  * **CAN 2.0 (Standard)** 
  * **CAN FD (Extended)**
* **Interval** - amount of seconds between requests.
* **Group** (optional) - logical group that schedules queries sharing the same execution interval.
* **Run At** (advanced) - defines when this query runs (on startup, on ignition on, on trip start or manually). 
* **Start Delay** (advanced) - amount of seconds before executing a query.
* **Loop Count** (advanced) - number of times this query will execute before stopping. Set `-1` for unlimited loops.

*Response specifications*
* **Receive Frames** (optional) - the specific amount of reply frames to wait for within the timeout period.
  * **Skip Error Frames** (advanced) 
  * **Skip Remote Frames** (advanced)
* **Receive Timeout** - the amount of time in seconds to wait for a reply frame.
* **Verification** (optional) - raise an error when no reply frames are received or if the amount of expected reply messages is not met within the timeout.
* **Pass Filters** (advanced) - list of pass filters to use for receiving reply frames.
* **Flow Control** (advanced) - list of flow control ID resolvers to enable. Options are 'OBD' and 'Custom'.
* **Result Formula** - python code that decodes the raw byte data to a value.
* **Converter** (advanced) - applies a transformation to the query response.
* **Triggers** (advanced) - specify one or more triggers that fire events based on the query response or converter result, if specified.
* **Filter** (advanced) - a filter can discard unwanted results.
* **Returners** - specify one or more returners that deliver results to other systems or services.

---

## Frame Listeners

The Frame Listeners are a feature that reacts to incoming CAN messages and allows you to define custom matching rules either based on frame data or Python expressions. When a match occurs, it can trigger an event or execute a custom worfklow.
Frame listeners are highly customizable, giving you control over how CAN messages are processed.

### How to create Frame Listener? 

![Create Frame Listener](/img/getting_started/autopi_canfd_pro/create_frame_listener.png)

*Matching part:*
* **ID Bits** - pick between 11 and 29 bits. 
* **ID** - arbitration ID to match against incoming frames.
* **Mask** - bitmask that determines whether there is a match with the specified arbitration ID. Used to match ranges or groups of IDs.
* **Also Match on Frame Data** - where you would need to specify **Data** (value to match against the data part of incoming frames) and **Data Mask** (bitmask that determines whether there is a match with the specified data value). 
* **Also Match on Python Expression** - python expression which is evaluated to determine if there is a match.

*Output part:*
* **Trigger Event** - trigger an event when a match occurs. You can also specify the **Event interval** to further specify the minimum frequency in seconds at which workflow execution is performed.
* **Perform Action** - specify one or more workflows to perform on a match.

**Example Use Case**
Imagine your AutoPi CAN-FD Pro is configured to collect only a limited set of data parameters at a low frequency (for example, once per hour). If a specific error message appears on the CAN bus, you can use a frame listener to react immediately.
In this scenario, the frame listener detects the error message and triggers a custom action such as increasing logging frequency or enabling additional loggers. This allows you to capture more detailed data around the issue, making it much easier to investigate and identify the root cause.

---

## Event Reactors
Event Reactors enable the system to react to incoming data by executing custom actions. For example, they can run a command when the device starts logging data or trigger any custom code based on defined conditions.

### How to create Event Reactor?

![Create Event Reactor](/img/getting_started/autopi_canfd_pro/create_event_reactor.png)

* **Add Event Reactor**
  *  **Description** (optional) - helpful if you want to add details about event reactor specifications.
* **Match Event Tag** - regular expression to match on an event tag.
* **Match on Conditions** (optional)- specify additional conditions that must all be met for a match to occur.
  * **Keyword resolve** - enable resolving of keywords specified in conditions. Examples of keywords are: `$context, $event, $match, $options and $salt`. 
* **Perform Action on Match** - specify one or more workflows to perform on a match (such as handler, converter, trigger, filter, returner). 

:::note
Make sure you create the Workflow hooks before selecting the Event Reactor. If no hooks exist, the dropdown will be empty and you won’t be able to select one at this step.
If that happens, you can still save your changes and come back later to edit and complete the configuration.
:::

### Common event types and examples 
The Events functionality provides a historical overview of what has been happening on a device over time. Events capture important system and vehicle activities, giving you deeper insight into the device’s behavior and status.
To view events, navigate to your Device and open the **Events tab**. From there, you can see the full event history and easily filter the results by a specific timeframe or by event tags to focus on what matters most.

:::note
You can find a complete list of available events and detailed descriptions in our documentation: [AutoPi CAN-FD Pro events](https://docs.autopi.io/cloud/device_management/events/cloud-events-vehicle/#battery-events).
:::

Some examples of commonly used events include:
* Battery events: 
  * For example when the battery voltage has reached a critically low level: `vehicle/battery/critical_level`
* Battery Nominal Voltage events: 
  * For example when the AutoPi device was able to autodetect the battery nominal voltage: `vehicle/battery/nominal_voltage/autodetected`
* CAN Logging Events: 
  * For example when a logger is writing raw CAN frames to an output file: `vehicle/bus/<can0|can1|...>/logger/<logger_name>/writing`
  * For example when an AWS S3 sync job has finished with success: `vehicle/bus/<can0|can1|...>/logger/<logger_name>/s3_sync/completed`
* Position events
  * For example when the vehicle's current position is not confirmed: `vehicle/position/unknown`
* Motion events
  * For example when the accelerometer readings detected a sudden jolt in the device: `vehicle/motion/jolting`

![Example of Pro device events](/img/getting_started/autopi_canfd_pro/user_guide/pro_events.png)

---

## Workflow Hooks
Workflow Hooks define reusable logic that can be attached to workflows to process, modify, or react to data at specific stages. They act as building blocks that encapsulate commands, custom code, and configuration, making workflows modular and easier to maintain.

Each Workflow Hook has a defined type (handler, converter, trigger, filter, enricher, or returner) that determines its role in the workflow, along with a function (execution module) to be called. Optional arguments (args and kwargs) can be provided to customize how the function is executed.

### How to create Workflow Hook?

![Create Workflow Hook](/img/getting_started/autopi_canfd_pro/create_workflow_hook.png)

*Basic information*
* **Name** - name your workflow hook. 
* **Description** (optional) - helpful if you want to add details about hook specifications.

*Defining the type of the worflow hook* 
* **Type** - specify the type of workflow hook, you can pick from: handler, converter, trigger, filter, enricher and returner. 
  ![Workflow hook types](/img/getting_started/autopi_canfd_pro/workflow_hook_type.png)
* **Function** - refers to the command aka execution module to be called. Custom execution modules can be defined via custom code.
* **Args** (optional) - positional arguments passed to the command.
* **Kwargs** (optional) - keyword arguments passed to the command.

---

## Advanced settings
Our newest [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) device has some additional advanced settings that can be modified. These settings are namely: Can Logging (only available for [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) ) and Tailscale (available not only for [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) but also for [AutoPi TMU CM4](https://shop.autopi.io/products/autopi-telematics-unit-cm4-4g-lte-edition)). 

### Advanced settings for Disk Housekeeper
Steps to get into advanced settings for disk housekeeper:
* Go to the Devices section in the menu.
* Select the device you want to work with.
* Click on Advanced settings.
* Click on Can Logging. 

![Advanced settings for Disk Housekeeper](/img/getting_started/autopi_canfd_pro/user_guide/disk_housekeeper.png)

Settings for disk housekeeper: 
* **Critical use limit** - this setting allows you to set an event based on critical use limit (user customizable). Disk usage percentage that is considered critical and which causes an event to be triggered.
* **Enabled** - this settings allows you to enable Disk Housekeeper, that prevents your disk from running full with old files. By clicking on True, you enable automatic disk cleanup to prevent the disk from running full. The oldest files will be deleted first.
* **Use limit** - disk usage percentage which is the limit for when file deletion should begin. This means that when this limit is hit or exceeded, the housekeeper starts to clean up and then it cleans up until it reaches 85% (to reach the Use Target - customizable in the setting below). And in order for you to not loose data, it takes always the oldest files first.
* **Use target** - disk usage percentage which is the target to reach when deleting files.
* **Worker delay** - represents delay after startup of the device before performing the first check for files to cleanup. This simply means that after device is woken up, it does all the neccesary functions first and Disk housekeeper is delayed by default by 60 seconds to give device enough time to postpone to a little later, the better for the performance and start up time.
* **Worker interval** - represent time period between each check for files to cleanup.

Every time the Disk Housekeeper deletes anything, it triggers an event that could be seen in the events section. This should help users to understand a little better what is happening on a device. We have 2 events: 
* `system/disk_housekeeper/ordinary_purge` - this event is triggered when it reaches ordinary limits (customizable in the advanced settings).
* `system/disk_housekeeper/critical_purge` - this event is triggered when it reaches critical limits (customizable in the advanced settings).

For more details, see [Core Commands: Disk Housekeeper](https://docs.autopi.io/core/commands/core-commands-disk-housekeeper/). This handler automatically deletes the oldest files when disk space is running full.

### Advanced settings for Output Handler 
Steps to get into advanced settings for output handler: 
* Go to the Devices section in the menu.
* Select the device you want to work with.
* Click on Advanced settings.
* Click on Can Logging. 

![Advanced settings for Output Handler](/img/getting_started/autopi_canfd_pro/user_guide/output_handler.png)

At the moment if you want to use [AWS S3 Cloud storage](https://aws.amazon.com/free/?trk=b45f363b-5d02-4b3f-87df-b7b1908ff05c&sc_channel=ps&ef_id=CjwKCAjwktO_BhBrEiwAV70jXi39jOGqTVzMppg3DxhsoIWS-bbtstEGVIVceNP95c9u0Id1n_q5XBoCGkMQAvD_BwE:G:s&s_kwcid=AL!4422!3!536452769228!e!!g!!aws%20s3!12198535626!120978772550&trk=b45f363b-5d02-4b3f-87df-b7b1908ff05c&sc_channel=ps&targetid=kwd-20982008831&gclid=CjwKCAjwktO_BhBrEiwAV70jXi39jOGqTVzMppg3DxhsoIWS-bbtstEGVIVceNP95c9u0Id1n_q5XBoCGkMQAvD_BwE&all-free-tier.sort-by=item.additionalFields.SortRank&all-free-tier.sort-order=asc&awsf.Free%20Tier%20Types=*all&awsf.Free%20Tier%20Categories=*all) as an output handler, you will need to fill out these fields: 
* **Worker delay** - delay after startup before executing of the AWS S3 sync process.
* **Worker interval** - time period between each check of the executing AWS S3 sync process. Checking the upload job by default every 10 seconds, making sure the files are uploaded. If the job is hanging, it will close it, to ensure you won't loose any data.

### Advanced settings for Tailscale
Steps to get into advanced settings for Tailscale: 
* Go to the Devices section in the menu.
* Select the device you want to work with.
* Click on Advanced settings.
* Click on Tailscale. 

![Advanced settings for Tailscale](/img/getting_started/autopi_canfd_pro/user_guide/tailscale_settings.png)

At the moment if you want to access your device remotely using [Tailscale](https://tailscale.com/) you will need to configure these fields: 
* **Auth Key** - Specify the Tailscale auth key to be used by the device. Generate a new key on the Tailscale console below 'Settings' > 'Keys'.
* **Enabled** - by default this setting is not enabled, but if you want to use Tailscale, you just have to enable it here. 

For more information check out this guide: [How to connect to Tailscale on your AutoPi device](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/)

### Advanced settings for Trips
The Trips feature provides detailed information about each vehicle trip, including the route displayed on a map, start and end addresses, trip duration, and distance traveled. You can also categorize trips as personal or business and export trip data when needed. For your AutoPi CAN-FD Pro device you can also tweak some extra settings under Advanced settings -> Trip. 

#### Enable trip functionality
Steps to get into advanced settings for trips: 
* Go to the Devices section in the menu.
* Select the device you want to work with.
* Click on Advanced settings.
* Click on Trip.
* Set Trip Logic Version to Improved (This is our enhanced trip detection logic, designed to provide more accurate trip mapping.).
* (Optional) Configure custom start and end event tags for your vehicle. We provide preset primary and secondary events, but if trip detection is not working correctly for your vehicle, you can modify these events to better match your use case.

![Advanced settings for Trip](/img/getting_started/autopi_canfd_pro/user_guide/advanced_settings_trip.png)

### Advanced settings for Vehicle 
Under this tab, the AutoPi CAN-FD Pro device allows you to tweak some extra settings for Ignition Event and Trip Event. 

![Advanced settings for Vehicle](/img/getting_started/autopi_canfd_pro/user_guide/advanced_settings_vehicle.png)

In the Trip Event section: 
* Under Sources, select which data source should be used to trigger trip start and stop events.
* Adjust the Transition to Start and Transition to Stop settings to fine-tune how trips are detected.

These settings allow you to control exactly when a trip is considered active, ensuring that CAN data logging starts and stops at the appropriate times.

---

## Getting started(3)

---

Need a device that can handle tough environments? The [AutoPi](https://www.autopi.io/) [CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro) is packed into a durable, IP67-rated aluminum casing — built to withstand dust, dirt, and water, making it perfect for rugged, outdoor, or industrial installations. This step-by-step guide will help you get started with your new device. The device comes pre-assembled with the SD card inside and requires just a few steps to complete the installation.

:::note
**Important Notes Before You Start**

The AutoPi Telematics Unit is a highly customizeable and technical device. It contains a direct
interface to your car and communicates with the ECU in your car.

1. **Power Off the Vehicle**: When inserting the device for the first time, ensure that the vehicle is powered off.
2. **Vehicle Must Be Parked**: When working on and customizing your device, make sure your vehicle is in the parked position.
3. **Do Not Remove the AutoPi While Driving.**
4. **Power Source**: The device can only be powered through the OBD-II port.
     Powering the Raspberry Pi directly is not supported and may cause issues.
5. **Advanced Settings Caution**: When updating the Advanced settings, ensure you understand what you
     are doing, as changes can affect the performance of your car and its battery.  
:::

## [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) Quick Start Summary
* Step 1: Set up your account on [AutoPi Cloud](https://my.autopi.io/), you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#1-setting-up-user-account).
* Step 2: Register your device on [AutoPi Cloud](https://my.autopi.io/), you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#2-register-your-device). 
* Step 3: SIM card installation (if you did not purchased one from us), you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#3-ensure-sim-connectivity).
* Step 4: Attach the External Antenna Kit to your AutoPi CAN-FD Pro device, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#4-attach-the-external-antenna-kit).
* Step 5: Locate an OBD port in your vehicle/equipment, you can read more about tips and tricks [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#5-locate-obd-port).
* Step 6: Device installation to your vehicle's OBD-II port, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#6-installation).
* Step 7: Connect your device to the [AutoPi Cloud](https://my.autopi.io/), you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#7-connect-to-wifi). 
* Step 8: Connect to Local Administration on your device, and set up APN User and MTU, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#8-connect-to-local-administration). 
* Step 9: Verify connectivity to ensure your APN setting is set properly, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#9-verify-connectivity). This setting is only for users using their own SIM card, if you have purchased a device with AutoPi SIM, you can skip this step. 
* Step 10: Change your password, you can read more [in this section](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/#10-finalization).
* Step 11: Set up output handlers for data (where do you want the captured data to be send to), you can read more [in this guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/#step-4-outputs).
* Step 12: Access the files remotely, you can read more [in this guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/).

---
## Getting started
This step-by-step guide will help you set up your AutoPi CAN-FD Pro with the IP67 casing.

## 1. Setting Up User Account

Once you have received your AutoPi device it is important to associate it with Cloud Platform.
Go to [my.autopi.io](https://my.autopi.io/) and click “Sign up”. In the pop-up, 
add the e-mail address you want to associate with your account and create a password. 
You can also expand the form to add additional details like your country and full name, 
though this can be done later. Click “Create account”.

![AutoPi sign up](/img/getting_started/getting_started/sign_up.png)

## 2. Register Your Device

After creating an account, you can access the Cloud Platform features for fleet and device management.
The next step is to register your device to unlock the platform’s full potential.  

To add a device to your account, follow one of these methods:  

**Option 1: Via Device Management**
1. See the “Device Management” section of the Platform. 
2. Click on “Devices”. 
3. Find and click the “Register Device” button in the upper right corner. 

**Option 2: Via the Accounts Tab**
1. Navigate to the “Accounts” tab at the bottom of the left side menu on the Platform.
2. Select “Devices”. 
3. Locate and click the “Register Device” button in the upper right corner.

After clicking the “Register Device” button, the registration tab will appear. Enter all necessary information: 

![Register Device](/img/getting_started/getting_started/register_new_device.png)

- **Unit ID**: This is the number on the side of your casing. You can also find it in the document attached in the email you received when the device was shipped. 
- **Vehicle Information**: Optionally include the make, model and year of the vehicle.
- **Vehicle Type**: Choose the type of vehicle (ICE, Battery [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini), Hybrid [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini), or Plug-in Hybrid [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini)).

Once all information is entered, click the “Register Device”. Your newly registered device 
will now appear in the list under “Vehicles” in the Fleet Management section and under 
“Devices” in the Device Management section of the Platform.

## 3. Ensure SIM Connectivity

:::note
If you have purchased the AutoPi TMU CM4 with monthly cloud subscription, 
your SIM card is already assembled in the device, so you can skip this step. 
:::

If you have purchased the hardware-only version, you will need to insert your SIM card 
into your AutoPi before connecting the device to your vehicle. The AutoPi uses nano SIM sizes. Getting your SIM card in place is quick and easy:
Simply open the device’s casing and insert the SIM card as shown in the picture below. 

![Sim card](/img/getting_started/getting_started/sim_pro.jpeg)

When inserting the SIM card, it’s important to ensure it is installed correctly. 
The picture below shows the proper orientation of the SIM card. 
Please note that the text side of the SIM card must face up and the “triangle” end point into the device. 

![Sim card positioning](/img/getting_started/getting_started/simcard_direction.jpeg)

:::caution
**Please notice:** When the SIM card is inserted correctly, you will hear a small "click" when the
card is in position. Don't try do force the SIM out after the click as this will damage the device.
Make sure the orientation is correct before inserting the SIM. Wrong orientation could potentially
damage your device.
:::

:::caution
**Please notice:** The SIM card needs to be compatible with ipv4, for the device to establish a 4g/LTE connection. 
:::

Here's a list of the US based SIM providers that we recommend to be used with the AutoPi:
1. AT&T
2. T-Mobile
3. Any MVNO provider that is roaming the networks of the providers above

## 4. Attach the External Antenna Kit

Each device comes with a labeled sticker showing which antenna connects to each port, making installation simple and error-free. This guide will walk you through the process step by step.

Your AutoPi CAN-FD Pro comes with the following antennas:
* 2 × 4G antennas
* 1 × GPS antenna
* 1 × Wi-Fi antenna

![AutoPi CAN-FD Pro](/img/hardware/autopi_canfd_pro/canfd_pro_casing_measurements.png)

As shown in the image above, when the AutoPi logo is facing upward, the antenna ports are arranged as follows:
* Right side (top to bottom): 4G, GPS, 4G.
* Left side (top to bottom): Wi-Fi.

To attach the antennas, gently screw each one into its corresponding port by hand. Tools are not required, just make sure each antenna is securely fastened without over-tightening.

## 5. Locate OBD Port

Next step is to locate your OBD port in your car, it is usually found underneath the dashboard and
looks something like this:

  ![AutoPi.io - OBD port](/img/getting_started/getting_started/obd_location.jpg)

The location of the OBD port varies from make and model, but is typically fund in one of the
locations shown below:

![AutoPi.io - OBD port location](/img/getting_started/getting_started/TMU_placement_dashboard_v1_finecut-01.jpg)

## 6. Installation

When installing the AutoPi, always make sure that the device is positioned with 
the logo facing upwards towards the sky. This orientation is crucial because the GPS antenna 
is located within the device, and incorrect positioning may result in a weak GPS signal. 

### Steps for installation:
1. Choose a Mounting Spot: pick a good location in your vehicle where you'd like to mount the device. It should be secure and have a clear view of the sky if possible.
2. Mount the Device: you can use one of our mounting options, like a homemade bracket or a ready-made bracket.
    Check out your options [here].
3. Connect the Antennas: attach the antennas to the device. Please make sure the distance between the antennas and the device is no more than 3 meters—that's the length of the antenna cables.
4. Need More Cable Length for the OBD II Port? No problem! If the OBD port is in an inconvenient spot or gets in the way, 
you can buy some accessories from our [AutoPi shop](https://shop.autopi.io/): 
    * [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable?pr_prod_strat=jac&pr_rec_id=f2111200b&pr_rec_pid=8619775328605&pr_ref_pid=14961336746333&pr_seq=uniform) – add extra reach for flexible placement.
    * [Dual Lock Extreme Velcro Strip](https://shop.autopi.io/products/dual-lock-extreme-velcro) – secure, vibration-resistant mounting anywhere.
    * [DoIP HAT](https://shop.autopi.io/products/doip-hat-v1-3) - the DoIP HAT is a highly advanced interface module designed to enhance vehicle diagnostics using the DoIP protocol (Diagnostics over Internet Protocol).  
    * [OBD-II Power Cable](https://shop.autopi.io/products/obd-ii-power-cable?pr_prod_strat=jac&pr_rec_id=17052e989&pr_rec_pid=8619774050653&pr_ref_pid=8609919074653&pr_seq=uniform) - power the AutoPi CAN-FD Pro device with any 12-24 volt DC power supply.
    * [OBD-II Splitter Cable](https://shop.autopi.io/products/obd-ii-splitter-cable?pr_prod_strat=jac&pr_rec_id=70ef610e3&pr_rec_pid=8619777327453&pr_ref_pid=8619774050653&pr_seq=uniform) - use this Y-splitter cable if you need to connect an additional OBD-II device at the same time as your AutoPi CAN-FD Pro.
    * [Tesla OBD-II Adapter Cable for Model 3 and Y](https://shop.autopi.io/products/tesla-obd2-adapter-cable-for-model-3-and-y) - add an OBD-II port to your Tesla Model 3 or Model Y with this adapter cable.
    * [CAN Bus Testing/Loop Cable](https://shop.autopi.io/products/can-bus-testing-cable) - the CAN Bus Testing Cable is a cable designed for internal communication testing between two CAN bus systems.
    * [Micro USB-A Adapter Cable](https://shop.autopi.io/products/micro-usb-to-usb-a-adapter-cable)- this Micro USB to USB-A adapter cable is made to fit perfectly with the external Micro USB port on the AutoPi CAN-FD Pro device.
    * [OBD-II to dual DB9](https://shop.autopi.io/products/obd2-to-dual-db) - connect two CAN bus nodes to the OBD2 port of the AutoPi CAN-FD Pro.

### Device dimensions:
160mm x 110mm x 60mm (L/W/H)

![AutoPi CAN-FD Pro](/img/hardware/autopi_canfd_pro/canfd_pro_casing_measurements.png)

### Tips on getting the best performance of your device:
- Make sure that the AutoPi logo is facing the sky.
- Antennas should also face the sky to ensure a strong signal. 
- Try to avoid installing the device in direct sun. Direct sun will heat up the device and, in the summertime, this can cause the CPU to throttle down, if the temperature gets too hot. 
- When powering the device, make sure you only power it through the OBD connector. The device cannot be powered through any of the other ports. 
- Proper installation makes all the difference in performance. Follow the steps above for correct device mounting.

:::note
If you're working with the device during development and have it open on your desk, you can connect a monitor (via HDMI), a keyboard (via USB), and even use an Ethernet cable for internet. This setup helps you see exactly what's happening on the device in real time—ideal for debugging or development sessions.
:::

## 7. Connect to WiFi
After installing your AutoPi device into the OBD port, you will need to connect it to the AutoPi Cloud.
To do this, you will temporarily use the device’s Wi-Fi hotspot. 

The hotspot is named autopi-XXXX, where "XXXX" represents the unique ID of your device.
The **password** for this Wi-Fi hotspot is the **first 13 characters of your Device ID**. 
You can find your Device ID either by navigating to Devices > Select your device > Overview: Device specifications; or in the documentation attached to your shipping email. 
Additionally, you can access Wi-Fi information directly from the AutoPi Cloud. To do this, navigate to Devices > Select Your Device > Advanced Settings > Wi-Fi. 

Here, you will find the Wi-Fi hotspot's password and SSID credentials. 

![Wifi settings](/img/getting_started/getting_started/wifi_settings.png)

When the device is powered on, a blue light will appear on the side, indicating 
that it has power. When the device successfully connects to the AutoPi Cloud, 
a green light will be visible. If the device is not connected, the light will be flashing. 

For a detailed description of the two status LEDs, please refer to the 

## 8. Connect to Local Administration

:::note
If you’ve purchased the AutoPi CAN-FD Pro with a monthly cloud subscription, your SIM card
is pre-installed in the device, and no additional action is required for SIM connectivity. 
The APN settings are already configured for you. Please be aware that the SIM card 
has a monthly data cap, so it's recommended to limit the use of the device’s hotspot 
for connecting your phone or notebook.
:::

:::note
If you need to know the APN string for the pre-installed SIM card, it is **nxt20.net**. 
:::

:::note
If you are using a **Verizon Wireless** SIM card, please follow the dedicated setup guide:
[Setting Up Your Device with Verizon Wireless](https://docs.autopi.io/developer_guides/setting-up-a-device-with-verizon-wireless/).
:::

If you are using your own SIM card, you may need to configure the APN settings after 
connecting to the device’s Wi-Fi hotspot to ensure a seamless 4G/LTE connection. 
However, setting up the APN is not always necessary—it depends on your SIM provider. 
We suggest checking with your SIM provider directly or searching online for the correct APN settings. 

Here’s how you configure the APN settings: 

1. Go to my.autopi.io. If you're already logged in, please log out. 
2. On the login page, find the “Go Local” button at the bottom left side, 
   or alternatively, go directly to local.autopi.io.

    

This will connect you to the local device, and you should see a screen similar to 
the one shown in the image below, indicating that you're connected locally.
From here, you can log in without needing a username or password.

![AutoPi.io - Localhost login](/img/getting_started/getting_started/local.jpg)

Once the information is saved, it will be applied to the device, and you should 
see a notification when successfully saved. 

4G/LTE Settings 
![AutoPi.io - Settings Page](/img/getting_started/getting_started/apn_settings.png)

APN Presets List
![AutoPi.io - Settings Page](/img/getting_started/getting_started/apn_settings_list.png) 

## 9. Verify Connectivity

To verify that you have set up your APN settings correctly, connect your phone 
to the AutoPi hotspot and use your browser to visit any webpage. 
If the page loads successfully, it means your device is online and has 
started uploading data to the AutoPi Cloud.

## 10. Finalization

Your device is now online and connected to the AutoPi Cloud. After completing 
the setup, it's important to change your device's WiFi password. 
The default password is intended for one-time use only, and it is strongly 
recommended to update it afterward. You can change the password through the 
AutoPi Cloud by navigating to **Devices** > **Advanced Settings** > **Wi-Fi** > **Pass**. 

To prevent excessive data usage, it's advisable to avoid using the device’s 
hotspot to connect your phone or tablet after the initial configuration is complete. 

## 11. Set up Output Handlers 

Your device can capture data, but you’ll need to choose where that data should be sent, also known as configuring an output handler. Currently, the AutoPi CAN-FD Pro supports output to an Amazon AWS S3 bucket. Setting this up is quick and straightforward, just follow the step-by-step guide here: [Amazon Web Services (AWS) S3 Bucket Creation](https://docs.autopi.io/getting_started/autopi_canfd_pro/set_up_AWS_S3_bucket/).

## 12. Access Files Remotely on AutoPi

You can also view and manage your captured data remotely from your AutoPi device. For detailed instructions on how to access your files using SFTP or SCP, check out this guide: [Accessing files via SFTP/SCP on AutoPi](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/). 

**You Are All Set!**

Congratulations! You've successfully set up your AutoPi device and connected it 
to the AutoPi Cloud. Your device is now ready to start gathering and transmitting data,
enabling you to take full advantage of the powerful features AutoPi offers. 
Take your device for a trip to start gathering data.

---

**What's Next?**

Now that your device is up and running, here are a few suggestions to help you 
get the most out of your AutoPi experience: 
- **Read our User guide**: dive into the CAN-FD Pro device and all of its functionalities in our [User guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/). 
- **Explore the AutoPi Cloud**: Dive into the [AutoPi Cloud platform](https://my.autopi.io/#/login) to explore all 
  the features available to you, such as real-time vehicle monitoring, 
  advanced analytics, and customizable alerts. 
- **Check Out Our Documentation**: Our [documentation page](https://docs.autopi.io/) 
  is a great resource for learning more about advanced features, troubleshooting, 
  and getting the most out of your device. 
- **Build your Nested Accounts and Invite New Users**: AutoPi Cloud uses a multi-tenant architecture, which means multiple accounts (tenants) share the same platform and infrastructure, while all data, configurations, and user access remain securely isolated. You can read more here: [Account management](https://docs.autopi.io/cloud/accounts/).

---

## Create Loggers

---
Logging is one of the core features of the [AutoPi Mini](https://www.autopi.io/hardware/autopi-mini), allowing you to automatically record key data from your device for analysis, monitoring, or integration with other systems. In this guide, you’ll learn how to create and configure loggers for your AutoPi Mini, from understanding what are the available loggers, to setting up your own custom data collection workflows.

We’ll start with a step-by-step walkthrough on how to create, manage, and verify loggers directly from your AutoPi Cloud, followed by a quick overview of the available loggers and their specifications. Whether you’re setting up your first logger or fine-tuning advanced data capture, this guide will help you get started quickly and confidently.

---

## Default Set of [Mini](https://www.autopi.io/hardware/autopi-mini) Loggers 
To ensure your AutoPi mini device works right out of the box, we preconfigure it with a set of commonly used loggers based on the most frequently requested data from our users. These default loggers are automatically installed on your device before delivery.

During the device registration process (covered in Step 2: Registration of the device of [Getting started guide](https://docs.autopi.io/getting_started/autopi_mini/#2-register-your-device)), you’ll be asked to enter your vehicle’s make, model, year, and type. **Vehicle types** include: Internal Combustion Engine (ICE), Battery Electric Vehicle (BEV), Plug-in Hybrid Electric Vehicle (PHEV) or Hybrid Electric Vehicle (HEV).

Once you select your vehicle type, the system automatically adjusts the logger configuration to better match your vehicle’s requirements. Any loggers that are updated during this process will be marked with a "modified" status. After the changes are successfully applied to your device, this status will disappear.

![Modified logger](/img/getting_started/autopi_mini/create_mini_loggers/modified.png)

Once the default setup is complete, you can create additional custom loggers and sync them to your device. Instructions for creating and managing custom loggers can be found in the next section.

---
## Creating a [Mini](https://www.autopi.io/hardware/autopi-mini) Logger
Let's create a logger for your [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini).
Open up the [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) device view and head over to the loggers page.
Here, you will see a 'Create' and a 'Restore default' button on the left-hand side.
Clicking on the 'Create' button will open a new window, that looks like the following screenshot:

![Create a Mini Logger](/img/getting_started/autopi_mini/create_mini_loggers/create_new_logger.png)

:::note
The 'Restore default', as the name suggests, deletes the current loggers and applies default loggers based on your vehicle type. 
:::

### Configure a Logger Fields

Let's look through the fields you can configure when creating a logger:

#### 1. Parameter
This is the parameter you would like to use. Select one of them from the dropdown menu.
Note that, some parameter share the same name but can be distinguished by the group they belong to.
Next to the parameter you can also modify if you want the logger to be **Enabled** or not by clicking the checkbox.

![Set parameter](/img/getting_started/autopi_mini/create_mini_loggers/parameter.png)

#### 2. Periodic monitoring
By enabling this setting, this logger will be available in all messages from the [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini). This means that it collects all data there is and eventually upload it. 
This setting is set up by default when you are creating a logger, as it functions the most efficiently when logging a data from the device.  

![Periodic monitoring](/img/getting_started/autopi_mini/create_mini_loggers/periodic_monitoring.png)

#### 3. Event on
This setting allows you to select an event that should trigger a record in the dropdown list.
When selecting an event, you get presented with dropdown of options: Range Exit, Range Enter, Range Both, Hysteresis, Change and Delta Change. These options are a way to configure how that event behaves.

![Event On Setting](/img/getting_started/autopi_mini/create_mini_loggers/logger_event_on.png)

As an example, when selecting `Range Both` - contains a range start and range end field, which allows to configure the range that `Range Both` should generate records based on, this can also be seen in the following image:

![Range Both](/img/getting_started/autopi_mini/create_mini_loggers/logger_range_both.png)

:::warning
When setting logger to trigger `Event on` set to `Change`, some of the loggers, like external voltage, are not static by nature — they can fluctuate frequently, even by small amounts. When these loggers are **set to trigger on change**, it can lead to a high volume of events being logged. This not only results in **excessive data usage** but **can also prevent the device from entering sleep mode**, as it’s constantly active processing these changes.
Switching these loggers to periodic monitoring helps manage this by reducing unnecessary events and allowing the device to function more efficiently. 
:::

Once you save the [Mini](https://www.autopi.io/hardware/autopi-mini) Logger, you will see it appear in the Loggers page.
Once the settings have been synchronized to your device, your device will start sending the newly created logger.

---
## List of Available Loggers with Specifications 
Compared to other [AutoPi](https://www.autopi.io) devices, the [Mini](https://www.autopi.io/hardware/autopi-mini) only supports a predefined list of PID and CAN loggers (It also support listening on some system [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) system changes, like the current sleep condition).

Down below, you can find the table of available loggers with specifications:

| Name                                        | Description                                                            | Bytes | Type     | Min     | Max       | Multiplier | Units | 
|---------------------------------------------|------------------------------------------------------------------------|-------|----------|---------|-----------|------------|-------|
| Accelerometer Axis X                        | X axis value                                                           | 2     | Signed   | -8000   | 8000      | —          | mG    | -
| Accelerometer Axis Y                        | Y axis value                                                           | 2     | Signed   | -8000   | 8000      | —          | mG    | -
| Accelerometer Axis Z                        | Z axis value                                                           | 2     | Signed   | -8000   | 8000      | —          | mG    | -
| Ambient air temperature                     | Ambient air temperature                                                | 1     | Signed   | -128    | 127       | —          | °C    | -
| Battery Current                             | Battery current                                                        | 2     | Unsigned | 0       | 65535     | 0.001      | A     | -
| Battery Level                               | Battery capacity level                                                 | 1     | Unsigned | 0       | 100       |  —         | %     | -
| Battery Voltage                             | Battery voltage                                                        | 2     | Unsigned | 0       | 65535     | 0.001      | V     | 
| Engine RPM                                  | Engine RPM                                                             | 2     | Unsigned | 0       | 16384     | —          | rpm   | -
| Engine Oil Temperature                      | Engine oil temperature                                                 | 1     | Unsigned | 0       | 215       | —          | °C    | -
| External Voltage                            | External voltage                                                       | 2     | Unsigned | 0       | 65535     | 0.001      | V     | -
| Fuel level                                  | Fuel level                                                             | 1     | Unsigned | 0       | 100       | —          | %     | 
| GSM Signal                                  | Value in range 1-5                                                     | 1     | Unsigned | 0       | 5         | —          | —     | - 
| Ignition                                    | 0 - Ignition Off; 1 - Ignition On                                      | 1     | Unsigned | 0       | 1         | —          | —     | - 
| Intake air temperature                      | Intake air temperature                                                 | 1     | Signed   | -128    | 127       | —          | °C    | -
| Network Type                                | 0 - 3G; 1 - GSM; 2 - 4G; 3 - LTE CAT M1; 4 - LTE CAT NB1; 99 - Unknown | 1     | Unsigned | 0       | 1         | —          |  —    | -  
| Number of DTC                               | Number of DTC                                                          | 1     | Unsigned | 0       | 255       | —          |  —    | -  
| OBD OEM Total Mileage                       | Total mileage (from OEM PID)                                           | 4     | Unsigned | 0       |  —        | —          | km    | -
| OBD Vehicle Speed                           | Vehicle speed                                                          | 1     | Unsigned | 0       | 255       | —          | km/h  | -
| OEM Battery charge level                    | Represents battery charged level                                       | 1     | Unsigned | 0       | 100       | —          | %     | -
| OEM Battery State Of Health                 | Battery health percentage                                              | 2     | Unsigned | 0       | 65535     | —          | %     | -
| OEM Battery Temperature                     | Battery pack temperature                                               | 2     | Signed   | -32768  | 32767     | —          | °C    | - 
| OEM Distance Until Service                  | Distance till next service received by requesting PID                  | 4     | Unsigned | 0       | —         | —          | —     | 
| OEM HV Battery Current                      | Current used by high-voltage battery                                   | 2     | Unsigned | 0       | 65535     | 0.1        | A     |
| OEM HV Battery Max Cell Temperature         | Maximum measured cell temperature                                      | 2     | Signed   | -32768  | 32768     | 0.1        | °C    | -
| OEM HV Battery Max Cell Voltage             | Maximum battery cell voltage                                           | 2     | Unsigned | 0       | 65535     | 0.1        | V     | - 
| OEM HV Battery Max Energy                   | Maximum energy capacity                                                | 2     | Unsigned | 0       | 65535     | 0.1        | kWh   | -
| OEM HV Battery Measured Energy              | Measured current energy capacity                                       | 2     | Unsigned | 0       | 65535     | 0.1        | kWh   | -
| OEM HV Battery Min Cell Temperature         | The lowest measured cell temperature                                   | 2     | Signed   | -32768  | 32768     | 0.1        | °C    | -
| OEM HV Battery Min Cell Voltage             | Minimum battery cell voltage                                           | 2     | Unsigned | 0       | 65535     | 0.1        | V     | -         
| OEM HV Battery Current                      | Current used by high-voltage battery                                   | 2     | Signed   | -3276   | 3276      | 0.1        | A     | -  
| OEM HV Battery Voltage                      | High voltage battery voltage                                           | 2     | Unsigned | 0       | 65535     | 0.1        | kWh   | -
| Total Odometer                              | Total Odometer value in meters                                         | 4     | Unsigned | 0       | 2147483647| —          |       | - missing unit
| Trip Odometer                               | Trip odometer value                                                    | 4     | Unsigned | 0       | 2147483647| —          | m     | - 
| VIN                                         | Vehicle Identification Number                                          | 17    | ASCII    | 0       |  —        | —          | —     | -

---

## Link Your Loggers to Your Dashboard

For a widget to display data, it must be linked to the appropriate **logger**. If you add or edit loggers, you will also need to update the corresponding **dashboard widgets**.

Widgets can display data in several formats, including:
* Graphs
* Line charts
* State timelines
* Gauges ... 

You can also configure widgets to show **average**, **minimum**, or **maximum** values depending on your needs.

After adjusting your widget settings:

1. Click **Save**.
2. Refresh the widget using the **circle icon** in the top-right corner.

If the data appears after refreshing, your configuration is correct. If you have just created a new logger, the device may need another **vehicle trip** before the required data is collected.

---

### Add a Widget

To create a new widget:

1. Navigate to **Dashboard**.
2. Click the **Actions** button in the upper-right corner.
3. Select **Add widget**.
4. Fill out the required information.
5. Click **Save**.
6. Save your dashboard changes to apply the widget.

![Add a Widget](/img/getting_started/autopi_mini/create_mini_loggers/add_new_widget.png)

> **Note:** For a more detailed explanation of widget configuration, see this guide: [Configure the widget settings](https://docs.autopi.io/cloud/fleet_management/configurations/dashboards/#step-2-add-widgets-to-the-shared-dashboard).

> **Note:** When choosing the **Field**, the list only shows data that has already been received from the device. If the logger you are looking for is not in the list, the device may not be reading it. In this case, go to **Loggers**, enable the logger, or update its settings.

> **Note:** A logger must be configured beforehand, otherwise the widget will not have any data to display.

---

### Configure a Widget

To edit an existing widget:

1. Navigate to **Dashboard**.
2. Click the **two-dot icon** on the widget you want to update.
3. Make your desired changes.
4. Click **Save**.

![Configure a Widget](/img/getting_started/autopi_mini/create_mini_loggers/configure_widget.png)

> **Note:** Ensure the configuration, especially the **Field** section, matches the data being logged.

---

### Auto-Generate Widgets

The **Auto-generate** feature allows you to quickly create widgets based on the data received from the device. This saves time compared to creating each widget manually. Auto-generated widgets are based on **real data**, and you can adjust them afterward if needed (for example changing aggregation or visualization).

How to use Auto-generate:

1. Navigate to **Dashboard**.
2. Click the **Actions** button in the upper-right corner.
3. Select **Auto-generate**.
4. Make any desired changes.
5. Click **Save**.

> **Note:** By default, there is usually an **auto-generated dashboard** created for your device, which you can find in the **dashboard dropdown menu**.

When you are satisfied with your dashboard configuration, remember to **save your layout** through **Widget Actions** to keep your settings for future sessions.

---

## Data Troubleshooting(Autopi_mini)

---

## Why Am I Not Seeing Any Data? 

If you've followed the [Getting Started Guide](/getting_started/autopi_mini/index.md)
and tested your [AutoPi](https://www.autopi.io) TMU CM4 device during a drivebut no data is appearing on 
your [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) Dashboard, this guide will help you identify and resolve common issues.

Organized as a checklist, this guide outlines potential causes for missing vehicle
data and offers solutions. It is specifically for the [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) device. For 
[AutoPi](https://www.autopi.io) TMU CM4, please refer to this [guide](/getting_started/autopi_tmu_cm4/index.md).  

![Dashboard](/img/getting_started/autopi_mini/data_troubleshooting/no_data_dashboard.png)

## Common Causes and Solutions for Data Not Appearing on the [Cloud](https://www.autopi.io/software-platform/cloud-management)  

### 1. Connection Issues 

One common reason for missing data is communication issues within the [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini)
or between [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) and the [Cloud](https://www.autopi.io/software-platform/cloud-management). The SIM card in your [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) comes 
pre-installed and should function out of the box. 

When your AutoPi [Mini](https://www.autopi.io/hardware/autopi-mini) is connected to your vehicle's OBD-II port, check the 
status of the two LEDs on the device: 

1. **Navigation LED(closer to the edge of the device):**
    
    This LED indicates the status of the GNSS (Global Navigation Satellite System).
    - **Green and blinking slowly:** The device is receiving a GNSS signal. 
    - **Solid green:** The device is not receiving a GNSS signal. 
    - **Off:** This may indicate the device is either in sleep mode or experiencing an issue. 

2.  **Status LED (farther from the edge of the device):**
    
    This LED reflects the device’s operating status.
    - **Blinking every second:** The device is in normal operating mode. 
    - **Blinking every 2 seconds:** The device is in sleep mode. 
    - **Fast blinking:** Indicates modem activity. 
    - **Off:** This could mean the device is not functioning. 

If either LED is not behaving as expected, it could be a sign of connectivity or 
hardware issues that need attention. Try to disconnect it from the OBD-II port, 
then reconnect it. Wait until both lights are green and blinking.  

![AutoPi Mini LED meaning](/img/getting_started/autopi_mini/data_troubleshooting/mini_light_placements_01.png)

### 2. Logger Creation

Another issue to why you are not seeing data on your [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) Dashboard could
be the configuration of the loggers.  

In order to view data on the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) Dashboard, you must ensure that loggers
are set up to collect data from your vehicle. While some loggers are created by 
default, they may not be suitable for your specific vehicle. 

For more detailed instructions on creating loggers for the [Mini](https://www.autopi.io/hardware/autopi-mini), refer to our 
[Logger Guide](/getting_started/autopi_mini/create-mini-loggers).

![Loggers configuration](/img/getting_started/autopi_mini/data_troubleshooting/loggers_configuration.png)

Recommendations for Logger Setup: 
- Use the logger groups OBD-II Standard or System, as these are typically 
  compatible with most vehicles. 
- Once your loggers are set up, check the ‘Change History’ to ensure the 
  changes were applied successfully.

### 3. Configuring Widgets 

Once your loggers are in place, the data should display in widgets on the 
Dashboard under Vehicles > Dashboard. 

![Successful dashboard](/img/getting_started/autopi_mini/data_troubleshooting/successful_data_dashboard.png)

A common reason for seeing "No Data" could also be incorrect widget configuration.
For the widget to display data, it must be linked to the appropriate logger. So, 
if you have added or edited the loggers, you will also need to make the changes 
in the Dashboard’s widgets.  

To edit your widget: 
- Click the three dots in the top right corner of the widget. 
- Ensure the configuration, especially the **Field** section, matches the data being logged. 

![Widget actions](/img/getting_started/autopi_mini/data_troubleshooting/configuration_widget.png)

**Customizing Widget Display:**
- You can choose from various display formats such as graphs, line charts, and gauges.
- Set the widget to show data averages, minimums, or maximums based on your preferences.

After adjusting your widget settings, click **Save**. Then, refresh the widget 
using the circle icon in the top right corner to see if the data appears. 
If the data is now visible, your configuration is correct. If you've just 
createda new logger, it may take another vehicle trip for the device to gather 
the required data.   

Don’t forget to save your dashboard changes by selecting **Widget Actions** > **Save**. 

![Widget actions](/img/getting_started/autopi_mini/data_troubleshooting/widget_action.png)

To add a new widget to your dashboard, go to **Widget Actions** and choose 
**Add Widget**. Remember, a logger must be set up beforehand, or the widget 
won't have any data to display.  

When you're satisfied with your dashboard configuration, save your layout via 
**Widget Actions** to keep your settings for future sessions.  

## 4. No data from your AutoPi mini (EV users)

If your [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) is not sending data to the cloud and you have an electric vehicle (EV), the issue may be due to the device not being able to autodetect the VIN. Unlike internal combustion engine (ICE) vehicles, some EVs do not support automatic VIN detection, which can prevent the device from reading data properly. To resolve this, follow these steps to adjust the advanced settings for EV compatibility. 

![AutoPi.io - Relocator cable](/img/getting_started/autopi_mini/mini_advanced_settings.png)

Recommended advanced settings for Electric Vehicle:

**Option 1: Adjust OBD Feature, this setting ensures the device correctly communicates with your EV.**

1. Go to: Advanced settings → Obd Settings → Obd Feature.
2. Select: Non-OBD Compliant.
3. Press: Save.

**Option 2: Manually enter your VIN (if not detected automatically).**

1. Go to: Advanced settings → Obd Vin Settings.
2. Set Vin: enter your 17-character VIN (digits and capital letters).
3. Pick Vin Source: select Manual.
4. Press: Save.

**Option 3: Set Ignition detection for EVs to properly detect when your EV is on or off.**
1. Go to: Advanced settings →System -> Ignition Settings.
2. Select: Accelerometer.
3. Press: Save.

After making these adjustments, check the 'Change History' tab to confirm that your settings were applied successfully.

---

## Getting Started(4)

---

Welcome to [AutoPi](https://www.autopi.io)! 

This step-by-step guide will help you set up your [AutoPi](https://www.autopi.io) TMU CM4 4G/LTE Edition. 
The device comes pre-assembled with the SD card inside and requires just a few steps to complete the installation.

:::note

**Important Notes Before You Start**

The [AutoPi](https://www.autopi.io) Telematics Unit is a highly customizeable and technical device. It contains a direct
interface to your car and communicates with the ECU in your car.

1. **Power Off the Vehicle**: When inserting the device for the first time, ensure that the vehicle is powered off.
2. **Vehicle Must Be Parked**: When working on and customizing your device, make sure your vehicle is in the parked position.
3. **Do Not Remove the [AutoPi](https://www.autopi.io) While Driving.**
4. **Power Source**: The device can only be powered through the OBD-II port.
     Powering the Raspberry Pi directly is not supported and may cause issues.
5. **Advanced Settings Caution**: When updating the Advanced settings, ensure you understand what you
     are doing, as changes can affect the performance of your car and its battery.  
:::

## 1. Setting Up User Account

Once you have received your [AutoPi](https://www.autopi.io) device it is important to associate it with [Cloud](https://www.autopi.io/software-platform/cloud-management) Platform.
Go to [my.autopi.io](https://my.autopi.io/) and click “Sign up”. In the pop-up, 
add the e-mail address you want to associate with your account and create a password. 
You can also expand the form to add additional details like your country and full name, 
though this can be done later. Click “Create account”.

![AutoPi sign up](/img/getting_started/getting_started/sign_up.png)

## 2. Register Your Device

After creating an account, you can access the [Cloud](https://www.autopi.io/software-platform/cloud-management) Platform features for fleet and device management.
The next step is to register your device to unlock the platform’s full potential.  

To add a device to your account, follow one of these methods:  

**Option 1: Via Device Management**
1. See the “Device Management” section of the Platform. 
2. Click on “Devices”. 
3. Find and click the “Register Device” button in the upper right corner. 

**Option 2: Via the Accounts Tab**
1. Navigate to the “Accounts” tab at the bottom of the left side menu on the Platform.
2. Select “Devices”. 
3. Locate and click the “Register Device” button in the upper right corner.

After clicking the “Register Device” button, the registration tab will appear. Enter all necessary information: 

![Register Device](/img/getting_started/getting_started/register_new_device.png)

- **Unit ID**: This is the number on the side of your device. You can also find it in the.
    document attached in the email you received when the device was shipped. 
- **Vehicle Information**: Optionally include the make, model and year of the vehicle.
- **Vehicle Type**: Choose the type of vehicle (ICE, Battery [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini), Hybrid [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini), or Plug-in Hybrid [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini)).

Once all information is entered, click the “Register Device”. Your newly registered device 
will now appear in the list under “Vehicles” in the Fleet Management section and under 
“Devices” in the Device Management section of the Platform.

## 3. Locate OBD Port

Next step is to install the device into your vehicle. Locate the OBD port in your car, 
it is usually found underneath the dashboard and looks something like this:

  ![AutoPi.io - OBD port](/img/getting_started/getting_started/obd_location.jpg)

Please note that the location of the OBD port varies from make and model but is
typically found in one of the locations shown below:

![AutoPi.io - OBD port location](/img/getting_started/getting_started/TMU_placement_dashboard_v1_finecut-01.jpg)

## 4. Installation

When installing the [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini), make sure the device is positioned with the 
logo facing upwards toward the sky. This is important because the GPS antenna is 
inside the device, and if it's not facing up, you might not get a strong GPS signal.

If the OBD port is in a difficult spot or gets in the way, you can buy an 
[extension cable](https://shop.autopi.io/products/obd-ii-extension-cable)
to place your [AutoPi](https://www.autopi.io) in a more convenient location. 

This is the OBD-II extension cable: 

![AutoPi.io - Relocator cable](/img/getting_started/getting_started/relocator_cable.png)

## Electric Vehicle configurations

If your [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) is connected to an Electric Vehicle we recommend to set some extra configurations for your device. Unlike internal combustion engine (ICE) vehicles, some EVs do not support automatic VIN detection, which can prevent the device from reading data properly. To resolve this, follow these steps to adjust the advanced settings for EV compatibility. 

![Mini advanced settings](/img/getting_started/autopi_mini/mini_advanced_settings.png)

Recommended advanced settings for Electric Vehicle:

**Configuration 1: Adjust OBD Feature, this setting ensures the device correctly communicates with your EV.**

1. Go to: Advanced settings → Obd Settings → Obd Feature.
2. Select: **Non-OBD Compliant**.
3. Press: Save.

**Configuration 2: Manually enter your VIN (if not detected automatically).**

1. Go to: Advanced settings → Obd Vin Settings.
2. Set Vin: enter your 17-character VIN (digits and capital letters).
3. Pick Vin Source: select **Manual**.
4. Press: Save.

**Configuration 3: Set Ignition detection for EVs to properly detect when your EV is on or off.**
1. Go to: Advanced settings → System -> Ignition Settings.
2. Select: **Accelerometer**.
3. Press: Save.

**Configuration 4: Set Movement source to be more precise when the vehicle is moving.**
1. Go to: Advanced settings → System -> Movement Source.
2. Select: **Accelerometer**.
3. Press: Save.

**Configuration 5: Set the Accelerometer Delay Settings to ensure rapid response for data reading but also a protection for quick state changes.**
1. Go to: Advanced settings → System -> **Movement start delay**.
2. Select: 5 to 12 seconds.
3. Go to: Advanced settings -> System -> **Movement stop delay**.
4. Select: 30 to 60 seeconds.
3. Press: Save.

After making these adjustments, check the 'Change History' tab to confirm that your settings were applied successfully.

**You Are All Set!**

Congratulations! You've successfully set up your [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) device and connected 
it to the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management). Your device is now ready to start gathering and transmitting 
data, enabling you to take full advantage of the powerful features [AutoPi](https://www.autopi.io) offers. 
Take your device for a trip to start gathering data.

---

## 4G Internet Setup Troubleshooting(Autopi_tmu_cm4)

---

This guide helps you diagnose and resolve common 4G connectivity issues on your [AutoPi](https://www.autopi.io) device. If you cannot access the internet while connected to the device hotspot, follow the steps below in order.

:::tip Our support team is here to help you.
If you need assistance, contact support@autopi.io.
:::

### Prerequisites
Before starting, complete the initial [setup guide](https://docs.autopi.io/getting_started/autopi_tmu_cm4/).

---

### Check SIM Card

* Confirm that your SIM card is enabled for mobile data. Test the SIM in another device (for example, a smartphone) and verify that internet access works.
* If you are using a data-only SIM, confirm with your carrier that the data plan is active and roaming is enabled when required.
* Verify that the SIM card is not PIN-locked. If it is PIN-locked, enter the correct PIN in the device advance settings.
* Remove and reinsert the SIM card, and inspect both the SIM and slot for physical damage. Bent contacts, debris, or a loose SIM slot can prevent modem detection.
* Make sure the SIM orientation is correct. The text side of the SIM card must face up, and the triangle end must point into the device.

    

:::caution
When inserted correctly, you should hear a small click as the card locks into position.
Do not force the SIM card out after the click, as this can damage the slot.
Always verify orientation before insertion.
:::

---

### Check Modem Detection (Hardware)

* Connect to the device hotspot and open [AutoPi Local](http://local.autopi.io). 
* Open the terminal and run:

    ```python
    cmd.run "lsusb"
    ```
* The output should look similar to this:

    ![lsusb](/img/getting_started/autopi_tmu_cm4/4g_internet_setup_troubleshooting/lsusb.jpg)

* Look for your modem in the list. The USB ID will vary depending on the modem installed in your device:

    | **Modem Manufacturer** | **USB ID** |
    |------------------------|------------|
    | Quectel                | `2c7c:0121` |
    | Telit                  | `1bc7:1031` |

* If you ordered a 4G-enabled device and the modem does not appear in the list, please contact support@autopi.io.

:::tip
If `lsusb` is unavailable, run `cmd.run "dmesg | grep -i usb"` to check USB detection events.
:::

---

### Check Modem Setup

#### Check PDP Context

PDP context controls how the modem connects to the mobile network. Incorrect values can prevent data sessions from starting.

For software version `1.22.7` or newer:

```python
modem.connection pdp_context
```

For `older` versions:

```python
modem.connection execute AT+CGDCONT?
```

Expected output is either:

```python
# Single context
value:
- apn: ''
  cid: 1
  pdp_type: IPV4V6

# Dual context (includes ims)
value:
- apn: ''
  cid: 1
  pdp_type: IPV4V6
- apn: 'ims'
  cid: 2
  pdp_type: IPV4V6
```

If the dual-context result causes connectivity issues, reconfigure with:

```python
cmd.run "systemctl stop qmi-manager"
modem.connection execute AT+CGDCONT=2
cmd.run "systemctl restart qmi-manager"
```

Run the PDP command again to confirm the result.

---

**Check Firmware Switch**

An incorrect firmware switch setting can prevent the modem from connecting to the network correctly.

**If you are using software version `1.22.7 or newer`, run:**

```python
modem.connection active_firmware_image
```

The expected output looks like this:

```python  
_stamp: "<current date>" 
_type: active_firmware_image
net_conf:global
storage_conf: ram  
```

Confirm that `net_conf` is set to `global`.

**Incase your software version is `older than 1.22.7`, you can run the following command to get the same information:**
```python  
modem.connection execute AT#FWSWITCH?'
```

Expected output:

```python
Data:'FWSWITCH:40:1'
```

If the value does not start with `40`, configure it manually:

```python
modem.connection execute AT#FWSWITCH=40,1
```

Restart the device and verify again.

:::tip
For additional modem commands and examples, see [Core Commands - Modem](https://docs.autopi.io/core/commands/core-commands-modem/).
:::

---

### Check APN Configuration

A missing or incorrect APN can block internet access even when the modem is detected.

:::note
If you are using the AutoPi SIM card (included with monthly cloud subscription), APN is pre-configured on newly shipped devices.
In most cases, you can skip this section.
If you want to verify manually, APN should be set to **nxt20.net**.
:::

Check the current APN:

```python
modem.connection pdp_context
```

If APN is missing and your carrier requires it, set it manually:

```python
modem.connection execute AT+CGDCONT=1,"IPV4V6","<your-apn>"
```

Then restart the manager:

```python
cmd.run "systemctl restart qmi-manager"
```

:::tip
If you do not know your APN, check your carrier documentation or support channel.
:::

---

### Check qmi-manager Status

`qmi-manager` maintains the cellular data connection.

Check status:

    ```python
    cmd.run "qmi-manager status"
    ```

Expected response: 

    ![qmistatus](/img/getting_started/autopi_tmu_cm4/4g_internet_setup_troubleshooting/qmistatus.jpg)

If needed, restart it:

    ```python
    cmd.run "systemctl restart qmi-manager"
    ```

---

### Restart the Network Interface

If `qmi-manager` is running but internet is still unavailable, cycle the interface:

```python
cmd.run "qmi-manager down"
cmd.run "qmi-manager up"
```

If SIM detection fails on `up`, power down the device, check SIM orientation and seating, then try again.

Check interface state and IP address:

```python
cmd.run "ip link show wwan0"
cmd.run "ip addr show wwan0"
```

If `wwan0` has no IP address, the mobile session is not established.

---

### Adjust the MTU Setting

If connection is unstable (drops, intermittent cloud status), tune MTU. Based on your board version, the default MTU is either `1500` or `1280`.

If your default is `1280`, change it to `1500` and check whether the device comes online.
If your default is `1500`, change it to `1280` and check whether behavior improves.
This quick comparison helps confirm whether MTU is causing the issue.

Apply MTU:

```python
grains.set qmi:mtu <value>
state.sls network.wwan.qmi.config
```

Verify:

```python
grains.get qmi:mtu
cmd.run "cat /etc/udhcpc/qmi.override"
```

Confirm that both outputs match the configured MTU.

:::note
* **US Verizon**: start with MTU `1428`.
* **Other carriers**: start with MTU `1280`.
:::

---

### Check Internet and Cloud Connectivity

Test internet over cellular:

```python
cmd.run "ping -c 5 -I wwan0 google.com"
```

Test AutoPi Cloud access:

```python
cmd.run "curl -v my.autopi.io"
```

If ping works but cloud access fails, test DNS:

```python
cmd.run "nslookup my.autopi.io"
```

If DNS fails, try a temporary public DNS value:

```python
cmd.run "echo 'nameserver 8.8.8.8' > /etc/resolv.conf"
```

Then re-run ping and curl.

---

### Collect Logs for Support

If the issue persists, collect logs before opening a support request.
Follow this guide to export relevant logs: [AutoPi Logs Guide](https://docs.autopi.io/developer_guides/autopi-logs/)

---

### Summary

By this point, you should have verified:

1. SIM compatibility, orientation, and slot condition.
1. Modem detection and modem configuration (PDP and firmware switch).
1. APN settings.
1. `qmi-manager` and `wwan0` status.
1. MTU tuning and DNS/cloud connectivity tests.

:::note
If you open a support case, include the full output from all commands used in this guide, along with the collected [Logs](https://docs.autopi.io/developer_guides/autopi-logs/).
:::

---

## Create Loggers(Autopi_tmu_cm4)

---

Logging data is one of the core features of the AutoPi TMU CM4, allowing you to automatically record key data from your device for analysis, monitoring, or integration with other systems. After completing the [Getting Started Guide](https://docs.autopi.io/getting_started/autopi_tmu_cm4/), this is the next step to help you get the most out of your AutoPi TMU CM4 device.

This guide walks you through:
* Setting up CAN communication.
* Using the OBD Library.
* Creating and managing loggers.
* Linking logged data to dashboards.

---

## Step 1: Setting up CAN Bus Protocol

Before creating loggers, ensure your CAN Bus is configured correctly. There are three available methods to set up a CAN Bus protocol: Auto-detection, manual setup or using CAN Analyzer. All of the methods are described below. 

> **Tip:** You can verify the protocol using the Cloud terminal command: `obd.protocol`. You can also read more in this guide: [OBD commands](https://docs.autopi.io/core/commands/core-commands-obd/#obdprotocol).

### Auto-detection of the CAN Bus Protocol 
  Automatically detects the correct protocol. If successful, it will appear in:
  * Events tab - you can see it as `system/obd/bus_connected`.
    ![Vehicle editor - CAN Bus](/img/getting_started/autopi_tmu_cm4/create_loggers/events_can_bus.png)
  * Device → Edit Device → Vehicle Editor → CAN Buses. 
    ![Vehicle editor - CAN Bus](/img/getting_started/autopi_tmu_cm4/create_loggers/vehicle_editor_canbus.png)
  * Device -> Overview -> CAN Bus widget. 
    ![Vehicle editor - CAN Bus](/img/getting_started/autopi_tmu_cm4/create_loggers/can_bus_widget.png)

### Manual setup of the CAN Bus Protocol 

Steps to manually setup the CAN Bus: 
  * Navigate to device -> Edit Device → Vehicle Editor → CAN Buses -> Create. 
  * Fill out these information: 
    ![Create new CAN Bus](/img/getting_started/autopi_tmu_cm4/create_loggers/new_can_bus.png)
    * **Name** - short name for your CAN Bus. 
    * **Default** - specify if you want to use this CAN Bus as default option. 
    * **Protocol** - select the protocol. 
    * **Baud Rate** - set up a baud rate. 
  * Click Create. 

### Use CAN Analyzer (Sniffer)
Use the sniffer to detect available CAN traffic and identify the correct protocol. The CAN Analyzer functionality consists of four main functions:

* Sniffer - passive monitoring of CAN traffic.
* Recorder - captures CAN messages and stores them for later use.
* Player - replays previously recorded CAN traffic.
* PID Tester - sends request-response queries to ECUs.

Using sniffer, helps you to find the correct CAN Bus Protocol, you can read more at this guide: [CAN Analyzer](https://docs.autopi.io/cloud/device_management/can-analyzer/). 

---

## Step 2: Browse the OBD Library

The OBD Library is where you define what data your device can read and you can then share this data across devices. 

### Community Library
Community Library contains shared PIDs from other users and free to be used. These PIDs are automatically filtered by your vehicle model (make/model/year). 

In the Community Library, you can:
* Preview the PID by clicking it, and test the command on your vehicle.
* Add PIDs to **My Library** by selecting your device from the dropdown options for "Device" and by clicking on "Add to my library". 

![Sharing PIDs to Your Library](/img/getting_started/autopi_tmu_cm4/create_loggers/share_pid.png)

> **Note:** Some PIDs may require adjustments depending on your vehicle.

If you want to learn more about how to find and use PIDs and add them to your Library, check out this guide: [Community Library](https://docs.autopi.io/cloud/obd_library/community_library/).

### My Library

My Library is your personal collection of PIDs, CAN messages and CAN signals. There are different ways to add items to your Library. Such as: 

#### Option 1: Import from Community Library 
  To add PIDs to My Library, go to Community Library and click on any PID you like, and by selecting your device and clicking on "Add to my library".

#### Option 2: Import DBC file (CAN messages/signals)
  The Library supports importing both CAN messages and signals through DBC files. As an example, let's use this simple DBC file:
    ```  
      VERSION "1.0"
      
      BO_ 938 FRONT_LEFT: 4 IO
        SG_ LEFT_SEAT_TEMP: 0|8@1+ (1,0) [0|0] "c" ECU1
        SG_ LEFT_BACK_TEMP: 8|16@1+ (1,0) [0|0] "c" ECU1
      
      BO_ 937 FRONT_RIGHT: 4 IO
        SG_ RIGHT_SEAT_TEMP: 0|8@1+ (1,0) [0|0] "c" ECU1
        SG_ RIGHT_BACK_TEMP: 8|16@1+ (1,0) [0|0] "c" ECU1
      
      CM_ SG_ 938 LEFT_SEAT_TEMP "Temperature of the front left seat";
    ```

#### Option 3: Import JSON file (PIDs)

The Library also supports importing PIDs using JSON format. Unlike CAN messages and signals, there's no industry standard file format for PIDs. Therefore, there's a custom JSON based format that you need to follow. 

This is an example PID JSON file:

```json
[
	{
		"fields": {
			"type": "PTY",
			"header": "700",
			"mode": "220",
			"code": "0103",
			"bytes": null,
			"frames": null,
			"strict": false,
			"formula": "bytes_to_int(messages[0].data[-3:])",
			"unit": "km",
			"min": null,
			"max": null,
			"datatype": null,
			"parent": null,
			"name": "TractorLighting",
			"description": "Tractor's light emission",
			"hash": "",
			"initial_hash": null,
			"can_extended_address": null,
			"can_flow_control": {
				"filter": {
					"pattern": "708",
					"mask": "7FF"
				},
				"id_pair": {
					"receiver_id": "700",
					"transmitter_id": "708"
				}
			},
			"can_messages": []
		}
	},
	{
		"fields": {
			"type": "PTY",
            ...
        }
	}
]
```

#### Option 4: Create manually

##### Option 4.1: Create a PID Manually
Items that are created with the OBD-II PID type are PIDs that are a part of the OBD-II standard which is used by most internal combustion engine (ICE) vehicles.

![Create PID Manually](/img/getting_started/autopi_tmu_cm4/create_loggers/library_create_new_PID.png)

To create a new PID, you need to fill out these:
* **Name**: short name of the PID that's being created.
* **Description**: optional description of the PID. This can be very useful if plan to share the PID with the rest of the community.
* **Mode**: this is the mode that the PID is working in. We will type 01 in our example. However there are different modes you can use:
    * `01` - show current data .
    * `02` - show freeze frame data.
    * `03` - show stored Diagnostic Trouble Codes. 
    * `04` - Clear Diagnostic Trouble Codes and stored values.
    * `05` - test results, oxygen sensor monitoring (non CAN only).
    * `06` - test results, other component/system monitoring (test results, oxzgen sensor monitoring for CAN only).
    * `07` - show pending Diagnostic Trouble Codes (detected during current or last driving cycle).
    * `08` - control operation of on-board component/system.
    * `09` - request vehicle information. 
    * `0A` - permanent Diagnostic Trouble Codes (DTCs)(Cleared DTCs).
* **Code**: the hexadecimal representation of the requested PID. In this case, the code is 0C and so we will specify that.
* **Header**: the header used to request the PID. 7DF is the standard header value for external OBD-II test equipment, so this is the one we'll use.
* **Bytes**: This is the expected length of the response. 
* Enhanced PID: 
  * **Frames**: how many can frames are expected for this PID response. If chosen `any` - accept single-frame or multi-frame responses. 
  * **Strict**: choose between strict and loose. If strict is set, it will ensure that the device is exactly the length of bytes specified in the bytes field.
  * **CAN Extended Address** - with CAN Extended Addressing, an extra byte inside the data payload is used to specify the target.
  * Filter **Pattern** - the expected CAN ID or part of it you want to match. 
  * Filter **Mask** - defines which bits matter in the pattern. Bits set to "1" - must match; bits set to "0" - ignore.
  * ID Pairs **Transmitter ID** - the CAN ID your tool sends from, usually something like `0x7DF`.
  * ID Pairs **Receiver ID** - the CAN ID you expect the response from, example `0x7DF`.
* **Formula**: A Formula is a dynamic expression evaluated at runtime that converts raw vehicle response data into meaningful values. It operates within a constrained execution environment with predefined helper functions and message objects.
    * Example of custom formula: `bytes_to_int(message.data[4:8])`
* **Unit**: The unit of the data (more examples: km/h, percentage, liters, etc.)
* **Min**: The minimum value that this PID can return.
* **Max**: The maximum value that this PID can return.
* **Vehicle Bus(es)**: A list of CAN busses that support this PID. If a vehicle is able to recognize this PID and return data back, it is recommended that you add the bus of that vehicle to the list.

This is how Custom Formula is evaluated: 

  ```python
    def calc_formula(expression, message_data, default=None):
    
        if not message_data:
            log.warn("No data found to calculate formula: {:}".format(expression))
    
            return default
    
        if type(message_data) == bytearray:
            message_data = [TranslatableMessage(message_data)]
    
        try:
            return eval(expression, {}, {
                # Helper functions
                "bytes_to_int": bytes_to_int,
                "bytes_to_hex": bytes_to_hex,
                "twos_comp": twos_comp,
                # Message data
                "message": message_data[0],
                "messages": message_data
            })
        except Exception as ex:
            log.exception("Failed to calculate formula")
    
            raise Exception("Failed to calculate formula: {:}".format(ex))
    ```
    Therefore using the formulas defined in the `calculate_formula` - and what comes in is an array of bytes, so each index contains one byte!

Formulas are evaluated using a restricted `eval` environment. The expression has access to:
* Helper Functions
  * `bytes_to_int` — converts raw byte sequences into an integer.
  * `bytes_to_hex` — converts raw byte sequences into a hexadecimal string.
  * `twos_comp` — interprets a value using two’s complement (for signed values).
* Message Context
  * `message` — the first response message (most common use case).
  * `messages` — a list of all response messages (useful for multi-frame responses).

##### Option 4.2: Create a PGN Manually

![Create PGN Manually](/img/getting_started/autopi_tmu_cm4/create_loggers/library_create_new_PGN.png)

To create a new PGN, you need to fill out these:
* **Name**: short name of the CAN message that is being created.
* **Description**: an optional description for this PGN. 
* **Number**: number of the PGN to query.
* **Priority**: the priority to use for the request frame.
* **Source address**: the source address of the request frame.
* **Destination address**: the destination address of the request frame.
* **Formula**: Python code that decodes the raw byte data to a value.
* **Auto Filter**: ensure to apply filtering to only include reply frame(s) for the specific PGN. 
* **Auto Enable TP**: automatically enable Transport Protocol (TP) for multi-frame messages.
* **Auto Filter Mask**: the bitmask to use when the filter is applied (to all frame types including TP).

##### Option 4.3: Create a CAN Message Manually
CAN messages are continuously broadcasted on the CAN bus and do not require any requests to be made. However, to be able to make any sense of the CAN messages, we need to specify which bytes within a message corresponds to which data point from the vehicle.

![Create CAN Message Manually](/img/getting_started/autopi_tmu_cm4/create_loggers/library_create_new_can_message.png)

To create a new CAN Message, you need to fill out these: 
* **Name**: short name of the CAN message that's being created.
* **Description**: an optional description for this CAN message.
* **Header**: the hexadecimal representation of the header that this CAN message is recognized by.
* **Bytes**: How long is the CAN message?
* **Sender**: The name of the transmitting node of this CAN message - usually defined inside a DBC file, but can be any short string.
* **X CAN Signals**: This is a list of CAN signals that can be found inside a CAN message. "X" represents the number of created signals. Each CAN signal has the same form fields:
  * **Name**: short name of the CAN signal.
  * **Description**: an optional description of this CAN signal.
  * **Endian**: the endianness of this CAN signal - which is the most significant byte.
  * **Sign**: defines if the CAN signal should be treated as a signed or unsigned number.
  * **Start**: defines the starting bit of the CAN signal.
  * **Length**: how long the CAN signal is.
  * **Factor**: used to calculate the real value off of the CAN signal. Formula: `VALUE = (RAW_VALUE * FACTOR) + OFFSET`
  * **Offset**: used to calculate the real value off of the CAN signal.
  * **Unit**: the unit of the value returned.
  * **Min**: the minimum value possible for this CAN signal.
  * **Max**: the maximum value possible for this CAN signal.
  * **Receivers**: the name of the receiving node of this CAN message - usually defined inside a DBC file, but can be any short string.
* **Vehicle bus(es)**: A list of CAN busses that support this CAN message. If a vehicle continuously writes this CAN message on its CAN bus, it is recommended that you add the bus of that vehicle to the list.
    
---

## Step 3: Setting up Loggers

After identifying which signals should be logged in **Step 2 (browsing the OBD Library and adding entries to your library)**, the next step is to configure the device to actively log this data.

**Steps to Create a new Logger:**
1. Navigate to: Device → Loggers.
2. Click the **Create** button.
3. Select one of the available logger types:
    * **PID Logger** - used for logging PIDs via standard OBD-II communication.
    * **CAN Logger** - used for logging raw or decoded CAN bus messages directly from the vehicle network.
4. Fill out the mandatory fields.
5. Save. 

![Create New Logger](/img/getting_started/autopi_tmu_cm4/create_loggers/create_new_logger.png)

### Create PID Logger (Simpler)

Types:
* OBD-II PID
* Proprietary PID.

In order to create a PID Logger, you need to fill out these information: 

![Create PID Logger](/img/getting_started/autopi_tmu_cm4/create_loggers/create_pid_logger.png)

* **Basic information:**  
  * Select a **PID** - choose a PID you want to log. 
  * **Interval** - setup a interval on how often the logger log the data in seconds. 
  * **Enabled** - decide if you want this logger to be enabled or not. 

* **Advanced:** 
  * **[Converter](https://docs.autopi.io/core/services/core-services-obd-manager/#converters)** - alters the result of the Logger to give another output.
  * **[Filter](https://docs.autopi.io/core/services/core-services-obd-manager/#filters)** - filter the output that is send to returner. There are two options: 
    * `alternating_readout` - filter that only returns alternating/changed results.
    * `alternating_dtc` - filters out repeating Diagnostics Trouble Codes (DTCs).
  * **[Trigger](https://docs.autopi.io/core/services/core-services-obd-manager/#triggers)** - choose a trigger that can send an event.
  * **Returner** - choose a returner that sends data. We have a different default returners: 
    * `cloud_https`/ `cloud` - sending data to a http endpoint. 
        > **Note:** this setting defaults to AutoPi backend but can be changed in the advanced settings under Cloud storage. 
    * `cloud_jsonl` - publishing data to a Kafka broker.
    * `mqtt` - publishing data to your own mqtt server and is highly configurable. This can be configured in the Advanced settings > Cloud Storage. 
  * **Name override** - override name of the PID. This functionality is useful for when you want to test different loggers with the same name.
  * **Verify** - if enabled, it verifies the protocol on each request.

You can also read more about how to create PID loggers in depth in this guide: [Create PID Looggers](https://docs.autopi.io/cloud/obd-ii/create-pid-loggers/).

If you want to investigate the raw request and response messages of PID queries, you can read this guide: [Debug Raw PID Queries](https://docs.autopi.io/cloud/obd-ii/debug-raw-pid-queries/).

##### Default OBD-II PID Loggers
In the AutoPi Cloud, under the Loggers section, you will find a set of standard loggers preconfigured. These are particularly useful when working with a basic OBD-II vehicle and can help you get started with data logging quickly. If you have made changes to the loggers, you can always use the “Restore to Default” option to revert to the standard configuration.
The default OBD-II PID loggers available in the AutoPi Cloud include:
* Fuel level
* Coolant temperature
* RPM
* Speed 
* Get DTCs (Diagnostic trouble codes)
* Ambient air temperature
* Engine load
* Intake temperature
These standard loggers provide a solid baseline for monitoring common vehicle parameters.

### Create CAN Logger (Advanced)

> **Prerequisite:** Signals must exist in **My Library**.

![Create CAN Logger](/img/getting_started/autopi_tmu_cm4/create_loggers/create_can_logger.png)

In order to create a CAN Logger, you need to fill out these information: 
* **Signal** - pick the signal you want to use.
* **Enabled** - decide if you want this logger to be enabled or not. 
* **Bus** - specify the CAN Bus. This setting is prefilled based on the signal chosen. 
* Advanced: 
  * **Name override** - override name of the CAN signal. 

You can also read more about how to create CAN Logger in depth in this guide: [Create CAN Signal Loggers](https://docs.autopi.io/cloud/obd-ii/create-can-signal-loggers/).

There is also a possibility to listen for raw CAN data on the OBD port and log the RAW CAN messages, you can read more about that in this guide: [Log Raw CAN Messages](https://docs.autopi.io/cloud/obd-ii/log-raw-can-messages/).

### Bulk Configuration via Importing a DBC File/JSON File

If you prefer not to configure loggers individually, you can use the **DBC/JSON import functionality** available in the OBD Library - My Library. This approach is recommended when working with larger signal sets or standardized CAN databases, as it reduces manual setup and ensures consistency.

This method allows you to:
* Import a **DBC or JSON file** containing CAN message and signal definitions.
* Automatically parse and validate CAN frames and associated signals.
* Review all available signals before applying configuration.

**How to Import a DBC file:**
* Go to OBD Library/ My Library. 
* Click on Import.
    ![Import DBC/JSON file](/img/getting_started/autopi_tmu_cm4/create_loggers/import_dbc_file.png)
* Click on import file.
* Upload the file.
* Specify the content: CAN or PID.
* Name - choose the name if desired.
* Validate the file.
* Choose which CAN or PID you want to create and which ones you want to ignore. 
* Once you go through the file, click upload. Now all your chosen CAN or PID are uploaded to "My Library".
* Now you can find them in the table and by clicking on it you can specify which vehicle you want this to be associated to. 
* Save your changes.

Imported items will now be available for logger creation.

---

## Step 4: Link your Loggers to Your Dashboard 
For a widget to display data, it must be linked to the appropriate **logger**. If you add or edit loggers, you will also need to update the corresponding **dashboard widgets**.

Widgets can display data in several formats, including:
* Graphs
* Line charts
* State timelines
* Gauges ... 

You can also configure widgets to show **raw**, **average**, **minimum**, or **maximum** values depending on your needs.

After adjusting your widget settings:
1. Click **Save**.
2. Refresh the widget using the **circle icon** in the top-right corner.

If the data appears after refreshing, your configuration is correct. If you have just created a new logger, the device may need another **vehicle trip** before the required data is collected.

### Create a Widget 
To create a new widget:

1. Navigate to **Dashboard**.
2. Click the **Actions** button in the upper-right corner.
3. Select **Add widget**.
4. Fill out the required information.
5. Click **Save**.
6. Save your dashboard changes to apply the widget.

![Add a Widget](/img/getting_started/autopi_mini/create_mini_loggers/add_new_widget.png)

> **Note:** For a more detailed explanation of widget configuration, see this guide: [Configure the widget settings](https://docs.autopi.io/cloud/fleet_management/configurations/dashboards/#step-2-add-widgets-to-the-shared-dashboard).

> **Note:** When choosing the **Field**, the list only shows data that has already been received from the device. If the logger you are looking for is not in the list, the device may not be reading it. In this case, go to **Loggers**, enable the logger, or update its settings.

> **Note:** A logger must be configured beforehand, otherwise the widget will not have any data to display.

### Edit an Existing Widget 
To edit an existing widget:

1. Navigate to **Dashboard**.
2. Click the **two-dot icon** on the widget you want to update.
3. Make your desired changes.
4. Click **Save**.

![Configure a Widget](/img/getting_started/autopi_mini/create_mini_loggers/configure_widget.png)

> **Note:** Ensure the configuration, especially the **Field** section, matches the data being logged.

### Auto-Generate Widgets

The **Auto-generate** feature allows you to quickly create widgets based on the data received from the device. This saves time compared to creating each widget manually. Auto-generated widgets are based on **real data**, and you can adjust them afterward if needed (for example changing aggregation or visualization).

How to use Auto-generate:

1. Navigate to **Dashboard**.
2. Click the **Actions** button in the upper-right corner.
3. Select **Auto-generate**.
4. Make any desired changes.
5. Click **Save**.

> **Note:** By default, there is usually an **auto-generated dashboard** created for your device, which you can find in the **dashboard dropdown menu**.

When you are satisfied with your dashboard configuration, remember to **save your layout** through **Widget Actions** to keep your settings for future sessions.

---

## Summary

* Configure CAN Bus correctly first.
* Use OBD Library to define signals and PIDs.
* Create PID or CAN loggers depending on your needs.
* Link loggers to dashboards for visualization.

This setup allows you to build powerful data collection and monitoring workflows tailored to your vehicle.

---

## Data Troubleshooting(Autopi_tmu_cm4)

---

## Why Am I Not Seeing Any Data? 

If you've followed the [Getting Started Guide](/getting_started/autopi_tmu_cm4/index.md)
and tested your [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device during a drive, but aren't seeing any data
on the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management), this guide will help you identify and resolve common issues. 

This guide is organized as a checklist, detailing potential reasons why your vehicle
data might not be appearing on the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) Dashboard. It is intended for the
[AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device, for [AutoPi](https://www.autopi.io) Mini please see the [Mini guides](/getting_started/autopi_mini/index.md).  

![Dashboard](/img/getting_started/autopi_tmu_cm4/data_troubleshooting/no_data_dashboard.png)

## Common Causes and Solutions for Data Not Appearing on the [Cloud](https://www.autopi.io/software-platform/cloud-management)  

### 1. Connection Issues 

A common reason for missing data is a communication issue between your [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) 
device and the [Cloud](https://www.autopi.io/software-platform/cloud-management). If you’ve followed the Getting Started guide, this should 
typically not be a problem. However, it’s important to check the status of the 
LEDs on the side of the device to confirm it’s communicating with the [Cloud](https://www.autopi.io/software-platform/cloud-management) and hasn’t entered sleep mode. 

- **LED Status**: Both the green and blue LEDs should be lit solid and bright. 
    If the blue LED is “breathing” (varying brightness from dim to bright), 
    the device is in sleep mode. 
- **To Resolve**: Disconnect the device from the OBD-II port, then reconnect it.
    Wait until both LEDs are solid before proceeding.

For more details on LED status meanings, refer to [this guide](/core/power_management/#status-leds).

![CM4 LED status meaning](/img/getting_started/autopi_tmu_cm4/data_troubleshooting/cm4_light_placements_01.png)

### 2. Internet Connectivity Issues 

Ensure your device is connected to the internet. If there are connectivity issues,
follow the steps outlined in our [4G Internet Setup and Troubleshooting Guide](/getting_started/autopi_tmu_cm4/4g-internet-setup-troubleshooting).

### 3. CAN Bus Creation 

When the device boots for the first time, it attempts to autodetect the 
communication protocol and sends the results back to [AutoPi](https://www.autopi.io), where a CAN Bus is 
created for your device.

- **Check for CAN Bus**: Go to Vehicles > Choose Device > Settings > Vehicle Editor 
    to see if the CAN Bus has been created.
- **Manual Configuration**: If the CAN Bus wasn’t created automatically, you might 
    need to configure it manually. For assistance, refer to this [guide](/cloud/obd-ii/can-bus-configuration).

![Change device settings](/img/getting_started/autopi_tmu_cm4/data_troubleshooting/device_settings.png)

### 4. Loggers Creation

To view data on the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) Dashboard, you need to create Loggers to collect
the data via your [AutoPi](https://www.autopi.io) device. 

- **Setting Up Loggers**: Loggers can be configured to communicate on the CAN Bus
    and capture the necessary data. They can be set up using PIDs or CAN messages,
    depending on your vehicle's communication type. 
- **Accessing Loggers**: Navigate to the Devices section of the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management), 
    select your device, and find Loggers. Some default loggers may already be 
    available and should display data in the Dashboard widgets. However, 
    depending on your vehicle, you may need to create custom loggers. 
- **Explore OBD Community Library**: You can check the OBD Community Library for
    loggers that have been created for your specific vehicle model and year. 

![Create Loggers](/img/getting_started/autopi_tmu_cm4/data_troubleshooting/loggers.png)

For more information on creating Loggers, visit our [OBD-II Introduction Guide](/cloud/obd-ii/). 
Additional documentation on CAN and PID configuration can be found under the 
OBD-II dropdown in the [Cloud](https://www.autopi.io/software-platform/cloud-management) section of our documentation. 

When everything is configured correctly you should be able to see your data 
displayed in the form of widgets on the Dashboard by navigating to Vehicles > Dashboard.

### 5. Configuring Widgets

![Successful dashboard](/img/getting_started/autopi_tmu_cm4/data_troubleshooting/successful_data_dashboard.png)

After setting up your loggers, you'll be able to view your data on the dashboard.
Each widget in the dashboard offers controls in the top-right corner: 

- **Circle icon**: Refreshes the widget's data. 
- **Three dots icon**: Opens the configuration options for the widget. 
- **X icon**: Removes the widget. Feel free to remove any default widgets that aren't relevant to you.

![Configurinyyg widget](/img/getting_started/autopi_tmu_cm4/data_troubleshooting/configuration_widget.png)

To customize how your data is displayed, click the three dots on a widget. 
This will take you to the configuration settings, where you can choose different 
display formats such as graphs, line charts, gauges, and more. You can also set 
the widget to show data averages, minimums, or maximums. 

:::note
If your widget shows "No data," it's often due to an incorrect configuration—especially 
in the 'Field' section. Ensure the widget's settings align with the configuration
of the logger that collects the data for that field. 
:::

After updating your widget settings, click **Save**, then refresh the widget using 
the circle icon to check if data appears. If you see the data, the configuration 
is correct. To make sure your changes are saved for future use, click 
**Widget Actions** and select **Save**.

![Widget actions](/img/getting_started/autopi_tmu_cm4/data_troubleshooting/widget_action.png)

To add a new widget to your dashboard, go to **Widget Actions** and choose 
**Add Widget**. Remember, a logger must be set up beforehand, or the widget 
won't have any data to display. 

When you're satisfied with your dashboard configuration, save your layout via 
**Widget Actions** to keep your settings for future sessions. 

For more detailed information on widgets, see [Link Your Loggers to Your Dashboard](https://docs.autopi.io/getting_started/autopi_tmu_cm4/create-loggers-cm4/#step-4-link-your-loggers-to-your-dashboard).

---

## Getting Started(5)

---

Welcome to AutoPi! 
 
This step-by-step guide will help you set up your AutoPi TMU CM4 4G/LTE Edition. 
The device comes pre-assembled with the SD card inside and requires just a few steps to complete the installation.

:::note

**Important Notes Before You Start**

The AutoPi Telematics Unit is a highly customizeable and technical device. It contains a direct
interface to your car and communicates with the ECU in your car.

1. **Power Off the Vehicle**: When inserting the device for the first time, ensure that the vehicle is powered off.
2. **Vehicle Must Be Parked**: When working on and customizing your device, make sure your vehicle is in the parked position.
3. **Do Not Remove the AutoPi While Driving.**
4. **Power Source**: The device can only be powered through the OBD-II port.
     Powering the Raspberry Pi directly is not supported and may cause issues.
5. **Advanced Settings Caution**: When updating the Advanced settings, ensure you understand what you
     are doing, as changes can affect the performance of your car and its battery.  
:::

## 1. Setting Up User Account

Once you have received your AutoPi device it is important to associate it with Cloud Platform.
Go to [my.autopi.io](https://my.autopi.io/) and click “Sign up”. In the pop-up, 
add the e-mail address you want to associate with your account and create a password. 
You can also expand the form to add additional details like your country and full name, 
though this can be done later. Click “Create account”.

![AutoPi sign up](/img/getting_started/getting_started/sign_up.png)

## 2. Register Your Device

After creating an account, you can access the Cloud Platform features for fleet and device management.
The next step is to register your device to unlock the platform’s full potential.  

To add a device to your account, follow one of these methods:  

**Option 1: Via Device Management**
1. See the “Device Management” section of the Platform. 
2. Click on “Devices”. 
3. Find and click the “Register Device” button in the upper right corner. 

**Option 2: Via the Accounts Tab**
1. Navigate to the “Accounts” tab at the bottom of the left side menu on the Platform.
2. Select “Devices”. 
3. Locate and click the “Register Device” button in the upper right corner.

After clicking the “Register Device” button, the registration tab will appear. Enter all necessary information: 

![Register Device](/img/getting_started/getting_started/register_new_device.png)

- **Unit ID**: This is the number on the side of your device. You can also find it in the.
    document attached in the email you received when the device was shipped. 
- **Vehicle Information**: Optionally include the make, model and year of the vehicle.
- **Vehicle Type**: Choose the type of vehicle (ICE, Battery [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini), Hybrid [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini), or Plug-in Hybrid [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini)).

Once all information is entered, click the “Register Device”. Your newly registered device 
will now appear in the list under “Vehicles” in the Fleet Management section and under 
“Devices” in the Device Management section of the Platform.

## 3. Ensure SIM Connectivity

:::note
If you have purchased the AutoPi TMU CM4 with monthly cloud subscription, 
your SIM card is already assembled in the device, so you can skip this step. 
:::

If you have purchased the hardware-only version, you will need to insert your SIM card 
into your AutoPi before connecting the device to your vehicle. The AutoPi uses nano SIM sizes. 
The location of the SIM card slot is shown in the picture below.  

When inserting the SIM card, it’s important to ensure it is installed correctly. 
The picture below shows the proper orientation of the SIM card. 
Please note that the text side of the SIM card must face up and the “triangle” end point into the device. 

![AutoPi.io - SIM card location](/img/getting_started/getting_started/sim_card.png)

:::caution
**Please notice:** When the SIM card is inserted correctly, you will hear a small "click" when the
card is in position. Don't try do force the SIM out after the click as this will damage the device.
Make sure the orientation is correct before inserting the SIM. Wrong orientation could potentially
damage your device.
:::

:::caution
**Please notice:** The SIM card needs to be compatible with ipv4, for the device to establish a 4g/LTE connection. 
:::

Here's a list of the US based SIM providers that we recommend to be used with the AutoPi:
1. AT&T
2. T-Mobile
3. Any MVNO provider that is roaming the networks of the providers above

## 4. Locate OBD Port

Next step is to locate your OBD port in your car, it is usually found underneath the dashboard and
looks something like this:

  ![AutoPi.io - OBD port](/img/getting_started/getting_started/obd_location.jpg)

The location of the OBD port varies from make and model, but is typically fund in one of the
locations shown below:

![AutoPi.io - OBD port location](/img/getting_started/getting_started/TMU_placement_dashboard_v1_finecut-01.jpg)

## 5. Installation

When installing the AutoPi, always make sure that the device is positioned with 
the logo facing upwards towards the sky. This orientation is crucial because the GPS antenna 
is located within the device, and incorrect positioning may result in a weak GPS signal. 

If the OBD port is in an inconvenient spot or gets in the way, 
you can buy an [extension cable](https://shop.autopi.io/products/obd-ii-extension-cable) 
to move your AutoPi to a better location. You can also use a holder or a 
[velcro strip](https://shop.autopi.io/products/dual-lock-extreme-velcro) to secure it 
on the side or underneath — just make sure the logo is still facing upwards.

This is the OBD-II extension cable:

![AutoPi.io - Relocator cable](/img/getting_started/getting_started/relocator_cable.png)

Velcro Strip:

![AutoPi.io - Relocator cable](/img/getting_started/getting_started/velcro_strip.png)

**Tips on getting the best performance of your device**:

- Make sure that the AutoPi logo is facing the sky.
- Try to avoid installing the device in direct sun. Direct sun will heat up the device and,
  in the summertime, this can cause the CPU to throttle down, if the temperature gets too hot.  
- The device contains a GPS antenna inside. 
  Make sure there is no metal covering the device as this can affect its performance. 
- When powering the device, make sure you only power it through the OBD connector.
  The device cannot be powered through any of the other ports. 

## 6. Connect to device WiFi hotspot

After installing your AutoPi device into the OBD port, you will need to connect it to the AutoPi Cloud.
To do this, you will temporarily use the device’s Wi-Fi hotspot. 

The hotspot is named autopi-XXXX, where "XXXX" represents the unique ID of your device.
The **password** for this Wi-Fi hotspot is the **first 13 characters of your Device ID**. 
You can find your Device ID either by navigating to Devices > Select your device > Overview: Device specifications; or in the documentation attached to your shipping email. 
Additionally, you can access Wi-Fi information directly from the AutoPi Cloud. 
To do this, navigate to Devices > Select Your Device > Advanced Settings > Wi-Fi. 
Here, you will find the Wi-Fi hotspot's password and SSID credentials. 

![Advanced Settings - Wifi](/img/getting_started/getting_started/wifi_settings.png)

When the device is powered on, a blue light will appear on the side, indicating 
that it has power. When the device successfully connects to the AutoPi Cloud, 
a green light will be visible. If the device is not connected, the light will be flashing. 

For a detailed description of the two status LEDs, please refer to the [full description](/core/power_management/#status-leds).

## 7. Connect to Local Administration

:::note
If you’ve purchased the AutoPi TMU CM4 with a monthly cloud subscription, your SIM card
is pre-installed in the device, and no additional action is required for SIM connectivity. 
The APN settings are already configured for you. Please be aware that the SIM card 
has a monthly data cap, so it's recommended to limit the use of the device’s hotspot 
for connecting your phone or notebook.
:::

:::note
If you need to know the APN string for the pre-installed SIM card, it is **nxt20.net**. 
:::

:::note
If you are using a **Verizon Wireless** SIM card, please follow the dedicated setup guide:
[Setting Up Your Device with Verizon Wireless](https://docs.autopi.io/developer_guides/setting-up-a-device-with-verizon-wireless/).
:::

If you are using your own SIM card, you may need to configure the APN settings after 
connecting to the device’s Wi-Fi hotspot to ensure a seamless 4G/LTE connection. 
However, setting up the APN is not always necessary—it depends on your SIM provider. 
We suggest checking with your SIM provider directly or searching online for the correct APN settings. 

Here’s how you configure the APN settings: 

1. Go to my.autopi.io. If you're already logged in, please log out. 
2. On the login page, find the “Go Local” button at the bottom left side, 
   or alternatively, go directly to local.autopi.io.

    

This will connect you to the local device, and you should see a screen similar to 
the one shown in the image below, indicating that you're connected locally.
From here, you can log in without needing a username or password.

![AutoPi.io - Localhost login](/img/getting_started/getting_started/local.jpg)

Once the information is saved, it will be applied to the device, and you should 
see a notification when successfully saved. 

### 4G/LTE Settings
![AutoPi.io - Settings Page](/img/getting_started/getting_started/apn_settings.png)

### APN Presets List
![AutoPi.io - Settings Page](/img/getting_started/getting_started/apn_settings_list.png) 

## 8. Verify Connectivity

To verify that you have set up your APN settings correctly, connect your phone 
to the AutoPi hotspot and use your browser to visit any webpage. 
If the page loads successfully, it means your device is online and has 
started uploading data to the AutoPi Cloud.

## 9. Finalization

Your device is now online and connected to the AutoPi Cloud. After completing 
the setup, it's important to change your device's WiFi password. 
The default password is intended for one-time use only, and it is strongly 
recommended to update it afterward. You can change the password through the 
AutoPi Cloud by navigating to **Devices** > **Advanced Settings** > **Wi-Fi** > **Pass**. 

To prevent excessive data usage, it's advisable to avoid using the device’s 
hotspot to connect your phone or tablet after the initial configuration is complete. 

**You Are All Set!**

Congratulations! You've successfully set up your AutoPi device and connected it 
to the AutoPi Cloud. Your device is now ready to start gathering and transmitting data,
enabling you to take full advantage of the powerful features AutoPi offers. 
Take your device for a trip to start gathering data.

:::note
If you are getting started with you DiY Edition please refer to this guide 
[Setup Your TMU DIY Edition](/hardware/legacy_devices/autopi_dongle_gen3/setup_your_tmu_diy_edition.md).

For older, Generation 2 devices, you can find the relevant guide here
[Setup Your Gen 2 Edition](/hardware/legacy_devices/autopi_dongle/setup_your_gen_2_diy_edition.md).
:::

---
**What's Next?**

Now that your device is up and running, here are a few suggestions to help you 
get the most out of your AutoPi experience: 
- **Explore the AutoPi Cloud**: Dive into the AutoPi Cloud platform to explore all 
  the features available to you, such as real-time vehicle monitoring, 
  advanced analytics, and customizable alerts. 
- **Check Out Our Documentation**: Our [documentation page](https://docs.autopi.io/) 
  is a great resource for learning more about advanced features, troubleshooting, 
  and getting the most out of your device. 
- **Build your Nested Accounts and Invite New Users**: AutoPi Cloud uses a multi-tenant architecture, which means multiple accounts (tenants) share the same platform and infrastructure, while all data, configurations, and user access remain securely isolated. You can read more here: [Account management](https://docs.autopi.io/cloud/accounts/).

---

## Getting Started(6)

---

[AutoPi](https://www.autopi.io) supports a wide range of electric vehicles ([Electric Vehicle](https://www.autopi.io/hardware/autopi-mini)s) by providing advanced telematics and
data analysis capabilities that enhance the functionality and management of [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini)s. The
supported library of [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini)s can be found here: [supported EVs](https://www.autopi.io/electric-vehicles/).

Getting started with AutpPi devices on [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini)s follow the same setup as Internal combustion engine vehicles.
Please follow the guides below to get started:

- [AutoPi](https://www.autopi.io) TMU CM4: [getting started guide](/getting_started/autopi_tmu_cm4/index.md).
- [AutoPi](https://www.autopi.io) mini: [getting started guide](/getting_started/autopi_mini/index.md).

![Electric vehicle graphic](/img/getting_started/electric_vehicles/intro/electric_vehicle_graphic.png)

---

## Power Cycles

---

The AutoPi dongle is initially configured to be powered on when the engine of the vehicle is
running. When the engine is not running, a sleep timer is created to put the dongle to sleep after
5 minutes or whatever configured.

Behind the scenes this works by using [engine events](/cloud/device_management/events/cloud-events-vehicle/#engine-events).
Engine events are triggered based on the RPM values continuously read from the vehicle. For all
non-BEVs (Battery [Electric Vehicle](https://www.autopi.io/hardware/autopi-mini)s) this is setup automatically as default because they all
support readout of engine RPM in the same way according to the OBD-II PID standard
(SAE J1979).

Unfortunately, this is not as simple for BEVs. Here there is no standard and data is read out in
different ways between makes and models. Two approaches are available:

1. if your vehicle can respond to PID requests and/or 
2. if your car continuously delivers data on a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus.

## Setup a PID Logger Using the `rpm_motor_event` Trigger
This option can be used if your vehicle can respond to PID queries.

**Precondition:** A PID which on request delivers an RPM value related to the movement of the
vehicle. It could be the RPM of an electric motor, a spinning wheel etc. If you do not know of such
a PID for your model, you can always check the *Community Library* on https://my.autopi.io.

:::note Important
The PID must be named 'RPM' or else the `rpm_motor_event` trigger will skip checking the value.
:::

Go to **Device** > **Loggers** > **Create** > **PID**. Choose your RPM PID and be sure to
select the *rpm_motor_event* trigger.

![Setting up RPM based PID logger](/img/getting_started/electric_vehicles/power_cycle_for_electric_vehicles/setting_up_rpm_based_pid_logger.png) 

After the logger has been synced to your device, and the service has been restarted, you should
start seeing motor events in the **Device** > **Events** page.

[Click here for documentation on motor events](/cloud/device_management/events/cloud-events-vehicle/#motor-events).

## Setup a PID Logger Using the `communication_event` Trigger

This option can be used if you do not have a PID capable of delivering RPM data, but instead have
another arbitrary PID that delivers data when the vehicle is moving or active. The actual content
of the PID response is irrelevant for this trigger to function.

**Precondition:** A PID which on request delivers data when the vehicle is active and no response
when the vehicle is inactive. If you do not know any PID to use, you can always check the
*Community Library* on https://my.autopi.io.

**Note:** There is no restriction on specific naming of the PID.

Go to **Device** > **Loggers** > **Create** > **PID**. Choose your arbitrary PID and be sure
to select the `communication_event` trigger.

![Setting up communication based PID logger](/img/getting_started/electric_vehicles/power_cycle_for_electric_vehicles/setting_up_communication_based_pid_logger.png) 

[Click here for documentation on communication events](/cloud/device_management/events/cloud-events-vehicle/#communication-events).

Next step is to re-configure the sleep timer functionality to use communication events instead of
the default engine/motor events. Go to **Device** > **Advanced Settings** > **Power** and change the three
values:

**Sleep Timer** > **Event Driven** > **Event Regex:** `^vehicle/communication/disconnected`

**Sleep Timer** > **Event Driven** > **Reason:** `vehicle_communication_disconnected`

**Sleep Timer** > **Suppress** > **Event Regex:** `^vehicle/communication/established`

As shown below:

![Change events 1](/img/getting_started/electric_vehicles/power_cycle_for_electric_vehicles/change_events_1.png) 

...

![Change events 2](/img/getting_started/electric_vehicles/power_cycle_for_electric_vehicles/change_events_2.png) 

After all the changes have been synced to your device, and the service has been restarted, you
should start seeing communication events and also `system/sleep_timer` events in the
**Device** > **Events** page.

## Setup a PID Logger Using a Custom Trigger

**Caution:** This option is recommended for expert users only.

Instead of using one of the built-in triggers you can provide your own implementation which also
can fire your own custom events. The setup procedure is the same as in the example above except
that the trigger used is custom. See how to create a custom trigger
[here](/cloud/device_management/services/create-custom-triggers/).

## Setup a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Logger Using the `rpm_engine_event` Trigger

This option can be used if your vehicle continuously produces data on a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus while
active/driving.

**Note:** At the time of writing, this approach can only make use of the `rpm_engine_event` trigger
and thus produce engine events,
[click here for documentation on engine events](/cloud/device_management/events/cloud-events-vehicle/#engine-events).

**Precondition:** A [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message mapping for your specific vehicle which contains an RPM signal. If
you do not know any [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages for your vehicle, you can always check the *Community Library*
on https://my.autopi.io.

The following example shows how an RPM signal can be found in the *Community Library* for vehicles of the make Alfa Romeo. 
Go to **OBD Library** > **Community Library** and specify *Make*:

![Community library](/img/getting_started/electric_vehicles/power_cycle_for_electric_vehicles/community_library_screenshot.png) 

Click on the *RPM* signal and in the pop-up window click on the button *Add to my library*. You have
now added the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message to your library, and you can use it for logging.

Next step is to setup a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) logger for the RPM signal. Go to **Device** > **Loggers** >
**Create** > **CAN** and choose the RPM signal:

![Setting up CAN signal logger](/img/getting_started/electric_vehicles/power_cycle_for_electric_vehicles/setting_up_can_signal_logger.png) 

:::note Important
The [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal must be named 'RPM' or else the `rpm_engine_event` trigger will skip checking the
value.
:::

After the logger has been synced to your device, and the service has been restarted, you should
start seeing engine events in the **Device** > **Events** page.

---

## Getting Started(Heavy_duty_vehicles)

---

This guide will show how to retrieve data from a vehicle supporting the J1939 protocol. To read more background information about J1939 please see the blog post: [J1939 Explained](https://www.autopi.io/blog/j1939-explained/)

## Preconditions
Before proceeding the [AutoPi](https://www.autopi.io) device must be:

  1. Connected to the vehicle with an appropriate OBD-II adapter cable that connects the vehicles two J1939 [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus wires to pin 6 (high) and 14 (low) of the OBD-II connector on the [AutoPi](https://www.autopi.io) device. If you are missing an adapter cable for your specific vehicle please contact sales@autopi.io.
  2. When initially inserting the device, make sure that the vehicle is powered off.
  3. Powered on and online in the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) at https://my.autopi.io.
  4. Also the ignition of the vehicle must be turned on to ensure the J1939 [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus is active.

## Determining the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus protocol
First step is the determine the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus protocol used for the connected vehicle (if you dont already know it). A few steps is required here:

  1. Remove all existing loggers on the device (make sure the changes are synced to the device). This can be done here: https://my.autopi.io go to _Devices_ > _Select Device_ > _Loggers_. You want to remove these, so that they dont interfere with the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus already.
  2. Remove all existing [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) busses on the vehicle. From the same page click the _Settings_ button in the top right corner. Click the _Vehicles Editor_ and remove the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) busses configured in the bottom of the popup. 
  3. Configure the vehicle for 24V operation (if its a 24V truck). You can do this on the vehicles editor page that you are add, by clicking the _Nominal Voltage_ dropdown. 
  4. You are now set to start the testing for the right [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus configuration.

You need to make sure the device is powered on, have good internet connection and that the engine of the vehicle is running. You can do so by following these steps:

  1. From terminal in the right hand side screen, run the following command: 
    ```python 
    test.ping
    ```
  It should return `true` if the device is online and connected to the [Cloud](https://www.autopi.io/software-platform/cloud-management).

  2. Again from the terminal run the following command: 
    ```python 
     obd.battery
     ```
    This command command will return the Voltage of the Auxilirary battery in the vehicle. If its a 24V type of battery you should see a value somewhere between 25-28V. If its close to 25V it means the engine is not running. If its closer to 28V it means the engine is running and ECU's are powered up. A good indicator is a value above 26.5V.

With these checks passed you can now continue to find the protocol and baudrate settings. With the vehicle's engine running, first try to listen to passive [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) traffic. One of these commands should show some data (raw). Once you find which command returns data, note down the protocol and baudrate for this vehicle:
```python 
  - obd.monitor duration=5 verify=False protocol=32 baudrate=500000
  - obd.monitor duration=5 verify=False protocol=32 baudrate=250000
  - obd.monitor duration=5 verify=False protocol=32 baudrate=125000
  - obd.monitor duration=5 verify=False protocol=31 baudrate=500000
  - obd.monitor duration=5 verify=False protocol=31 baudrate=250000
  - obd.monitor duration=5 verify=False protocol=31 baudrate=125000
  - obd.monitor duration=5 verify=False protocol=52 baudrate=500000
  - obd.monitor duration=5 verify=False protocol=52 baudrate=250000
  - obd.monitor duration=5 verify=False protocol=52 baudrate=125000
  - obd.monitor duration=5 verify=False protocol=51 baudrate=500000
  - obd.monitor duration=5 verify=False protocol=51 baudrate=250000
  - obd.monitor duration=5 verify=False protocol=51 baudrate=125000
```

To determine whether any of the raw data is J1939, you can do 1 of 2 things:
  1. Check on the [Cloud](https://www.autopi.io/software-platform/cloud-management) whether there is any data coming in. Note, that you would only be able to see this if the protocol configuration of the device matches that of the vehicle.
  2. Look for the EEC1 frame. If the vehicle supports J1939, it will almost certainly have this. In the data returned by the monitor command, look for a frame where the 3th to 6th characters are `F004`. For example, if the full frame is `18F0040012AB331288112244`, you can see `F004` at the beginning.

### Determining if the vehicle responds to J1939 VIN queries:
If you've found the protocol, baudrate combination which works, use the same combination to check for the VIN query. Run the following command. It should return the VIN string for the vehicle:
```python 
obd.query vin mode=FEEC pid=x00 header=18ea00f9 formula='str(message.data)' verify=false force=true protocol=<PROTOCOL> baudrate=<BAUDRATE>
```

## Check for Broadcast Data via the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Bus sniffer
As most J1939 messages are broadcast we start by checking if we can see any data on the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) bus.

On https://my.autopi.io go to _Devices_ > _Select Device_ > _CAN Analyzer_ > _Sniffer_.

Select one of the following J1939 protocols that fits your vehicle in regards to 11bit or 29bit header:
  - `[41] J1939 (11bit, 250kbps)`
  - `[42] J1939 (29bit, 250kbps)`

**Optional:** Change the baud rate if predefined value of `250000` is incorrect. `500000` is a typical alternative.

Click the _Sniff_ button to start recording [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages sent on the J1939 bus. An example of a recording result is shown in below screenshot.

:::note
The start and end of the recording are indicated audibly with loud beep sounds played by the [AutoPi](https://www.autopi.io) device.
:::

_Example_:

![j1939_can_sniffer](/img/getting_started/heavy_duty_vehicles/j1939_getting_started_guide/j1939_can_sniffer.png)

If no data is returned, try:
  1. Change the protocol and/or baud rate combinations.
  2. Increase the recording duration from default `1` to `10` seconds.
  3. Continue to the next section describing how to query for data.

## Query for Data via PID tester tool
Some data is only available on request. This means a J1939 request message must be sent in order to get a data response. This can be done using the PID tester tool.

In the _CAN Analyzer_ select the _PID Tester_ tab.

First the J1939 protocol and baud rate must be specified in the same way as described previously.

Next the J1939 request message must be specififed. It consists of a header and a data part. 

>**Header:** `18 EA 00 F9` is broken down into:
>
>  - `18` contains priority of 6.
>  - `EA 00` is PGN 59904 (Request PGN).
>  - `F9` is source address 249 (Service Tool).
>
>**Data:** `00 C1 00` is the specific PGN that is requested. In this example PGN 49408 (Diagnostic Readiness 2).

_Example_:

![j1939_pgn_query](/img/getting_started/heavy_duty_vehicles/j1939_getting_started_guide/j1939_pgn_query.png) 

In above screenshot we query PGN 61444 (Electronic Engine Controller 1) which among other values contains SPN 190 (Engine Speed).

## Register Vehicle Bus
Once a J1939 bus has been identified and tested, it is recommended to register it on the vehicle's profile.

Go to _Devices_ > _Select Device_ > _Settings_ > _Vehicles Editor_ and click on _Create_ button below _CAN Buses_. Fill in the relevant values for name, protocol and baud rate.

_Example_:

![create_j1939_vehicle_bus](/img/getting_started/heavy_duty_vehicles/j1939_getting_started_guide/create_j1939_vehicle_bus.png)

## Register PID for Request PGN
This section may be skipped if you only receive broadcast J1939 messages. But if you need to query for a specific PGN 
it is recommended to register the request PGN as a PID in the _OBD Library_. It can then later be used to easily set up loggers.

Go to _OBD Library_ > _Create_ > _PID_.

Enter the informations previously verified using the _PID Tester_.

_Example_:

![create_pid_for_j1939_request_pgn](/img/getting_started/heavy_duty_vehicles/j1939_getting_started_guide/create_pid_for_j1939_request_pgn.png)

#### PID Details

>**Name:** Short name of the PGN requested.
>
>**Description:** Optional description of the PGN requested.
>
>**Mode:** Hexadecimal value `00` is specified here.
>
>**Code:** The hexadecimal representation of the requsted PGN number 61444 (Electronic Engine Controller 1).
>
>**Header:** The header to request a PGN:
>
>  - `18` contains priority of 6.
>  - `EA 00` is PGN 59904 (Request PGN).
>  - `F9` is source address 249 (Service Tool).
>

:::note
It is recommended to specify how many messages/frames are expected to be returned by the query. This is done by unfolding the section _Enhanced PID_ and entering the number of messages under _Frames_. This helps reduce the total query time (better performance) because the waiting timeout for the last message is skipped.
:::

#### Used by Vehicle(s)

>**Vehicle Bus(es):**  Specify which bus(es) the PID is to be associated with. The previously created J1939 bus is selected.

## Decode Messages (with DBC file)
After receiving the raw J1939 [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages they must be decoded to get the actual measurement values. This can be done using the built-in CAN database functionality.

The [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) database contains definitions of how the individual [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages are structured. Each [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message can consist of one or more [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals, each of which typically contains a single measurement value (eg. temperature, speed, RPM or the like).

As an exmaple, the J1939 PGN 61444 (Electronic Engine Controller 1) contains 8 SPNs in total. It can be mapped to a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message with 8 [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals as shown below.

```
PGN 61444 (Electronic Engine Controller 1)                            --->  CAN message
  SPN 899 (Engine Torque Mode)                                        --->    CAN signal #1
  SPN 899 (Engine Torque Mode)                                        --->    CAN signal #2
  SPN 4154 (Actual Engine - Percent Torque)                           --->    CAN signal #3
  SPN 512 (Driver's Demand Engine - Percent Torque)                   --->    CAN signal #4
  SPN 513 (Actual Engine - Percent Torque)                            --->    CAN signal #5
  SPN 190 (Engine Speed)                                              --->    CAN signal #6
  SPN 1483 (Source Address of Controlling Device for Engine Control)  --->    CAN signal #7
  SPN 1675 (Engine Starter Mode)                                      --->    CAN signal #8
  SPN 2432 (Engine Demand – Percent Torque)                           --->    CAN signal #9
```

When all (or only a few selected) [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages have be defined they will need to be synchronized to the [AutoPi](https://www.autopi.io) device and stored in the form of a DBC file. The synchronization is handled automatically by to [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) management system. Using this DBC file, the [AutoPi](https://www.autopi.io) device can decode raw [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages into readable measurement values. The decoded data can then be uploaded to the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management), stored locally or sent to any custom endpoint.

### Create Mapping 

To create a mapping for a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message to be be decoded go to _OBD Library_ > _Create_ > _CAN_.

_Example_:

![create_j1939_can_message](/img/getting_started/heavy_duty_vehicles/j1939_getting_started_guide/create_j1939_can_message.png) 

In above screenshot, we register a [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message mapping for PGN 61444 (Electronic Engine Controller 1):

#### [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Message

>**Name:** Short name to identify the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message.
>
>**Description:** Optional description of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message.
>
>**Header:** [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message header for PGN 61444:
>
>  - `8C` contains priority of 6 but has no actual significance.
>  - `F004` is the hexadecimal representation of PGN number 61444.
>  - `FE` is source address 254 (Null Address) but has no actual significance.
>
>**Bytes:** 8 is the number of data bytes that the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message contains.
>
>**Sender:** Identifier of the ECU that sent the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message. Enter `XXX` or similar if unknown.

#### [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Signal #1

In the above screenshot we only show how to map SPN 190 (Engine Speed) but the procedure the same when adding more.

>**Name:** Short name to identify the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal.
>
>**Description:** Optional description of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal.
>
>**Endian:** Sequence of bytes is little-endian - least significant bits first.
>
>**Start:** Bitwise start index of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal value within the data part of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message. When it comes to big-endian indexing is straightforward, but for little-endian it is more complex.
>
>**Length:** Bit length of the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signal value.
>
>**Sign:** Unsigned integer value - no negative values.
>
>**Factor:** A factor of `0.125` to be multiplied by the value in order to get the actual measurement value.
>
>**Offset:** No offset to be added to the value.
>
>**Unit:** Unit of the value is RPM (Revolutions per minute).
>
>**Min:** The maximum possible value is undefined.
>
>**Max:** The minimum possible value is undefined.
>
>**Receivers:** Identifiers for ECUs that use the signal value.

#### Used by Vehicle(s)

>**Vehicle Bus(es):**  Specify which bus(es) the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message is to be associated with. The previously created J1939 bus is selected.

### Sync DBC File

After the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message has been created, it must be synchronized to the [AutoPi](https://www.autopi.io) device. This is done in the same way as all other changes; applied immediately on request if the device is online or queued and applied the next time the device is back online.

When synchronizing, the [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages are stored in one or more DBC files located on the file system below the path:

```
/opt/autopi/obd/can/db/protocol_<ID>.dbc
```

A separate DBC file is created on the device for each associated vehicle bus protocol. 
In the above example, protocol `[42] J1939 (29bit, 250kbps)` is used. Therefore, the synchronized DBC file will be found at: `/opt/autopi/obd/can/db/protocol_42.dbc`

:::note
As default, all created [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages and associated [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals are synchronized to the DBC file. But if one or more [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals
are used in loggers only the used [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) signals and [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages are included in the DBC file.
:::

### Test [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) Converter

To easily test [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) message conversion with a DBC file, the following terminal command can be executed. It performs a single workflow that queries a PGN and then converts the raw response message using the DBC file.

```
obd.manage run handler="query" \
args="['EEC1']" \
kwargs='{"mode": "00", "pid": "F004", "header": "18EA00F9", "force": true}' \
converter="can"
```

_Example_:

![create_pid_for_j1939_request_pgn](/img/getting_started/heavy_duty_vehicles/j1939_getting_started_guide/run_j1939_query_workflow.png)

#### Command Breakdown
```
>_**obd.manage**_ is the [command](/core/commands/core-commands-obd/#obdmanage) to execute.
>
>_**run**_ a [workflow](/core/services/core-services-intro/#workflows) directly.
>
>_**handler="query"**_ specifies the handler of the workflow to be called.
>
>_**args="['EEC1']"**_ specifices the arguments of the handler. The value consists of an embedded JSON array.
>
>_**kwargs={{"mode": "00", "pid": "F004", "header": "18EA00F9", "force": true}}**_ specifices the keyword arguments of the handler. The value consists of an embedded JSON dictionary.
>
>_**converter="can"**_ specifies a converter in the workflow to be called after the handler. Here we use the [CAN](/core/services/core-services-obd-manager/#can) converter.
```

## Setup Loggers

To receive the J1939 data in the [Cloud](https://www.autopi.io/software-platform/cloud-management), loggers must first be set up on the device. Go to _Device_ > _Loggers_ and create loggers 
for the respective PIDs and or [CAN](https://www.autopi.io/hardware/autopi-canfd-pro) messages. After a logger has been created, it must be synchronized to the [AutoPi](https://www.autopi.io) device, just like any other change.

---

## Using DIMO Device on AutoPi's Cloud

If you have a [DIMO x AutoPi device](https://drivedimo.com) and would like to use it on the [AutoPi Cloud platform](https://my.autopi.io/#/login), this guide will walk you through the full migration process. You will learn how to transition your device from the DIMO server to AutoPi's server and unlock all AutoPi Cloud features.

## Prerequisites

Before beginning, ensure you have:

- A DIMO x AutoPi device.
- Access to your device's physical location (for setup and reflashing).
- An email address for creating your AutoPi account.

## Step 1: Order an AutoPi SIM Card

Start by ordering a Global SIM card from the AutoPi Shop: **[Order SIM Card Here →](https://shop.autopi.io/products/global-sim-card-solution)**

The subscription cost is **€6 per month**, which includes both data usage and full access to the AutoPi Cloud platform.

## Step 2: Create Your AutoPi Account

Go to [my.autopi.io](https://my.autopi.io/) and click "Sign up." In the pop-up,
add the email address you want to associate with your account and create a password.
You can also expand the form to add additional details like your country and full name,
though this can be done later. Click "Create account".

![Sign Up](/img/getting_started/dimo/sign_up.png)

For more details, see: [Setting up a User Account](https://docs.autopi.io/getting_started/autopi_tmu_cm4/#1-setting-up-user-account)

Save your login email address; you will need it in the next step.

## Step 3: Contact AutoPi Support

Open a support ticket with AutoPi by sending an email to **support@autopi.io**  or through the support form in the AutoPi Cloud platform and provide the following information:

- Confirmation of your SIM card purchase.
- Your device ID (found on the sticker on the side of your device).
- The email address you used to create your AutoPi account.

This allows AutoPi's team to configure the server connection and set up the necessary permissions for your device registration.

## Step 4: Receive Configuration Details

You'll receive a response from AutoPi support containing:

- Your device's board version.
- A link to the reflashing guide: [Reflashing Your Device](https://docs.autopi.io/developer_guides/reflashing-your-device/).

Keep this information handy for the next steps.

## Step 5: Reflash Your Device

Reflashing migrates your device from the DIMO server to the AutoPi server. Follow the detailed instructions in the reflashing guide: **[Reflashing Your Device →](https://docs.autopi.io/developer_guides/reflashing-your-device/)**

:::warning
Reflashing erases the existing software on your device. Make sure you have backed up any critical local data before proceeding.
:::

## Step 6: Register Your Device

After creating an account, you can access the AutoPi Cloud features for fleet and device management.
The next step is to register your device to unlock the platform's full potential.

To add a device to your account, follow one of these methods:

**Option 1: Via Device Management**

1. Open the "Device Management" section of the platform.
2. Click on "Devices".
3. Find and click the "Register Device" button in the upper right corner.

**Option 2: Via the Accounts Tab**

1. Navigate to the "Accounts" tab at the bottom of the left-side menu on the platform.
2. Select "Devices".
3. Locate and click the "Register Device" button in the upper right corner.

After clicking the "Register Device" button, the registration tab will appear. Enter all necessary information:
![Register Your Device](/img/getting_started/dimo/register_device.png)

- **AutoPi.io Unit ID**: this is the number on the side of your device.
- **Vehicle Information**: optionally include the make, model, and year of the vehicle.
- **Vehicle Type**: choose the type of vehicle (ICE, Battery Electric Vehicle, Hybrid Electric Vehicle, or Plug-in Hybrid Electric Vehicle).

Once all information is entered, click the "Register Device" button. Your newly registered device will now appear in the list under "Vehicles" in the Fleet Management section and under "Devices" in the Device Management section of the Platform.

## Step 7: Configure Your SIM Card

When inserting the SIM card, it is important to ensure it is installed correctly. If inserted correctly, the device makes a click sound.
The picture below shows the proper orientation of the SIM card.
Please note that the text side of the SIM card must face up and the "triangle" end must point into the device.

![AutoPi.io - SIM card location](/img/getting_started/getting_started/sim_card.png)

Connect to your device's local administration interface and update the APN (Access Point Name) to **nxt20.net**. This ensures your device connects to the AutoPi network: **[Local Administration Setup →](https://docs.autopi.io/getting_started/autopi_tmu_cm4/#7-connect-to-local-administration)**

Here's how you configure the APN settings:

1. Go to my.autopi.io. If you're already logged in, please log out.
2. On the login page, find the "Go Local" button at the bottom-left side,
   or alternatively, go directly to local.autopi.io.

    
        
    

This will connect you to the local device, and you should see a screen similar to the one shown in the image below, indicating that you're connected locally. From here, you can log in without needing a username or password.

![AutoPi.io - Localhost login](/img/getting_started/getting_started/local.jpg)

Once the information is saved, it will be applied to the device, and you should see a confirmation notification. To verify that you have set up your APN settings correctly, connect your phone to the AutoPi hotspot and use your browser to visit any webpage. If the page loads successfully, it means your device is online and has started uploading data to the AutoPi Cloud.

## Step 8: Accept Device Key

When your device comes online over 4G, it will appear in your AutoPi Cloud dashboard as Online. Accept the device key to complete the connection.

- Navigate to the device page.
- Click the **Edit device** button in the upper-right corner.
- Scroll to the **Key state** section and press **Accept** the key.

![Accept Device's Key](/img/getting_started/dimo/accept_key.png)

## You're Ready to Go!
Congratulations! Your device is now fully integrated with the AutoPi Cloud platform.

**What's Next?**

Now that your device is up and running, here are a few suggestions to help you get the most out of your AutoPi experience: 
- **Explore the AutoPi Cloud**: Dive into the AutoPi Cloud platform to explore all 
  the features available to you, such as real-time vehicle monitoring, 
  advanced analytics, and customizable alerts. 
- **Check Out Our Documentation**: Our [documentation page](https://docs.autopi.io/) 
  is a great resource for learning more about advanced features, troubleshooting, 
  and getting the most out of your device. 
- **Build your Nested Accounts and Invite New Users**: AutoPi Cloud uses a multi-tenant architecture, which means multiple accounts (tenants) share the same platform and infrastructure, while all data, configurations, and user access remain securely isolated. You can read more here: [Account management](https://docs.autopi.io/cloud/accounts/). 

Start with the Cloud section to learn about device management, data logging, and advanced configurations. If you need additional support, our team is happy to help. Contact us at **support@autopi.io** or through the support form in the AutoPi Cloud platform.

---

## Caterpillar 14 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a Caterpillar heavy-duty vehicle for J1939 diagnostics or data logging?

The Caterpillar 14 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many Caterpillar heavy-duty vehicles — including loaders, construction machinery, and mining vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 14-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Caterpillar 14 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/catapiller-14-pin-j1939-to-16-pin-obd-ii-adapter-cable).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Compatibility       | Caterpillar engines with a 14 PIN diagnostic port |
| Connector Types     | 14 PIN (male) to 16 PIN OBD-II (female)           |
| Protocol Support    | J1939 for vehicle diagnostics                     |
| Durability          | Premium materials for heavy-duty use              |
| Ease of Use         | Plug-and-play design                              |

## Pinout

| AutoPi Function | Caterpillar 14 PIN | OBD-II 16 PIN |
|:-----------------:|:--------------------:|:---------------:|
| CAN Low         | Pin D              | Pin 14        |
| Power           | Pin B              | Pin 16        |
| GND             | Pin C              | Pin 5         |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your Caterpillar engine documentation for any model-specific variations.
:::

---

## Caterpillar (538-5051) Truck 9 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a Caterpillar truck for J1939 diagnostics and data logging?

The Caterpillar (538-5051) Truck 9 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many Caterpillar truck models — including heavy-duty trucks and commercial vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 9-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Caterpillar (538-5051) Truck 9 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/cummins-komatsu-truck-12-pin-j1939-to-16-pin-obd-ii-adapter-copy).
:::

## Specifications

| Property            | Details                                              |
|:---------------------:|:------------------------------------------------------:|
| Compatibility       | Caterpillar 538-5051 truck with 9 PIN diagnostic port |
| Connector Types     | 9 PIN (male) to 16 PIN OBD-II (female)               |
| Protocol Support    | J1939 for vehicle diagnostics                        |
| Durability          | Premium materials for heavy-duty use                 |
| Ease of Use         | Plug-and-play design                                 |

## Pinout

| AutoPi Function | OBD-II 16 PIN | Caterpillar 9 PIN |
|:-----------------:|:---------------:|:-------------------:|
| CAN High        | Pin 6         | Pin G             |
| CAN Low         | Pin 14        | Pin F             |
| Power           | Pin 16        | Pin A             |
| GND             | Pin 5         | Pin B             |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your Caterpillar truck documentation for any model-specific variations.
:::

---

## Cummins 9 PIN J1939 (J1708) to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a Cummins heavy-duty vehicle for J1939 or J1708 diagnostics and data logging?

The Cummins 9 PIN J1939 (J1708) to 16 PIN OBD-II Adapter Cable fits many Cummins-powered heavy-duty vehicles — including trucks, buses, and industrial machinery — and lets you easily connect your AutoPi device to start reading J1939 or J1708 data. Simply locate the 9-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Cummins 9 PIN J1939 (J1708) to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/cummins-9-pin-j1939-j1708-to-16-pin-obd2-adapter-cable).
:::

## Specifications

| Property            | Details                                              |
|:---------------------:|:------------------------------------------------------:|
| Compatibility       | Cummins engines with a 9 PIN diagnostic port         |
| Connector Types     | 9 PIN (male) to 16 PIN OBD-II (female)               |
| Protocol Support    | J1939 and J1708 for vehicle diagnostics              |
| Durability          | Premium materials for heavy-duty use                 |
| Ease of Use         | Plug-and-play design                                 |

## Pinout

| AutoPi Function | Cummins 9 PIN | OBD-II 16 PIN |
|:-----------------:|:---------------:|:---------------:|
| CAN High        | Pin C         | Pin 6         |
| CAN Low         | Pin D         | Pin 14        |
| Power           | Pin B         | Pin 16        |
| GND             | Pin A         | Pin 5         |

	

:::note
The pinout above is based on the standard J1939/J1708 to OBD-II mapping. Refer to your Cummins engine documentation for any model-specific variations.
:::

---

## Cummins-Komatsu Truck 12 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a Cummins or Komatsu truck for J1939 diagnostics and data logging?

The Cummins-Komatsu Truck 12 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many Cummins and Komatsu truck models — including heavy-duty trucks and commercial vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 12-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Cummins-Komatsu Truck 12 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/man-truck-12-pin-j1939-to-16-pin-obd-ii-adapter-copy).
:::

## Specifications

| Property            | Details                                              |
|:---------------------:|:------------------------------------------------------:|
| Compatibility       | Cummins and Komatsu trucks with 12 PIN diagnostic port |
| Connector Types     | 12 PIN (male) to 16 PIN OBD-II (female)              |
| Protocol Support    | J1939 for vehicle diagnostics                        |
| Durability          | Premium materials for heavy-duty use                 |
| Ease of Use         | Plug-and-play design                                 |

## Pinout

| AutoPi Function | Cummins-Komatsu 12 PIN | OBD-II 16 PIN |
|:-----------------:|:------------------------:|:---------------:|
| CAN High        | Pin 3                    | Pin 6         |
| CAN Low         | Pin 10                   | Pin 14        |
| Power           | Pin 1                    | Pin 16        |
| GND             | Pin 12                   | Pin 5         |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your Cummins or Komatsu truck documentation for any model-specific variations.
:::

---

## Device Mounts

---

This section contains a description of the mounting options available for the [AutoPi](https://www.autopi.io) devices.

## Flat Surfaces Mount
The mount is meant to be screwed or glued to a flat surface and to snap on the bottom of the device. 

![Device mount for flat surfeces](/img/hardware/accessories/device_mounts/device_mount_3_cut.png)

Download mount for flat surfaces.

## Curved Surfaces Mount
The mount is meant to be glued or secured with zip ties to a curved surface such as a support pipe under the dash or a curved piece of plastic and to snap on the bottom of the device.

![Device mount for curved surfeces](/img/hardware/accessories/device_mounts/device_mount_curve_1_CutV2.png)

Download mount for curved surfaces.

---

## DoIP HAT Installation

---

:::caution Before you begin
The DoIP solution described in this guide is **only supported on AutoPi TMU CM4–based devices** and newer revisions.

- DoIP can be ordered **pre-installed** from AutoPi. If your device was delivered with DoIP pre-installed, no hardware installation is required.
- When the DoIP HAT is installed, the **Ethernet interface on the AutoPi is internally routed to the vehicle**.  
  **Do not connect anything to the Ethernet port** after installation.
- **Never install a DoIP-enabled device in a vehicle that does not support DoIP (Ethernet diagnostics).**  
  Using Ethernet-based diagnostics on a CAN-only vehicle may interfere with vehicle communication and operation.
:::

## Introduction

This guide explains how to physically install the **AutoPi DoIP HAT** on an AutoPi TMU CM4 device.

The DoIP HAT enables **Diagnostics over IP (DoIP)**, allowing diagnostic and programming communication with vehicle ECUs over Ethernet instead of CAN. This is commonly used for:
- UDS diagnostics over Ethernet
- ECU flashing and programming
- High-bandwidth diagnostic workflows
- OEM and engineering tools that require DoIP

If you are looking for instructions on **how to use DoIP after installation**, see:  
[Setting up DoIP on AutoPi](/developer_guides/setting-up-doip/)

## What is DoIP?

DoIP (Diagnostic over Internet Protocol, ISO 13400) is an automotive diagnostic protocol that transports diagnostic messages over IP-based networks, typically Ethernet.

Compared to CAN-based diagnostics, DoIP offers:
- Higher bandwidth
- Faster flashing and data transfer
- Direct compatibility with modern OEM diagnostic tools
- Ethernet-based ECU access without CAN bottlenecks

## Prerequisites

Before starting, ensure you have the following:

- 1 × AutoPi DoIP HAT PCB
- 3 × Plastic screws
- 2 × 6.5 mm plastic spacers
- AutoPi TMU CM4 device
- Clean, static-safe workspace

:::info
The DoIP HAT can be purchased from the AutoPi Shop:  
[DoIP HAT for AutoPi TMU CM4](https://shop.autopi.io/products/doip-hat-v1-3)

You can also order AutoPi devices with the DoIP HAT pre-installed.
:::

  

## Installation Steps

### Step 1 – Open the AutoPi enclosure

Place the AutoPi device upside down and remove the four screws on the bottom of the enclosure.

Carefully lift off the top cover to expose the internal PCB.

  

### Step 2 – Prepare the DoIP HAT

Attach the two **6.5 mm plastic spacers** to the DoIP HAT PCB using the provided plastic screws.

Ensure the spacers are firmly mounted and aligned with the mounting holes.

  

### Step 3 – Mount the DoIP HAT

Carefully align the DoIP HAT with the **40-pin GPIO header** on the AutoPi main board.

Press the HAT straight down until the connector is fully seated.  
Verify:
- The HAT is level
- The GPIO connector is fully engaged
- No pins are misaligned or bent

  

### Step 4 – Reassemble the enclosure

Reassemble the device using the **DoIP-compatible side shield**.

This side shield provides the correct cutout and routing for the internal Ethernet interface used by DoIP.

Make sure:
- No cables are pinched
- The HAT remains firmly seated
- All enclosure screws are tightened evenly

  

## Final Checks

After installation:

- The external Ethernet port on the AutoPi is now **reserved for DoIP**
- Do not connect external Ethernet cables
- Install the device **only in vehicles that support DoIP**
- Proceed with software configuration before attempting diagnostics

## Next Steps

The DoIP hardware installation is now complete.

Continue with the software setup guide to:
- Enable DoIP services
- Configure network settings
- Validate ECU discovery and communication

➡️ [Setting up DoIP on AutoPi](/developer_guides/setting-up-doip/)

## Troubleshooting

If the device does not detect DoIP ECUs after installation:

- Verify the HAT is fully seated on the GPIO header
- Confirm the vehicle supports DoIP
- Check that no external Ethernet device is connected
- Ensure the correct AutoPi OS version is installed

---

You have now successfully installed the AutoPi DoIP HAT.

---

## OBD-II to dual DB9 pinout

---

## Introduction
This page describes the pinout of our OBD-II to dual DB9 pinout cable:

    

The following is the size and dimensions:

    

## Pinout

| AutoPi function      | OBD-II Connector       | DB9 CH1         | DB9 CH2                     |
|-------|------------------------|-----------------------------------------------|-|
| Power    | Pin 16           | Pin 1 (Power)                                           |  Pin 1 (Power)     |
| GND | Pin 5              | Pin 3 + Pin 6 (GND)                        | Pin 3 + Pin 6 (GND)   |
| MS CAN Low | Pin 11          | Pin 2 (CAN1 Low)                 | NC  |
| MS CAN High | Pin 3              | Pin 7 (CAN1 High)                   |  NC |
| HS CAN Low | Pin 14   | NC                              | Pin 2 (CAN2 Low)   |
| HS CAN High| Pin 6              | NC                          |  Pin 7 (CAN2 High)  |
| HAT Pin 11| Pin 9               | Pin 4 (LIN1)    | NC  |
| HAT Pin 12 | Pin 12                 | Pin 9 (LIN1 VBat)                                       | NC  |
| HAT Pin 5 | Pin 1              | NC                     | Pin 4 (LIN2)     |
| HAT Pin 8 | Pin 2                | NC           | Pin 9 (LIN2 VBat)  |

:::info
This adapter cable can be bought through AutoPi shop: [**OBD-II to dual DB9 adapter cable**](https://shop.autopi.io/products/obd2-to-dual-db9). 
:::

---

## Female CAN Bus Cable with Open Wires

---

## Introduction

Do you need to connect your AutoPi device directly to a CAN bus interface?

The Female CAN Bus Cable with Open Wires allows you to connect your AutoPi device directly to CAN bus systems using open wire connections. This cable is ideal for custom installations and integration with specialized CAN bus networks. Simply match the wire colors to your target CAN bus signals and secure the connections.

	

The cable features open wires for flexibility in custom configurations, and is constructed with premium materials built for reliable use.

:::info
This cable can be purchased through the AutoPi shop: [**Female CAN Bus Cable with Open Wires**](https://shop.autopi.io/products/female-can-bus-cable-w-open-wires).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Connector Type      | Female CAN Bus connector                     |
| Wire Type           | 16 open wires (one wire per OBD-II pin)           |
| Supported Protocols | CAN 2.0, J1939, and other OBD-II/CAN-based protocols |
| Durability          | Premium materials for reliable use                |
| Applications        | Custom CAN bus integrations and installations    |

## OBD-II Pin Breakout (16 Open Wires)

| OBD-II Pin | Typical Function | Wire Color on AutoPi's Cable* |
|:------------:|:------------------:|:-------------------------------:|
| Pin 1      | Manufacturer specific | Brown |
| Pin 2      | SAE J1850 Bus+ (vehicle dependent) | Brown + White |
| Pin 3      | Manufacturer specific | Purple |
| Pin 4      | Chassis Ground | Mustard Yellow |
| Pin 5      | Signal Ground | Light blue |
| Pin 6      | CAN High (ISO 15765-4 / J1939) | Green |
| Pin 7      | K-Line (ISO 9141-2 / ISO 14230-4) | Black |
| Pin 8      | Manufacturer specific | Black + White |
| Pin 9      | Manufacturer specific | Red + White |
| Pin 10     | SAE J1850 Bus- (vehicle dependent) | White |
| Pin 11     | Manufacturer specific | Yellow |
| Pin 12     | Manufacturer specific | Pink |
| Pin 13     | Manufacturer specific | Grey |
| Pin 14     | CAN Low (ISO 15765-4 / J1939) | Green + White |
| Pin 15     | L-Line (optional / vehicle dependent) | Blue |
| Pin 16     | Battery Power (VBat) | Red |

:::note
*Color mapping can vary by cable production batch. Always verify each wire with a multimeter/continuity test before connecting to vehicle power or bus lines.
:::

## Connection Guide

When connecting the open wires:

1. Identify the exact wire-to-pin mapping for your cable batch.
2. Connect power and ground first (OBD-II Pin 16 and Pin 5).
3. Connect CAN High and CAN Low next (OBD-II Pin 6 and Pin 14).
4. Connect any remaining lines only if required by your protocol.

:::warning
Ensure all connections are secure and properly insulated. Incorrect connections can damage your AutoPi device or target system. Verify wire connections against your system's CAN bus documentation before powering on.
:::

---

## Accessories Overview

---

:::info Need Custom Integrations?
[Contact](mailto:support@autopi.io) our team to discuss tailored solutions for your business.
:::

This section contains a description of addons avaible for the [AutoPi](https://www.autopi.io) devices. 

Learn how to create and integrate various accessories with your AutoPi device to unlock its full potential. 
These add-ons enhance functionality, allowing you to customize your setup and optimize data management. Explore the possibilities and make the most of your AutoPi experience.

## Global SIM Card Solution 
Our Global SIM card solution works in 188 countries, providing you with reliable and seamless connectivity wherever your solution is based. Stay connected and experience the easiest setup of your device with our versatile sim card.

You can read more about coverage and more information in this **guide**: [Global SIM Card Solution](https://docs.autopi.io/hardware/accessories/sim-solution/). 

The solution can be **purchased** in our [AutoPi Webshop - Global SIM Card](https://shop.autopi.io/products/global-sim-card-solution). We offer different package sizes and your monthly data usage is shown from our [AutoPi Cloud solution](https://my.autopi.io).

## OBD-II to dual DB9 pinout Cable
Connect two CAN bus nodes to the OBD2 port of the AutoPi TMU CM4 or the AutoPi CAN-FD Pro. The DB9 connections each connects to one of the CAN busses available on the devices. 

You can read more about pinout and more information in this **guide**: [OBD-II to dual DB9 pinout](https://docs.autopi.io/hardware/accessories/dualdb9-pinout/). 

This cable can be **purchased** in our [AutoPi Webshop - OBD-II to dual DB9 cable ](https://shop.autopi.io/products/obd2-to-dual-db9). 

**Specifications:**
* Compatibility: For DB9 based connections.
* Connector Types: DB9 (male) to 16 PIN OBD2 (female).
* Protocol Support: CAN BUS for vehicle interfacing.
* Durability: Constructed with premium materials.
* Ease of Use: Plug-and-play design for quick and secure connections.

    

## DoIP HAT 
The DoIP HAT is a highly advanced interface module designed to enhance vehicle diagnostics using the DoIP protocol (Diagnostics over Internet Protocol). With high-speed Ethernet connectivity and support for multiple protocols, this module ensures accurate communication and comprehensive diagnostic capabilities for modern vehicles.

This DoIP HAT can be **purchased** in our [AutoPi Webshop - DoIP HAT](https://shop.autopi.io/products/doip-hat-v1-3).

You can read more about how to install DoIP HAT to your AutoPi device in this **guide**: [DoIP HAT Install guide](https://docs.autopi.io/hardware/accessories/doip-install/). 

And you can read more on how to start using the DoIP software and **step by step guide on how to activate DoIP interface** on your AutoPi device: [Setting up DoIP](https://docs.autopi.io/developer_guides/setting-up-doip/).

**Technical Overview:**
An advanced DoIP (ISO 13400) interface module designed for enhanced diagnostic communication with vehicle ECUs, leveraging high-speed Ethernet connectivity for real-time data analysis.

**Performance Advantages:**
* DoIP Protocol Support: Fully compliant with ISO 13400 standards for efficient communication with vehicle systems, enabling precise diagnostics and firmware updates.
* High-Speed Ethernet Connectivity: Provides fast and reliable data transfer, essential for real-time diagnostics and monitoring.
* Multi-Protocol Compatibility: Supports UDS (Unified Diagnostic Services) and other key automotive protocols across a wide range of vehicle makes and models.
* Rugged Construction: Engineered for durability, the HAT is built to withstand harsh automotive environments for consistent performance.
* Quick Deployment: Designed for plug-and-play installation on compatible devices, simplifying the setup process for fast implementation.
* Application Scope: Ideal for automotive workshops, testing centers, and manufacturers requiring advanced diagnostics, real-time vehicle monitoring, and firmware updates.

    

## WiFi/BLE/LTE/GPS Antennas
If you often drive in places with poor 4G/LTE coverage and/or weak GPS signal, our Webshop offers 2 external kits that should improve the overall signal quality. The kit allows you to boost 4G/LTE connectivity and GPS signal strength, which is especially useful if you frequently drive in areas with weak signal reception. 

* [4-in-1 Antenna Kit](https://shop.autopi.io/products/4-in-1-car-antenna-lte-x2-gps-wifi) - he 4in1 Antenna Kit is a high-performance solution designed to optimize connectivity for the AutoPi TMU CM4 device. Featuring two LTE antennas, one GPS antenna, and one WiFi antenna, this compact system delivers strong signal reception and reliable communication across multiple wireless standards. Built for demanding environments, the antenna kit ensures stable and long-term performance.
This kit can be pre-installed on AutoPi TMU CM4 device or installed by using this guide: [Installation Guide for CM4 device](https://docs.autopi.io/hardware/autopi_tmu_cm4/installing_4in1_external_antennas/). 

    

* [3-in-1 Antenna Kit](https://shop.autopi.io/products/3in1-external-antenna-kit) - With this kit you can convert your AutoPi device to use the all in one external antenna, instead of the built-in internal antennas, thereby improving the overall signal quality. This antenna kit includes: 2x LTE and 1x GPS. 
This kit can be pre-installed on AutoPi TMU CM4 device or installed by using this guide: [Installation Guide for CM4 device](https://docs.autopi.io/hardware/autopi_tmu_cm4/installing_external_antennas/). 

    

:::info
Our [Autopi CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro) comes with the 4-in-1 Antenna Kit already included. 
:::

## Adapter Cables
Our Autopi Webshop offers various adapter cables to help integrate your AutoPi device in specific setups: 
  * [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable?pr_prod_strat=jac&pr_rec_id=f2111200b&pr_rec_pid=8619775328605&pr_ref_pid=14961336746333&pr_seq=uniform) – Add extra reach for flexible placement.
  * [OBD-II Power Cable](https://shop.autopi.io/products/obd-ii-power-cable?pr_prod_strat=jac&pr_rec_id=17052e989&pr_rec_pid=8619774050653&pr_ref_pid=8609919074653&pr_seq=uniform) - Power the AutoPi device with any 12-24 volt DC power supply.
  * [OBD-II Splitter Cable](https://shop.autopi.io/products/obd-ii-splitter-cable?pr_prod_strat=jac&pr_rec_id=70ef610e3&pr_rec_pid=8619777327453&pr_ref_pid=8619774050653&pr_seq=uniform) - Use this Y-splitter cable if you need to connect an additional OBD-II device at the same time as your AutoPi device.
  * [Tesla OBD-II Adapter Cable for Model 3 and Y](https://shop.autopi.io/products/tesla-obd2-adapter-cable-for-model-3-and-y) - Add an OBD-II port to your Tesla Model 3 or Model Y with this adapter cable.
  * [Micro USB-A Adapter Cable](https://shop.autopi.io/products/micro-usb-to-usb-a-adapter-cable) - This Micro USB to USB-A adapter cable is made to fit perfectly with the external Micro USB port on the AutoPi device.
  * [CAN Bus Testing/Loop Cable](https://shop.autopi.io/products/can-bus-testing-cable) - The CAN Bus Testing Cable is a cable designed for internal communication testing between two CAN bus systems.
  * [CAN Bus Cable with Open Wires](https://shop.autopi.io/products/can-bus-cable-w-open-wires) - The CAN Bus cable with open wires is a cable designed for customized installations, where you need to connect specific wires only. 

    

## Heavy-duty Adapter Cables
Our Autopi Webshop offers various heavy-duty adapter cables to help integrate your AutoPi device in different Heavy-duty J1939 vehicles. You can browse through the selection for: 
* [Catapiller 14 PIN J1939 to 16 PIN OBD-II Adapter cable](https://shop.autopi.io/products/catapiller-14-pin-j1939-to-16-pin-obd-ii-adapter-cable)
* [IVECO 30 PIN J1939 to 16 PIN OBD-II Adapter Cable](https://shop.autopi.io/products/iveco-30-pin-to-16-pin-obd2-adapter-cable)
* [Knorr Wabco Trailer 7 PIN J1939 to 16 PIN OBD-II Adapter Cable](https://shop.autopi.io/products/knorr-wabco-trailer-7-pin-to-16-pin-obd2-adapter-cable) 
* [MAN 37 PIN J1939 to 16 PIN OBD-II Adapter Cable](https://shop.autopi.io/products/man-37-pin-to-16-pin-obd2-adapter-cable)
* [MAN Truck 12 PIN J1939 to 16 PIN OBD-II Adapter](https://shop.autopi.io/products/man-truck-12-to-16-pin-obd2-adapter)
* [Mercedes 14 PIN J1939 to 16 PIN OBD-II Adapter Cable](https://shop.autopi.io/products/mercedes-14-pin-to-16-pin-obd2-adapter-cable)
* [Renault 12 PIN J1939 to 16 PIN OBD-II Adapter Cable](https://shop.autopi.io/products/renault-12-pin-to-16-pin-obd2-adapter-cable)
* [Scania 16 PIN J1939 to 16 PIN OBD-II Adapter Cable](https://shop.autopi.io/products/scania-16-pin-to-16-pin-obd2-adapter-cable)
* [Volvo 8 PIN J1939 to 16 PIN OBD-II Adapter Cable](https://shop.autopi.io/products/volvo-8-pin-to-16-pin-obd2-adapter-cable)
* [Cummins 9 PIN J1939 (J1708) to 16 PIN OBD-II Adapter Cable](https://shop.autopi.io/products/cummins-9-pin-j1939-j1708-to-16-pin-obd2-adapter-cable)

![Heavy-duty Adapter Cables](/img/hardware/accessories/cables/j1939_cables.png)
![Heavy-duty Adapter Cables2](/img/hardware/accessories/cables/j1939_cables2.png)

## Device Mounts 
At the moment we have 2 mounting options available for the AutoPi devices. You can mount your AutoPi device with [Flat Surface Mount](https://docs.autopi.io/hardware/accessories/device_mounts/#flat-surfaces-mount) or [Curved Surfaces Mount](https://docs.autopi.io/hardware/accessories/device_mounts/#curved-surfaces-mount). For both of the options we have a free designs available for download, you can read more at this **guide**: [Device Mounts](https://docs.autopi.io/hardware/accessories/device_mounts/).

---

## IVECO 30 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to an IVECO truck for J1939 diagnostics and data logging?

The IVECO 30 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many IVECO truck models — including heavy-duty trucks and commercial vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 30-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**IVECO 30 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/iveco-30-pin-to-16-pin-obd2-adapter-cable).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Compatibility       | IVECO trucks with 30 PIN diagnostic port          |
| Connector Types     | 30 PIN (male) to 16 PIN OBD-II (female)           |
| Protocol Support    | J1939 for vehicle diagnostics                     |
| Durability          | Premium materials for heavy-duty use              |
| Ease of Use         | Plug-and-play design                              |

## Pinout

| AutoPi Function | IVECO 30 PIN | OBD-II 16 PIN |
|:-----------------:|:--------------:|:---------------:|
| CAN High        | Pin 4        | Pin 6         |
| CAN Low         | Pin 12       | Pin 14        |
| Power           | Pin 30       | Pin 16        |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your IVECO truck documentation for any model-specific variations.
:::

---

## Introduction(Accessories)

:::caution
The keyless entry solution described here only works with the [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) and newer editions
:::

This guide provides a general technical overview of the [AutoPi](https://www.autopi.io) Keyless solution. 

Many different approaches to lock/unlock exist already, but with the solution from [AutoPi](https://www.autopi.io), you receive an agnostic solution working across all make and models available. These are some of the benefits:
-	No wire cutting needed, which means your vehicle’s warranty is not voided 
-	Easy and fast installation and removal
-	Supports keyless ignition for vehicles with electronic start/stop technology
-	Build-in immobilizer for vehicles with electronic start/stop technology 
Several different keyless entry solutions exist on the market today. All the different types of solutions have pros and cons, but one universal solution does not exist.

---

## Keyless Interface Specification

:::warning
This solution has been discontinued and is no longer supported by the platform. 
:::

:::caution
The keyless entry solution described here only works with the [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) and newer editions
:::

This section descripes the interface for the keyless keyfob solution provided through the BLE extension available through [AutoPi](https://www.autopi.io). The BLE extension is a small extension board, which makes it possible to wake the [AutoPi](https://www.autopi.io) through a BLE connection and then send BLE commands to control a keyfob through the same interface. The BLE connection makes it possible to unlock/lock the car in areas where there is no internet connection. 

## API for Key Controls
Commands can be sent from another system to the [AutoPi](https://www.autopi.io) server and there on to control the vehicle. 

## Power Settings to Optimize Sleep Scheduling
It is possible to upload booking schedules to the [AutoPi](https://www.autopi.io) backend. These will be transformed into sleeping schedules for the [AutoPi](https://www.autopi.io) to ensure that the device is powered on at the correct times.

## Offline Mode
When the device is offline (not connected to LTE/GSM network), it is important that the user can still control the car. Therefore, a set of offline functions will be available through Bluetooth. 

From an App it is possible to communicate directly with the device using BLE. 

To ensure security, the device will have a rolling key pair needed for smartphones to be able to send the commands. This key needs to be synced to the smartphone during the booking, to allow unlock of the car. These keys will be distributed by the [AutoPi](https://www.autopi.io) backend and will be updated on the device and made available for the external system.

---

## Keyfob Cloud Configuration

:::caution Before proceeding with the install
The keyless entry solution described in this guide is **only compatible** with the [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) and newer editions.  
Earlier AutoPi models do not provide the required hardware interfaces or software support and will not function with the keyfob HAT.
:::

:::note
**Prerequisites** before starting:  
- The keyfob HAT has been securely installed in your AutoPi TMU CM4 device.  
- The keyfob has been correctly soldered to the wires in the extension casing. Ensure that solder joints are solid and free from shorts.  
- You have a working AutoPi Cloud account at [my.autopi.io](https://my.autopi.io/) with your device already registered.  
- Your device is powered, connected to the internet, and synchronized with the AutoPi Cloud.  
:::

---

## Step-by-Step Guide

### Step 1 – Hardware Connection
Begin by connecting the keyfob casing to the correct port on your AutoPi device. The keyfob must always be connected to **CONN2**, as shown below:  

Make sure that the red wire (power) is connected to **`Vcc3v3_switched`**. This is critical, as the keyfob is designed to operate on a 3.3V switched power source. Supplying the wrong voltage, or connecting to a continuous supply, can damage the HAT or prevent correct operation.  

Check all wiring carefully:
- **Red wire** → `Vcc3v3_switched` (power)  
- **Black wire** → GND  
- **Signal wires** → Corresponding button outputs  

Proper cable management is also recommended to avoid strain or accidental disconnection inside the extension casing.

---

### Step 2 – Access Cloud Settings
Next, configure the keyfob through the AutoPi Cloud platform.  

1. Log in at [my.autopi.io](https://my.autopi.io/).  
2. Navigate to your device and open the **Advanced Settings** section.  
3. Locate the **Keyfob Tab**. If the tab is not visible, contact [support@autopi.io](mailto:support@autopi.io) to have it enabled.  

![Step 2](/img/hardware/accessories/keyfob/keyfob_cloud1.jpg)

The Keyfob Tab provides the configuration options needed to activate the HAT and define button mappings. Without this configuration, the AutoPi device cannot interpret or forward keyfob button actions to your vehicle.

---

### Step 3 – Enable and Configure the Keyfob
Once inside the Keyfob Tab:  

1. Enable the keyfob feature by pressing the **Enable** button.  
2. Set **EXT2** as the output port. This assigns the communication channel used to interact with the HAT.  

After enabling, press the **Reset** button under the *Buttons* section. This action will generate a default list of button mappings. These mappings represent the raw signals detected from your soldered wires.  

You must now map each signal to the correct button function, depending on how the keyfob has been wired. For example, a button connected to a green wire may correspond to "Lock," while another connected to a yellow wire may represent "Unlock."  

Carefully record your configuration so that the same mapping can be reused later if the device is reset or updated. It is good practice to name buttons clearly, using functional terms such as `lock`, `unlock`, `trunk`, or `lights`.

![Step 3](/img/hardware/accessories/keyfob/keyfob_cloud2.jpg)

---

### Step 4 – Power Up the Keyfob
Before the keyfob can be used, you must explicitly power it on. The keyfob HAT does not receive constant power to prevent unnecessary drain on the device.  

1. Run the [`keyfob.power`](/core/commands/core-commands-keyfob/#keyfobpower) command from the AutoPi Cloud.  
2. Verify that the device is online and has a stable internet connection.  
3. Open the **Live Terminal** to interact with the device in real time.  

![Step 4](/img/hardware/accessories/keyfob/keyfob_cloud3.jpg)

If power is not enabled, none of the keyfob actions will execute. You may also configure power to be enabled automatically on startup if frequent use is required.

---

### Step 5 – Lock and Unlock the Vehicle
With power enabled and buttons mapped, you can now use the keyfob commands.  

The main command is [`keyfob.action`](/core/commands/core-commands-keyfob/#keyfobaction). The argument you supply to this command must match the button name you configured in the Keyfob Tab.  

For example, if you created a button named `unlock`, the following command will trigger that function and send the corresponding signal to your vehicle’s central locking system:  

![Step 5](/img/hardware/accessories/keyfob/keyfob_cloud4.jpg)

Typical actions include:
- **Unlock** – Open vehicle doors.  
- **Lock** – Secure vehicle doors.  
- **Trunk** – Release trunk or rear hatch.  
- **Lights** – Flash headlights or activate hazard lights.  

Each action depends on how the wires have been soldered to your original keyfob PCB. Always verify functionality in a safe environment before regular use.

---

## Best Practices
To ensure reliable operation and safety:  
- Use consistent naming for buttons. Avoid spaces and special characters.  
- Document the wire colors and functions in your project notes.  
- Test each button individually before finalizing installation.  
- Consider heat-shrink tubing around soldered joints for extra durability.  
- If the vehicle does not respond, check the wiring orientation and verify that the AutoPi Cloud shows the device as online.

---

## Troubleshooting and Support
If you experience issues:  
- Verify that **CONN2** is used for the connection.  
- Confirm that `Vcc3v3_switched` is supplying power to the keyfob.  
- Recheck soldering to ensure solid electrical connections.  
- Confirm that the Keyfob Tab is visible and enabled in the AutoPi Cloud.  
- Run `keyfob.power` again to confirm that the HAT is active.  

If the problem persists, contact [support@autopi.io](mailto:support@autopi.io) or reach out to your assigned sales representative. Provide details such as your device ID, wiring layout, and button configuration for faster resolution.

---

## Keyfob HAT Install

:::caution Before proceeding with the install
The keyless entry solution described here only works with the [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) and newer editions
:::

:::note
**Prerequesites** for this guide:
- 1x Keyless Entry BLE HAT PCB
- 1x 4mm plastic spacer
- 2x Plastic screw
- 2x 6.5 mm plastic spacer
- AutoPi BLE side shield
:::

## Step-by-Step Guide

### Step 1
Open up the [AutoPi](https://www.autopi.io) device by unscrewing the four screws at the bottom. 

### Step 2
Start preparing the BLE hat by screwing one 6.5 mm spacer in each hole of the PCB as seen in the pictures.

![Step 2](/img/hardware/accessories/keyfob/install_step1.jpg)

### Step 3
Connect the BLE hat with the [AutoPi](https://www.autopi.io) board through the 40 pin headers. Verify that the connectors are properly connected.

![Step 3](/img/hardware/accessories/keyfob/install_step2.jpg)

### Step 4
Reasemble the device using the new [AutoPi](https://www.autopi.io) BLE side shield, giving access to two new Keyfob control ports on the side.

## Disscussion

	You have now successfully installed the keyless entry solution to the device.

---

## Keyfob HAT Pinout

:::note
The keyless entry solution described here only works with the [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) and newer editions
:::

The keyless keyfob extension HAT enables two new ports on the [AutoPi](https://www.autopi.io) device. These can be seen here during the install:

After assembly of the device, the ports can be seen from the picture below:

## Pinout Conn 1 - HAT interface

Connection 1 on the Keyfob HAT is controlled locally on the keyfob extension board. 

The pinout for this connector is:

| **Pin No.** | **Wire Color** | **Name** | **Description** | **Comments** |
|:-----:|--------|--------|--------|--------|
|   1   |   Red      |   Vcc3v3_switched    |   Controllable 3.3V power supply   |   Controlled by the HAT's onboard MCU   | 
|   2   |   Black    |   GND                |   Internal ground                  |   |
|   3   |   Yellow   |   Vcc5v_switched     |   Controllable 5V power supply     |   Controlled by the HAT's onboard MCU   |
|   4   |   Green    |   DIO9               |   Digital input/output             |   Controlled by the HAT's onboard MCU   |
|   5   |   Blue     |   DIO10              |   Digital input/output             |   Controlled by the HAT's onboard MCU   |
|   6   |   White    |   DIO3               |   Digital input/output             |   Controlled by the HAT's onboard MCU   |
|   7   |   Orange   |   DIO2               |   Digital input/output             |   Controlled by the HAT's onboard MCU   |
|   8   |   Purple   |   DIO0               |   Digital input/output             |   Controlled by the HAT's onboard MCU   |

## Pinout Conn 2 - RPI interface
Connection 2 on the Keyfob HAT is controlled from the [AutoPi](https://www.autopi.io) base board, by the standard [AutoPi](https://www.autopi.io) setup. 

The pinout for this connector is:

| **Pin No.** | **Wire Color** | **Name** | **Description** | **Comments** |
|:-----:|--------|--------|--------|--------|
|   1   |   Red      |   Vcc3v3_switched   |   Controllable 3.3V power supply   |   Controlled by the [AutoPi](https://www.autopi.io) base board MCU   | 
|   2   |   Black    |   GND               |   Internal ground                  |   |
|   3   |   Yellow   |   Vcc5v_switched    |   Controllable 5V power supply     |   Controlled by the [AutoPi](https://www.autopi.io) base board MCU   |
|   4   |   Green    |   RPI_ID_SD         |   Digital input/output             |   Controlled by the RPi   |
|   5   |   Blue     |   RPI_GPIO24        |   Digital input/output             |   Controlled by the RPi   |
|   6   |   White    |   RPI_GPIO23         |   Digital input/output             |   Controlled by the RPi   |
|   7   |   Orange   |   RPI_GPIO27        |   Digital input/output             |   Controlled by the RPi   |
|   8   |   Purple   |   RPI_ID_SC        |   Digital input/output             |   Controlled by the RPi   |

---

## Knorr Wabco Trailer 7 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a Knorr Wabco trailer for J1939 diagnostics and data logging?

The Knorr Wabco Trailer 7 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many Knorr Wabco trailer systems — including commercial trailers and heavy-duty vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 7-pin diagnostic port in your trailer, typically found near the connector interface, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Knorr Wabco Trailer 7 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/knorr-wabco-trailer-7-pin-to-16-pin-obd2-adapter-cable).
:::

## Specifications

| Property            | Details                                               |
|:---------------------:|:-------------------------------------------------------:|
| Compatibility       | Knorr Wabco trailers with 7 PIN diagnostic port       |
| Connector Types     | 7 PIN (male) to 16 PIN OBD-II (female)                |
| Protocol Support    | J1939 for vehicle diagnostics                         |
| Durability          | Premium materials for heavy-duty use                  |
| Ease of Use         | Plug-and-play design                                  |

## Pinout

| AutoPi Function | Knorr Wabco 7 PIN | OBD-II 16 PIN |
|:-----------------:|:-------------------:|:---------------:|
| Power           | Pin 2             | Pin 16        |
| GND             | Pin 1             | Pin 5         |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your Knorr Wabco trailer documentation for any model-specific variations.
:::

---

## Male CAN Bus Cable with Open Wires

---

## Introduction

Do you need to connect your AutoPi device directly to a CAN bus interface?

The Male CAN Bus Cable with Open Wires allows you to connect your AutoPi device directly to CAN bus systems using open wire connections. This cable is ideal for custom installations and integration with specialized CAN bus networks. Simply match the wire colors to your target CAN bus signals and secure the connections.

	

The cable features open wires for flexibility in custom configurations, and is constructed with premium materials built for reliable use.

:::info
This cable can be purchased through the AutoPi shop: [**Male CAN Bus Cable with Open Wires**](https://shop.autopi.io/products/can-bus-cable-w-open-wires).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Connector Type      | Male CAN Bus connector                            |
| Wire Type           | 16 open wires (one wire per OBD-II pin)           |
| Supported Protocols | CAN 2.0, J1939, and other OBD-II/CAN-based protocols |
| Durability          | Premium materials for reliable use                |
| Applications        | Custom CAN bus integrations and installations    |

## OBD-II Pin Breakout (16 Open Wires)

| OBD-II Pin | Typical Function | Wire Color on AutoPi's Cable* |
|:------------:|:------------------:|:-------------------------------:|
| Pin 1      | Manufacturer specific | Brown |
| Pin 2      | SAE J1850 Bus+ (vehicle dependent) | Brown + White |
| Pin 3      | Manufacturer specific | Purple |
| Pin 4      | Chassis Ground | Mustard Yellow |
| Pin 5      | Signal Ground | Light blue |
| Pin 6      | CAN High (ISO 15765-4 / J1939) | Green |
| Pin 7      | K-Line (ISO 9141-2 / ISO 14230-4) | Black |
| Pin 8      | Manufacturer specific | Black + White |
| Pin 9      | Manufacturer specific | Red + White |
| Pin 10     | SAE J1850 Bus- (vehicle dependent) | White |
| Pin 11     | Manufacturer specific | Yellow |
| Pin 12     | Manufacturer specific | Pink |
| Pin 13     | Manufacturer specific | Grey |
| Pin 14     | CAN Low (ISO 15765-4 / J1939) | Green + White |
| Pin 15     | L-Line (optional / vehicle dependent) | Blue |
| Pin 16     | Battery Power (VBat) | Red |

:::note
*Color mapping can vary by cable production batch. Always verify each wire with a multimeter/continuity test before connecting to vehicle power or bus lines.
:::

## Connection Guide

When connecting the open wires:

1. Identify the exact wire-to-pin mapping for your cable batch.
2. Connect power and ground first (OBD-II Pin 16 and Pin 5).
3. Connect CAN High and CAN Low next (OBD-II Pin 6 and Pin 14).
4. Connect any remaining lines only if required by your protocol.

:::warning
Ensure all connections are secure and properly insulated. Incorrect connections can damage your AutoPi device or target system. Verify wire connections against your system's CAN bus documentation before powering on.
:::

---

## MAN 37 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a MAN truck for J1939 diagnostics and data logging?

The MAN 37 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many MAN truck models — including heavy-duty trucks and commercial vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 37-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**MAN 37 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/man-37-pin-to-16-pin-obd2-adapter-cable).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Compatibility       | MAN trucks with 37 PIN diagnostic port            |
| Connector Types     | 37 PIN (male) to 16 PIN OBD-II (female)           |
| Protocol Support    | J1939 for vehicle diagnostics                     |
| Durability          | Premium materials for heavy-duty use              |
| Ease of Use         | Plug-and-play design                              |

## Pinout

| AutoPi Function | MAN 37 PIN | OBD-II 16 PIN |
|:-----------------:|:-----------:|:---------------:|
| CAN High        | Pin B     | Pin 6         |
| CAN Low         | Pin C     | Pin 14        |
| Power           | Pin D     | Pin 16        |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your MAN truck documentation for any model-specific variations.
:::

---

## MAN Truck 12 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a MAN truck for J1939 diagnostics and data logging?

The MAN Truck 12 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many MAN truck models — including heavy-duty trucks and commercial vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 12-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**MAN Truck 12 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/man-truck-12-to-16-pin-obd2-adapter).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Compatibility       | MAN trucks with 12 PIN diagnostic port            |
| Connector Types     | 12 PIN (male) to 16 PIN OBD-II (female)           |
| Protocol Support    | J1939 for vehicle diagnostics                     |
| Durability          | Premium materials for heavy-duty use              |
| Ease of Use         | Plug-and-play design                              |

## Pinout

| AutoPi Function | MAN 12 PIN | OBD-II 16 PIN |
|:-----------------:|:-----------:|:---------------:|
| CAN High        | Pin 6     | Pin 6         |
| CAN Low         | Pin 14    | Pin 14        |
| Power           | Pin 16    | Pin 16        |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your MAN truck documentation for any model-specific variations.
:::

---

## Mercedes 14 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a Mercedes truck for J1939 diagnostics and data logging?

The Mercedes 14 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many Mercedes truck models — including heavy-duty trucks and commercial vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 14-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Mercedes 14 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/mercedes-14-pin-to-16-pin-obd2-adapter-cable).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Compatibility       | Mercedes trucks with 14 PIN diagnostic port       |
| Connector Types     | 14 PIN (male) to 16 PIN OBD-II (female)           |
| Protocol Support    | J1939 for vehicle diagnostics                     |
| Durability          | Premium materials for heavy-duty use              |
| Ease of Use         | Plug-and-play design                              |

## Pinout

| AutoPi Function | Mercedes 14 PIN | OBD-II 16 PIN |
|:-----------------:|:-----------------:|:---------------:|
| CAN High        | Pin 6           | Pin 6         |
| CAN Low         | Pin 14          | Pin 14        |
| Power           | Pin 3           | Pin 16        |
| GND             | Pin 1           | Pin 5         |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your Mercedes truck documentation for any model-specific variations.
:::

---

## Renault 12 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a Renault truck for J1939 diagnostics and data logging?

The Renault 12 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many Renault truck models — including heavy-duty trucks and commercial vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 12-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Renault 12 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/renault-12-pin-to-16-pin-obd2-adapter-cable).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Compatibility       | Renault trucks with 12 PIN diagnostic port        |
| Connector Types     | 12 PIN (male) to 16 PIN OBD-II (female)           |
| Protocol Support    | J1939 for vehicle diagnostics                     |
| Durability          | Premium materials for heavy-duty use              |
| Ease of Use         | Plug-and-play design                              |

## Pinout

| AutoPi Function | Renault 12 PIN | OBD-II 16 PIN |
|:-----------------:|:----------------:|:---------------:|
| CAN High        | Pin 1          | Pin 6         |
| CAN Low         | Pin 7          | Pin 14        |
| Power           | Pin 2          | Pin 16        |
| GND             | Pin 5          | Pin 5         |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your Renault truck documentation for any model-specific variations.
:::

---

## Scania 16 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a Scania truck for J1939 diagnostics and data logging?

The Scania 16 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many Scania truck models — including heavy-duty trucks and commercial vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 16-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Scania 16 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/scania-16-pin-to-16-pin-obd2-adapter-cable).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Compatibility       | Scania trucks with 16 PIN diagnostic port         |
| Connector Types     | 16 PIN (male) to 16 PIN OBD-II (female)           |
| Protocol Support    | J1939 for vehicle diagnostics                     |
| Durability          | Premium materials for heavy-duty use              |
| Ease of Use         | Plug-and-play design                              |

## Pinout

| AutoPi Function | Scania 16 PIN | OBD-II 16 PIN |
|:-----------------:|:---------------:|:---------------:|
| CAN High        | Pin 5         | Pin 6         |
| CAN Low         | Pin 9         | Pin 14        |
| Power           | Pin 1         | Pin 16        |
| GND             | Pin 2         | Pin 5         |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your Scania truck documentation for any model-specific variations.
:::

---

## Global SIM Card Solution

---

## Introduction
[AutoPi](https://www.autopi.io) offers a global SIM card solution. The SIM card solution is mainly targeted for our [CAN-FD Pro](https://www.autopi.io/hardware/autopi-canfd-pro) and [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) (without simcard) solutions, as these does not come with a SIM card per standard. 
The solution can be purchased in our webshop. We offer different package sizes and your monthly data usage is shown from our [Cloud](https://www.autopi.io/software-platform/cloud-management) solution. 

:::tip
In case you have any questions, don't hesitate to contact us at [sales@autopi.io](mailto:sales@autopi.io).
:::

## Global coverage

Our SIM solution offers coverage in 188 countries. This is a list of our supported countries. 

| Country                | Operators                                                 |
|------------------------|-----------------------------------------------------------|
| Afghanistan            | MTN                                                       |
| Albania                | ONE Telecommunications                                    |
| Algeria                | Optimum Telecom Algerie S.p.A, Wataniya Telecom Algerie   |
| Anguilla               | CWI Carribbean Ltd, Digicel, Digicel                      |
| Antigua and Barbuda    | Cable & Wireless                                          |
| Armenia                | Telecom Armenia, K Telecom - Vivacel (MTS)                |
| Austria                | H3G Austria, A1 Telekom Austria AG                        |
| Azerbaijan             | BAKCELL LLC., Azercell Telecom B.M                        |
| Bahrain                | Batelco - Bahrain Telecommunications Company, VIVA Bahrain|
| Bangladesh             | Grameenphone                                              |
| Barbados               | Cable & Wireless                                          |
| Belgium                | Orange (Ex Mobistar), Proximus                            |
| Benin                  | Spacetel-Benin (MTN Benin), Etisalat Benin S.A            |
| Bermuda                | Bermuda Digital                                           |
| Bolivia                | Telecel, Nuevatel PCS de Bolivia SA                       |
| Bonaire                |  Mossel Digicel Curaçao & Bonaire                         |
| Bosnia and Herzegovina | m:tel, HT Mobile                                          |
| Botswana               | MASCOM                                                    |
| Brazil                 | Vivo, Claro, TIM                                          |
| British Virgin Islands | Cable & Wireless, Digicel British Virgin Islands          |
| Brunei                 | DST Communications Sdn Bhd(public)                        |
| Bulgaria               | Yettel (Telenor), A1                                      |
| Burkina Faso           | Orange                                                    |
| Cambodia               | Mobitel, Metfon                                           |
| Cameroon               | Orange Cameroun S.A., MTN                                 |
| Cape Verde             | T+ Telecomunicacões, CVTelecom                            |
| Cayman Islands         | CWI Carribbean Ltd                                        |
| Central AfricanRepublic| Orange Centrafrique                                       |
| Chad                   | Celtel Tchad (Airtel), Millicom Tchad (Tigo)              |
| China                  | China Unicom, China Mobile                                |
| Congo                  | Airtel Congo Brazzaville, MTN                             |
| Costa Rica             | Claro, I.C.E.                                             |
| Croatia                | Tele2 AB Croatia, Croatian Telecom, VIPnet                |
| Cyprus                 | MTN, CytaMobile                                           |
| Czech Republic         | O2, Vodafone                                              |
| Denmark                | Telia Mobile, Telia Mobile, Hi3G Access AB 2              |
| Dominican Republic     | Claro Dominicana, Cable & Wireless                        |
| Ecuador                | Conecel Ecuador                                           |
| Egypt                  | Orange Egypt                                              |
| El Salvador            | CTE Telecom, Telemovil, Digicel                           |
| Estonia                | Tele2 Eesti AS, Telia Eesti AS, Elisa Eesti               |
| Faroe Islands          | Faroese Telecom, Kall Vodafone                            |
| Fiji                   | Digicel Fiji and Nauru, Vodafone Fiji Ltd                 |
| Finland                | Telia Sonera, Alands Telekommunikation Ab, Elisa          |
| France                 | SFR                                                       |
| French Guiana          | Outremer Telecom, Digicel                                 |
| Gabon                  | Airtel Gabon SA, Libertis S.A.                            |
| Georgia                | Beeline, Geocell Ltd                                      |
| Germany                | Telefonica O2, VODAFONE D2                                |
| Ghana                  | MTN Ghana                                                 |
| Greece                 | WIND                                                      |
| Greenland              | Tele Greenland A/S                                        |
| Grenada                | Cable & Wireless                                          |
| Guadeloupe             | Dauphin Telecom                                           |
| Guatemala              | Claro, Comcel                                             |
| Guinea                 | Areeba/MTN-Guinea                                         |
| Guinea-Bissau          | MTN                                                       |
| Guyana                 | Guyana Telephone (Telegraph), U-Mobile (Cellular)         |
| Honduras               | Claro Honduras, Tigo Honduras                             |
| Hungary                | Vodafone                                                  |
| Iceland                | Vodafone Iceland, Siminn - Iceland Telecom Ltd            |
| Iraq                   | Asiacell                                                  |
| Ireland                | Three Ireland, Vodafone Ireland Plc                       |
| Israel                 | Pelephone                                                 |
| Italy                  | Wind, Vodafone Omnitel N.V., Telekom Italia, Hutchison 3G |
| Ivory Coast            | Orange Cote Divoire S.A. (Orange CI), MTN                 |
| Jamaica                | CWI Carribbean Ltd                                        |
| Jordan	             | Orange, Umniah Jordan                                     |
| Kazakhstan	         | Kcell JSC, Kazakhstam Tele2, KaR-Tel LLP (Beeline)        |
| Kenya	                 | Airtel Networks Kenya Limited                             |
| Kosovo	             | IPKO                                                      |
| Kyrgyzstan	         | Beeline, MegaCom                                          |
| Laos	                 | Laotel, VimpelCom Lao Co, Ltd (Beeline)                   |
| Latvia                 | Tele2, LMT Gsm                                            |
| Lesotho                | Econet Ezi Cell                                           |
| Liberia                | Lonestar (MTN), Cellcom                                   |
| Liechtenstein	         | Telekom Liechtenstein                                     |
| Lithuania              | UAB Tele2, Telia Lietuva                                  |
| Luxembourg             | Orange, POST, Tango                                       |
| Macau                  | CTM                                                       |
| Macedonia              | ONE.VIP DOO, T-Mobile Macedonia                           |
| Madagascar             | Orange Madagascar, Airtel                                 |
| Malawi                 | CelTel- ZAIN- Airtel                                      |
| Malaysia               | Digi Telecom                                              |
| Mali                   | Orange Mali, Malitel SA                                   |
| Malta                  | Epic Malte, MobIsle Communications Ltd                    |
| Martinique             | Orange Caraïbe                                            |
| Mauritania             | MAURITEL MOBILES                                          |
| Mauritius              | Cellplus Mobile Communications Ltd, Emtel, MTML           |
| Mayotte                | Societe Reunionnaise de Radiotelephone (SRR REUNION)      |
| Mexico                 | Telcel                                                    |
| Moldova                | Moldcell SA, Orange Moldava (VoXtel S.A.)                 |
| Kosovo                 | Monaco Telecom                                            |
| Mongolia               | MobiCom, SKY TEL, Unitel LLC                              |
| Montserrat             | Cable & Wireless                                          |
| Myanmar	             | Myanma Posts and Telecommunications                       |
| Namibia	             | LEO                                                       |
| Nauru	                 | Digicel Nauru                                             |
| Nepal	                 | Nepal Telecommunications Corporation                      |
| Netherlands	         | Vodafone, KPN Telecom                                     |
| Nicaragua	             | Empresa Nicaraguense de Telecomunicaciones S.A., TCN      |
| Niger	                 | Airtel, Atlantique Telecom                                |
| Nigeria	             | Airtel Nigeria, MTN Nigeria                               |
| Norway	             | Telia Norge AS, TELIASONERA NORGE AS (NETCOM AS)          |
| Panama	             | Digicel, Grupo de Comunicaciones Digitales, S.A           |
| Papua New Guinea	     | Digicel PNG                                               |
| Paraguay	             | Nucleo S.A., Claro, Tigo Paraguay                         |
| Poland	             | Orange Poland, Plus Gsm                                   |
| Portugal               | MEO, S.A., Vodafone, noS                                  |
| Romania	             | RCS & RDS, Orange Romania SA, Vodafone Romania SA         |
| Rwanda	             | Airtel Rwanda Limited, MTN Rwandacell SARL, Tigo          |
| Saint Kitts and Nevis	 | Cable & Wireless                                          |
| Saint Lucia	         | Cable & Wireless                                          |
| Saint Vincent and the Grenadines| Cable & Wireless                                 |
| Samoa	                 | DIGICEL SAMOA                                             |
| Senegal	             | Sonatel                                                   |
| Seychelles	         | Telecom (Seychelles Limited) (AIRTEL)                     |
| Sierra Leone	         | Airtel, AFR LINTEL                                        |
| Singapore	             | SingTel Mobile                                            |
| Slovakia	             | Orange, O2 Slovakia                                       |
| Slovenia	             | SI.Mobil, Telekom Slovenije                               |
| South Sudan	         | MTN SOUTH SUDAN                                           |
| Spain	                 | Telefonica Movistar, Vodafone                             |
| Sri Lanka	             | Mobitel                                                   |
| Suriname	             | Digicel                                                   |
| Swaziland	             | MTN Swaziland                                             |
| Sweden	             | Hi3G Sweden, TeliaSonera MN AB, Tele 2 AB (COMVIQ)        |
| Tanzania	             | MIC Tanzania, Airtel Tanzania, Vodacom Tanzania, ZANTEL   |
| The Gambia	         | Africell (Gambia) Ltd                                     |
| Togo	                 | Moov Togo                                                 |
| Tonga	                 | Digicel Tonga                                             |
| Trinidad and Tobago	 | Digicel                                                   |
| Turkey	             | Turk Telecom, Turkcell Iletisim Hizmetleri A.S.           |
| Turks & Caicos Islands | CWI Carribbean Ltd                                        |
| Uganda	             | MTN, Airtel Uganda                                        |
| Ukraine	             | LIFECELL ex Astelit                                       |
| United Kingdom	     | Virgin Media O2, Hutchison UK 3G, Vodafone Ltd            |
| Uruguay	             | Claro (CTI)                                               |
| Uzbekistan             | Beeline Uz, Ucell                                         |
| Vietnam	             | Vinaphone, Viettel                                        |
| Zambia                 | MTN Zambia Limited, Airtel Zambia                         |

---

## Tesla OBD-II Adapter Cable for Model 3 and Y

---

## Introduction

Do you need to connect your AutoPi device to a Tesla Model 3 or Model Y for diagnostics and data logging?

The Tesla OBD-II Adapter Cable for Model 3 and Y lets you easily connect your AutoPi device to your Tesla vehicle to start reading vehicle data and performing diagnostics. Simply locate the OBD-II port in your vehicle and plug in the adapter cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for reliable use.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Tesla OBD-II Adapter Cable for Model 3 and Y**](https://shop.autopi.io/products/tesla-obd2-adapter-cable-for-model-3-and-y).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Compatibility       | Tesla Model 3 and Model Y                         |
| Connector Types     | Tesla connector (male) to 16 PIN OBD-II (female)  |
| Supported Protocols | Tesla vehicle diagnostics                         |
| Durability          | Premium materials for reliable use                |
| Ease of Use         | Plug-and-play design                              |

## Pinout

| AutoPi Function | Tesla Connector | OBD-II 16 PIN |
|:-----------------:|:-----------------:|:---------------:|
| CAN High        | Pin 19           | Pin 6         |
| CAN Low         | Pin 18           | Pin 14        |
| Power           | Pin 1            | Pin 16         |

:::note
The pinout above is based on the standard Tesla connector to OBD-II mapping. Refer to your Tesla Model 3 or Model Y documentation for any model-specific variations.
:::

---

## Volvo 8 PIN J1939 to OBD-II Adapter Cable

---

## Introduction

Do you need to connect your AutoPi device to a Volvo truck for J1939 diagnostics and data logging?

The Volvo 8 PIN J1939 to 16 PIN OBD-II Adapter Cable fits many Volvo truck models — including heavy-duty trucks and commercial vehicles — and lets you easily connect your AutoPi device to start reading J1939 data. Simply locate the 8-pin diagnostic port in your vehicle, typically found in the cabin, and plug in the cable.

	

The cable features a plug-and-play design for quick and secure connections, and is constructed with premium materials built for heavy-duty environments.

:::info
This adapter cable can be purchased through the AutoPi shop: [**Volvo 8 PIN J1939 to 16 PIN OBD-II Adapter Cable**](https://shop.autopi.io/products/volvo-8-pin-to-16-pin-obd2-adapter-cable).
:::

## Specifications

| Property            | Details                                           |
|:---------------------:|:---------------------------------------------------:|
| Compatibility       | Volvo trucks with 8 PIN diagnostic port           |
| Connector Types     | 8 PIN (male) to 16 PIN OBD-II (female)            |
| Protocol Support    | J1939 for vehicle diagnostics                     |
| Durability          | Premium materials for heavy-duty use              |
| Ease of Use         | Plug-and-play design                              |

## Pinout

| AutoPi Function | OBD-II 16 PIN | Volvo 8 PIN |
|:-----------------:|:---------------:|:-------------:|
| Power           | Pin 16        | Pin 8       |
| GND             | Pin 4         | Pin 1       |

	

:::note
The pinout above is based on the standard J1939 to OBD-II mapping. Refer to your Volvo truck documentation for any model-specific variations.
:::

---

## Device dimensions

---

Wondering if the [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) will fit in your vehicle? Don’t worry — we’ve got you covered. This guide provides all the essential dimensions to ensure a smooth, hassle-free fit.

### Device dimensions
See the pictures below for exact measurements: 

### Need more flexibility?
If you need extra reach or want to place the device somewhere more convenient, we’ve got two handy accessories for you:

1. [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable) – Perfect for extending the reach of your device. 
2. [Dual Lock Extreme Velcro](https://shop.autopi.io/products/dual-lock-extreme-velcro) – For secure, vibration-resistant mounting anywhere you need it. 

Want to dive deeper into setup details? Check out these guides:
* OBD Connector Pinout: read more [here](https://docs.autopi.io/hardware/autopi_canfd_pro/pro-obd-connector-pinout/)   
* Mounting holes for using mounts in the vehicle and examples of device mounts: read more [here](https://docs.autopi.io/hardware/autopi_canfd_pro/mounting_options/)

---

## Technical Specifications

---

Ready to dive into what makes the [AutoPi](https://www.autopi.io/) [CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) such a powerful tool, designed for full speed automotive datalogging of dual CAN-FD channels? This guide breaks down all the key technical specs — all you need to know.

New to [AutoPi](https://www.autopi.io/)? 
Want all details in one place? **Download the official datasheet here:** [AutoPi CAN-FD Pro Datasheet](https://www.autopi.io/static/pdf/autopi_CAN_FD_Pro_datasheet.pdf)

### Full Technical Specs 
Check out the table below for an easy breakdown of everything inside the [AutoPi](https://www.autopi.io/) [CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro).

| **Name** | **Description** |
|:-----:|:--------:|
| Processor | Broadcom BCM2711 Quad-core Cortex-A72 (ARM v8) 64-bit SoC @ 1.5GHz (RPi CM4) |
| Memory | 4GB LPDDR2 SDRAM |
| Storage | 32GB on board eMMC (expandable with USB flash drive) |
| Modem | Integrated 4G/LTE Cat 4 connection (3G/EDGE fallback)  (150Mbit DL / 50Mbit UL) (Global connectivity in a single device) |
| Secure Element | Secure Element |
| Bluetooth | Bluetooth |
| GPS/GNSS | Integrated GPS + A-GPS (GPS/GLONASS/BeiDou/Galileo/QZSS) |
| Power |  Line Voltage: 12.5V AC (Car battery power). Up to 35V (Trucks).  Support for trucks with up to 35V |
| Expansion | 2 x USB, Gigabit Ethernet and HAT |
| Wireless | WiFi: 2.4GHz and 5GHz IEEE 802.11.b/g/n/ac wireless LAN  Bluetooth: Bluetooth 5.0 + Bluetooth Low Energy (BLE) |
| Accelerometer | 3-Axis accelerometer |
| Gyroscope | Built in 3-axis gyroscope |
| Automotive Interface | 2X CAN-FD interface with up to 5Mbps Data rate with integrated CAN data filters |
| Input Slots | SIM Card: Nano SIM (SIM subscription purchased separately) |
| Audio | Built-in speakers |
| Video Out | mini HDMI @ 1080p60 Video Output |
| Operating System | Raspbian OS with preconfigured AutoPi Core software |

:::tip
Our [AutoPi](https://www.autopi.io/) [CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) is built for performance and flexibility.
* **4-in-1 External Antenna**: Included with every device — supports 2x 4G/LTE, 1x GPS, and 1x WiFi/BLE for top-notch connectivity.
* **[Tailscale Add-on Pre-Installed](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/)**: Our latest feature makes remote access faster and more secure than ever. Troubleshooting on the go? No problem — you’ll be connected in no time.
:::

### 4-in-1 preinstalled antenna kit
The 4in1 Antenna Kit is a high-performance solution designed to optimize connectivity for the [AutoPi](https://www.autopi.io/) [CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro). Featuring two LTE antennas, one GPS antenna, and one WiFi antenna, this compact system delivers strong signal reception and reliable communication across multiple wireless standards. Built for demanding environments, the antenna kit ensures stable and long-term performance. 

| **Name** | **Description** |
|:-----:|:--------:|
| Antennas | 2x LTE (main and AUX), 1x GPS, and 1x Wi-Fi | 
| Wi-Fi Support | Dual-Band (2.4 GHz and 5.8 GHz) | 
| Connector Types | SMA for LTE and GPS, RP-SMA for Wi-Fi (configurable) | 
| Cable Lengths | Standard 3m cables and 10 cm U.FL connectors | 
| Mounting Options | Through-hole, adhesive, or magnetic | 
| Compatibility | LTE/4G, GSM/3G, Wi-Fi, ISM, M2M, ZigBee, Bluetooth, and more |

---

## Introduction(Hardware)

The AutoPi CAN-FD Pro is our most powerful device to date, purpose-built for full-speed automotive data logging across dual CAN-FD channels. It ships with 32 GB of onboard storage — expandable via USB flash drive — and features a built-in 4G/LTE modem for secure, reliable data transmission to your cloud solution. The device is powered by the Raspberry Pi Compute Module.

### Quick Links 
[Getting started](https://docs.autopi.io/getting_started/autopi_canfd_pro/) | [User Guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/) | [Device Dimensions](https://docs.autopi.io/hardware/autopi_canfd_pro/device_dimensions/) | [Specifications](https://docs.autopi.io/hardware/autopi_canfd_pro/device_specifications/) | [State of a Device](https://docs.autopi.io/hardware/autopi_canfd_pro/pro-led-and-button/) | [OBD Connector Pinout](https://docs.autopi.io/hardware/autopi_canfd_pro/pro-obd-connector-pinout/) | [Use Tailscale for Remote Access](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/) | [Access Files](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/) | [Data Troubleshooting](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-data-troubleshooting/) | [4G Troubleshooting](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-4g-internet-setup-troubleshooting/)

### Key Benefits

| Benefit | Description |
|:---:|:---:|
| **4G/LTE with Global Coverage** | Integrated modem with worldwide connectivity for uninterrupted data transmission. |
| **Dual CAN-FD Interface** | Native support for two simultaneous CAN-FD channels for comprehensive automotive data capture. |
| **Flexible Deployment** | Suitable for both factory-integrated OEM installations and aftermarket add-on use cases. |
| **Power Fail-Safe** | Proven power fail-safe functionality protects data integrity during unexpected power loss. |
| **Full Linux OS** | Runs a stable, well-tested Linux operating system for maximum reliability and flexibility. |
| **Highly Extensible** | Easily extended to support a wide range of business and personal applications. |
| **Upgradeable Storage & Memory** | Supports up to 32 GB storage and 4 GB memory for demanding workloads. |
| **Automotive Certified (CE/FCC)** | Certified to automotive standards for global deployment. |
| **Hardware Security Element** | Onboard NXP SE51 secure element for data encryption and signing. |
| **External Antenna Connectors** | SMA connectors for 2× 4G/LTE, 1× GPS, and 1× Wi-Fi/BLE antennas. |

For full technical details, download the official datasheet: [**AutoPi CAN-FD Pro Datasheet**](https://www.autopi.io/static/pdf/autopi_CAN_FD_Pro_datasheet.pdf)

### Highlighted Features

#### Dual-Channel CAN Bus Logging
Configure loggers in the AutoPi Cloud to capture full CAN-FD traffic from both interfaces simultaneously. Remotely adjust bitrate, enable CAN bus termination, configure bus auto-detection, and more — all without physical access to the device.

#### Flexible Storage Endpoints
Define where your data goes. Route captured data to Amazon AWS S3, store it locally on the onboard eMMC, or write it to an external USB flash drive. Storage endpoints are fully configurable from the cloud.

#### On-Device CAN Bus Decoding
Offload CAN decoding to the edge device rather than relying on expensive cloud-side processing. Upload your proprietary DBC files to decode raw CAN data directly on the device and receive clean, structured data in the cloud.

#### Remote Live Debugging
Use Tailscale to securely connect to the CAN-FD Pro from anywhere and perform live debugging and real-time CAN bus interaction. Deploy custom software using Docker images directly to the device.

#### Advanced CAN Bus Filtering
Set up precise pass and block filters based on CAN message IDs to control exactly which frames are captured and transmitted. Reduce bandwidth usage and focus on the data that matters most.

#### Data Enrichment and Encryption
Combine CAN bus data with additional sources — such as onboard IMU and GPS — or integrate external sensors for a richer dataset. Encrypt and cryptographically sign your data using the onboard NXP SE51 secure element.

### Accessories

| Accessory | Description |
|:---:|:---:|
| [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable?pr_prod_strat=jac&pr_rec_id=f2111200b&pr_rec_pid=8619775328605&pr_ref_pid=14961336746333&pr_seq=uniform) | Adds extra reach for more flexible device placement. |
| [Dual Lock Extreme Velcro Strip](https://shop.autopi.io/products/dual-lock-extreme-velcro) | Provides secure, vibration-resistant mounting on any surface. |
| [Global SIM Card Solution](https://shop.autopi.io/products/global-sim-card-solution) | Connectivity in 188 countries for truly global deployments. |
| [OBD-II Power Cable](https://shop.autopi.io/products/obd-ii-power-cable?pr_prod_strat=jac&pr_rec_id=17052e989&pr_rec_pid=8619774050653&pr_ref_pid=8609919074653&pr_seq=uniform) | Powers the CAN-FD Pro from any 12–24 V DC power supply. |
| [OBD-II Splitter Cable](https://shop.autopi.io/products/obd-ii-splitter-cable?pr_prod_strat=jac&pr_rec_id=70ef610e3&pr_rec_pid=8619777327453&pr_ref_pid=8619774050653&pr_seq=uniform) | Y-splitter for connecting an additional OBD-II device simultaneously. |
| [Tesla OBD-II Adapter Cable (Model 3 & Y)](https://shop.autopi.io/products/tesla-obd2-adapter-cable-for-model-3-and-y) | Adds an OBD-II port to Tesla Model 3 or Model Y. |
| [CAN Bus Testing/Loop Cable](https://shop.autopi.io/products/can-bus-testing-cable) | Designed for internal communication testing between two CAN bus systems. |
| [Micro USB to USB-A Adapter Cable](https://shop.autopi.io/products/micro-usb-to-usb-a-adapter-cable) | Purpose-fitted for the external Micro USB port on the CAN-FD Pro. |
| [OBD-II to Dual DB9](https://shop.autopi.io/products/obd2-to-dual-db9) | Connects two CAN bus nodes to the OBD-II port of the CAN-FD Pro. |
| [IP67 Aluminum Casing](https://shop.autopi.io/products/autopi-can-fd-pro-ip67-casing) | Rugged, weatherproof enclosure for demanding environments. |

---

## LED and Button States

---

The [AutoPi](https://www.autopi.io) [CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro) comes with an advanced smart power management (SPM) system, which will handle the lifecycle of the device. The status of SPM can be seen from the LEDs on the side of the device and can changed from software or from the Button also located on the side:

![LED and Button location](/img/hardware/autopi_tmu_cm4/led_and_button/led_button_location.png)

The following state diagram explains this lifecycle. The LED is the Blue LED on the side of the device.

![LED and Button states](/img/hardware/autopi_tmu_cm4/led_and_button/led_button_states.png)

## Button
With the button it is possible to control the state of the device:

| Action | State | Description |
| :------: | :------: | :------: |
| Long press (>3s) | Can be initated from any state. | SPM will go into **USER SETUP** state. |
| Click | **ON** State | SPM will go into **SHUTDOWN** state and thereby either into hibernate or sleep. |
| Click | **USER SETUP** State | SPM will go into **HIBERNATING** state. |
| Click | **SLEEPING** State | SPM will go into **BOOTING** state. |
| Click | **HIBERNATING** State | SPM will go into **BOOTING** state. |

## Status LEDs

### Blue LED

The blue LED indicates the current state of the [low-level ](/core/power_management/core-power-low) SPM system.

| LED State | Description |
| :------: | :------: |
| Turned off | SPM is in **OFF** state. |
| Constantly dimmed | SPM is in **HIBERNATING** state. |
| Fading in | SPM is in **BOOTING** state. |
| Fading out | SPM is in **SHUTTING DOWN** state. |
| Constantly bright | SPM is in **ON** state. |
| Breathing slow | SPM is in **SLEEP** state. |
| Flashing medium (once a second) | SPM is in **USER SETUP** state. |
| Flashing rapidly | eMMC is begin flashed |

### Green LED

The green LED indicates the current state of the [high-level](/core/power_management/core-power-high) system.

| LED State | Description |
| :------: | :------: |
| Turned off | Not running or in the process of booting up. |
| Flashing brightly | Up and running but NOT (yet) connected to the [Cloud](https://www.autopi.io/software-platform/cloud-management). |
| Constantly bright | Up and running and connected to the [Cloud](https://www.autopi.io/software-platform/cloud-management). |
| Flashing rapidly | [AutoPi](https://www.autopi.io) Core software upgrade in progress |

---

## Mounting Options

---

Want more flexibility when setting up your [AutoPi](https://www.autopi.io/) [CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro)? No worries — we’ve made installation easier than ever.

## Mounting holes on your [AutoPi](https://www.autopi.io/) [CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro)

### Need more reach?
We’ve got two essential accessories to make setup of your [AutoPi](https://www.autopi.io/) [CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro) easier. [Accessories](https://shop.autopi.io/):
  * [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable?pr_prod_strat=jac&pr_rec_id=f2111200b&pr_rec_pid=8619775328605&pr_ref_pid=14961336746333&pr_seq=uniform) – Add extra reach for flexible placement.
  * [Dual Lock Extreme Velcro Strip](https://shop.autopi.io/products/dual-lock-extreme-velcro) – Secure, vibration-resistant mounting anywhere.

### Prefer a more permanent mounting solution?
The [AutoPi](https://www.autopi.io/) [CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro) comes with built-in mounting holes — perfect for creating a custom, secure setup in your vehicle. You can find the mounting holes at the back of your [AutoPi](https://www.autopi.io/) [CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro): 

![Device mounting holes](/img/hardware/autopi_canfd_pro/canfd_pro_mounting_holes.png)

## Choose your mount
Don’t want to DIY? We’ve got you covered with pre-designed mounts made specifically for the [AutoPi](https://www.autopi.io/) [CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro).

### 1. Flat surface mount
* Perfect for dashboards, panels, or any flat surface.
* Easily screws in place or secures with adhesive.
* Snaps right onto the bottom of your AutoPi device.
[Download mount for flat surfaces](https://www.thingiverse.com/thing:6014024)

![Device mount for flat surfaces](/img/hardware/accessories/device_mounts/device_mount_3_cut.png)

### 2. Curved surface mount
* Great for pipes, curved panels, or irregular surfaces.
* Secures with adhesive or zip ties for a snug fit.
* Snaps onto the bottom of your AutoPi device just like the flat mount.
[Download mount for curved surfaces](https://www.thingiverse.com/thing:6017686)

![Device mount for curved surfeces](/img/hardware/accessories/device_mounts/device_mount_curve_1_CutV2.png)

---

## OBD Connector Pinout

---

This is an image of the OBD connector pinout. It is valid for the different generations of [AutoPi](https://www.autopi.io) devices including the [AutoPi CAN-FD Pro](https://shop.autopi.io/products/autopi-can-fd-pro).

![OBD connector pinout](/img/hardware/autopi_tmu_cm4/obd_connector_pinout/obd_pinout_CM4_ed01.png)

## In need of Accessories? Check our [AutoPi shop](https://shop.autopi.io/)
  * [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable?pr_prod_strat=jac&pr_rec_id=f2111200b&pr_rec_pid=8619775328605&pr_ref_pid=14961336746333&pr_seq=uniform) – Add extra reach for flexible placement.
  * [Dual Lock Extreme Velcro Strip](https://shop.autopi.io/products/dual-lock-extreme-velcro) – Secure, vibration-resistant mounting anywhere.
  * [Global SIM card solution](https://shop.autopi.io/products/global-sim-card-solution) - Our Global SIM card solution works in 188 countries, providing you with reliable and seamless connectivity wherever your solution is based.
  * [DoIP HAT](https://shop.autopi.io/products/doip-hat-v1-3) - The DoIP HAT is a highly advanced interface module designed to enhance vehicle diagnostics using the DoIP protocol (Diagnostics over Internet Protocol). 
  * [OBD-II Power Cable](https://shop.autopi.io/products/obd-ii-power-cable?pr_prod_strat=jac&pr_rec_id=17052e989&pr_rec_pid=8619774050653&pr_ref_pid=8609919074653&pr_seq=uniform) - Power the AutoPi CAN-FD Pro device with any 12-24 volt DC power supply.
  * [OBD-II Splitter Cable](https://shop.autopi.io/products/obd-ii-splitter-cable?pr_prod_strat=jac&pr_rec_id=70ef610e3&pr_rec_pid=8619777327453&pr_ref_pid=8619774050653&pr_seq=uniform) - Use this Y-splitter cable if you need to connect an additional OBD-II device at the same time as your AutoPi CAN-FD Pro.
  * [Tesla OBD-II Adapter Cable for Model 3 and Y](https://shop.autopi.io/products/tesla-obd2-adapter-cable-for-model-3-and-y) - Add an OBD-II port to your Tesla Model 3 or Model Y with this adapter cable.
  * [CAN Bus Testing/Loop Cable](https://shop.autopi.io/products/can-bus-testing-cable) - The CAN Bus Testing Cable is a cable designed for internal communication testing between two CAN bus systems.
  * [Micro USB-A Adapter Cable](https://shop.autopi.io/products/micro-usb-to-usb-a-adapter-cable) - This Micro USB to USB-A adapter cable is made to fit perfectly with the external Micro USB port on the AutoPi CAN-FD Pro device.
  * [OBD-II to dual DB9](https://shop.autopi.io/products/obd2-to-dual-db9) - Connect two CAN bus nodes to the OBD2 port of the AutoPi CAN-FD Pro.
  * [IP67 Aluminum Casing version of the CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro-ip67-casing) – Built tough for rugged environments.

---

## Introduction(8)

The [AutoPi CAN-FD Pro + IP67 Casing](https://shop.autopi.io/products/autopi-can-fd-pro-ip67-casing) is our most powerful automotive data logging device, engineered for full-speed dual CAN-FD channel capture. Built on the Raspberry Pi Compute Module, it features 32 GB of onboard storage (expandable via flash drive) and an integrated 4G/LTE modem for secure, real-time data delivery to your cloud environment.

Designed for demanding deployments, the device is housed in a durable, IP67-rated aluminum enclosure — resistant to dust, dirt, and water ingress — making it well-suited for rugged, outdoor, and industrial installations.

### Device dimensions

### Key benefits

| Feature | Description |
|:---:|:---:|
| **4G/LTE with global coverage** | Integrated modem with worldwide connectivity support. |
| **Dual CAN-FD interface** | Native automotive-grade dual CAN bus connectivity. |
| **OEM or aftermarket deployment** | Suitable for factory-integrated OEM builds or aftermarket installations. |
| **Power fail-safe** | Proven, integrated power protection prevents data loss on unexpected shutdowns. |
| **Full Linux OS** | Runs a stable, well-tested Linux environment with long-term reliability. |
| **Highly extensible** | Adaptable to a wide range of business and personal use cases. |
| **Upgradeable storage & memory** | Supports up to 32 GB storage and 4 GB RAM. |
| **Automotive certified (CE/FCC)** | Meets automotive certification standards for global deployment. |
| **Secure element** | Onboard NXP SE51 security chip for hardware-level encryption and data signing. |
| **External antenna connectors** | SMA connectors for 2× 4G/LTE, 1× GPS, and 1× Wi-Fi/BLE. |

For full technical specifications, download the official datasheet: [**AutoPi CAN-FD Pro Datasheet**](https://www.autopi.io/static/pdf/autopi_CAN_FD_Pro_datasheet.pdf).

---

### Highlighted features

#### CAN Bus logging from dual interface
Configure loggers in the AutoPi Cloud to capture full CAN-FD traffic from both interfaces simultaneously. Remotely adjust bitrate, CAN bus termination, and bus auto-detection settings — no physical access required.

#### Flexible storage endpoints
Define where your data goes. Route data to Amazon AWS S3, store it locally on the eMMC, or write to an external flash drive — all configured from the cloud.

#### On-device CAN bus decoding
Offload decoding to the edge device rather than processing it in the cloud. Upload proprietary DBC files to decode raw CAN data directly on the device before transmission.

#### Remote live debugging
Connect to the CAN-FD Pro via Tailscale for secure remote access. Interact with live CAN bus traffic and deploy custom projects using Docker images — without being on-site.

#### Advanced CAN bus filtering
Reduce data volume by applying pass or block filters based on individual CAN frame message IDs, ensuring only the most relevant data is captured and transmitted.

#### Data enrichment and encryption
Augment CAN data with additional sources such as onboard IMU and GPS, or integrate external sensors. All data can be encrypted and cryptographically signed using the onboard NXP SE51 secure element.

---

### Useful links

- [Getting started](https://docs.autopi.io/getting_started/autopi_canfd_pro_casing/) — Steps to follow after receiving your device.

**Accessories:**
- [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable?pr_prod_strat=jac&pr_rec_id=f2111200b&pr_rec_pid=8619775328605&pr_ref_pid=14961336746333&pr_seq=uniform) — Extends reach for more flexible device placement.
- [Dual Lock Extreme Velcro Strip](https://shop.autopi.io/products/dual-lock-extreme-velcro) — Vibration-resistant mounting solution for secure installation.
- [Global SIM Card Solution](https://shop.autopi.io/products/global-sim-card-solution) — Connectivity in 188 countries for reliable worldwide deployment.
- [DoIP HAT](https://shop.autopi.io/products/doip-hat-v1-3) — Advanced interface module for vehicle diagnostics over the DoIP protocol.
- [OBD-II Power Cable](https://shop.autopi.io/products/obd-ii-power-cable?pr_prod_strat=jac&pr_rec_id=17052e989&pr_rec_pid=8619774050653&pr_ref_pid=8609919074653&pr_seq=uniform) — Powers the CAN-FD Pro from any 12–24V DC supply.
- [OBD-II Splitter Cable](https://shop.autopi.io/products/obd-ii-splitter-cable?pr_prod_strat=jac&pr_rec_id=70ef610e3&pr_rec_pid=8619777327453&pr_ref_pid=8619774050653&pr_seq=uniform) — Y-splitter for running an additional OBD-II device alongside the AutoPi.
- [Tesla OBD-II Adapter Cable (Model 3 / Y)](https://shop.autopi.io/products/tesla-obd2-adapter-cable-for-model-3-and-y) — Adds an OBD-II port to compatible Tesla vehicles.
- [CAN Bus Testing/Loop Cable](https://shop.autopi.io/products/can-bus-testing-cable) — Designed for internal communication testing between two CAN bus systems.
- [Micro USB to USB-A Adapter Cable](https://shop.autopi.io/products/micro-usb-to-usb-a-adapter-cable) — Fits the external Micro USB port on the CAN-FD Pro device.
- [OBD-II to Dual DB9](https://shop.autopi.io/products/obd2-to-dual-db9) — Connects two CAN bus nodes to the OBD-II port of the CAN-FD Pro.

---

## Mounting Options(Autopi_canfd_pro_casing)

---

Do you need more flexibility when installing your AutoPi CAN-FD Pro with the IP67 casing? No worries, there are several practical options to make installation easier and more reliable.

## Mounting of the IP67 Casing in the Vehicle
In the images below, you can see examples of recommended mounting options for the IP67 casing. We suggest using metal mounting brackets or shaped metal plates that allow the casing to be securely screwed into the vehicle.

When selecting mounting hardware, keep the following in mind:

* Use durable, high-quality materials.
* Ensure the mounting solution can support the combined weight of the casing and the device.
* Mount the casing securely to prevent movement while driving.
* The casing includes dedicated mounting holes on both sides, make sure screws are properly tightened on all mounting points
(the image below highlights the locations of the mounting holes that can be used with brackets): 
    ![Mounting holes for AutoPi CAN-FD Pro with IP67 casing](/img/hardware/ip67/pro_casing_mounting_option.jpeg)

### Examples of the Mounting Brackets
Below, you can find examples showing how the device can be mounted using an L-shaped metal bracket. Both options provide a stable and secure mounting solution, depending on the available space in the vehicle. Two options:
* **A shorter bracket:**

    
        
        
    

* **A longer bracket:**

    
        
        
    

At the moment, we do not sell mounting accessories for Pro devices. If you have any questions or need guidance, feel free to contact us at sales@autopi.io.

---

## Accessories for AutoPi CAN-FD Pro with IP67 Casing 
If you need additional cable length for your AutoPi CAN-FD Pro, you can use an OBD-II Extension Cable. This is especially useful when the device needs to be mounted away from the OBD-II port.
You can find the extension cable on our webshop: [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable)

---

## Wiring of the IP67 Casing
When connecting antennas to the IP67 casing, make sure the device is oriented correctly. With the AutoPi logo facing upward, the antenna ports are arranged as follows:
* Right side (top to bottom):
  * 4G
  * GPS
  * 4G
  ![Right side of the AutoPi CAN-FD Pro with IP67 casing](/img/hardware/shared_devices/autopi_pro_casing_sticker.png)

* Left side (top to bottom):
  * OBD-II 
  * Empty 
  * Wi-Fi

:::note    
Correct antenna placement ensures optimal connectivity and performance.
:::

---

## Screw terminal pinouts for IP67

---

The [AutoPi](https://www.autopi.io/) [CAN-FD Pro device](https://shop.autopi.io/products/autopi-can-fd-pro) is packed into a durable, IP67-rated aluminum casing — built to withstand dust, dirt, and water, making it perfect for rugged, outdoor, or industrial installations. Inside the device it's possible to access additional GPIO pins for your project. These are conviniently located at a set of screw terminal blocks inside the device. There is 23 connections in total:

    

The screw terminals is applied to a custom AutoPi HAT board located inside the CAN-FD Pro device, giving you easy access to a number of selected pins:

    

The pinouts have the following functions assigned, note some of them are already pre assigned for the OBD-II connector on the device:

| Pin | Function | Used | Description |
| :------: | :------: | :------: | :------: |
| Pin 1 | HS_CAN_HI | Yes | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 2 | HS_CAN_LO | Yes | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 3 | MS_CAN_HI | Yes | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 4 | MS_CAN_LO | Yes | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 5 | Vcc12V | Yes | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 6 | GND | Yes | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 7 | RPI_GPIO22 | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 8 | RPI_GPIO24 | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 9 | RPI_GPIO27 | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 10 | Vcc5V_EXT  | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 11 | Vcc3V3_EXT | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 12 | RPI_PWR | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 13 | PICO_EXT_17 | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 14 | PICO_EXT_28 | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 15 | Vcc5V | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 16 | GND | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 17 | RPI_GPIO23 | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 18 | RPI_ID_SD | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 19 | RPI_ID_SC | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 20 | Vcc3V3 | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 21 | GND | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 22 | EXT_WAKE_12V | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |
| Pin 23 | GND | No | [See here](/hardware/autopi_tmu_cm4/using-hat/#pinout) |

If you want to use some of the additional pins in the screw terminal, then its important that you use the correct cable transfer out of the box, to maintain the IP67 integrety. An alternative is to use some of the unused cables in the OBD connector as this is already IP67 rated. These unused cables has been neatly tied up inside the box in flex wrapping.

---

## Specifications

---

Download the official datasheet here: 
[Autopi Mini Datasheet](https://www.autopi.io/static/pdf/autopi_mini_datasheet.pdf)

## Device Specifications 
| **Name** | **Description** |
|:-----------------------------------:|:-----------------------------------------------------------------:|
|   Physical specifications    |   **Weight:** 63 g  **Dimensions:** 67,2 x 49,6 x 25 mm (L x W x H)   | 
|   Modem (EMEA variant)   |  Integrated 4G/LTE Cat 1 connection  **4G (LTE-FDD):**  B1, B3, B7, B8, B20, B28  **4G (LTE-TDD):** B38, B40, B41  **2G (GSM):** B2, B3, B5, B8  | 
|   Modem (APAC/LATAM variant)  | Integrated 4G/LTE Cat 1 connection  **4G (LTE-FDD):**  B1, B2, B3, B4, B5, B7, B8, B20, B28  **4G  (LTE-TDD):** B40  **2G (GSM):** B2, B3, B5, B8       | 
|   Modem (NA variant)   |   Integrated 4G/LTE Cat 1 connection (3G/EDGE fallback)  **4G (LTE FDD):** B2, B4, B5, B12, B13  **3G (WCDMA):** B2, B4, B5     |  
|   Certifications    |   CE/RED/UKCA, E-Mark, EAC, RoHS, REACH, RCM, SDPPI POSTEL, CITC     |   
|   GPS    |   Integrated GPS + A-GPS.  **Supports:** GPS/GLONASS/BeiDou/Galileo/SBAS/QZSS/DGPS  **Receiver:** 33 channel  **Tracking sensitivity:** -165 dBM  **Position Accuracy:** < 2.5 m CEP  **Hot start:** < 1 s  **Warm start:** < 25 s  **Cold start:** < 35 s  **Velocity Accuracy:** < 0.1 m/s (within +/- 15% error) |  
|   Power    |  Built-in Power Management system to prevent the vehicle’s battery from being drained  **Input voltage range:** 10–30 V DC with overvoltage and reverse polarity protection  **Back-up battery:** 170 mAh Li-Ion battery (0.63 Wh)  **Power consumption:**  At 12V < 3 mA (Ultra Deep Sleep)  At 12V < 5 mA (Deep Sleep)  At 12V < 16 mA (Online Deep Sleep)  At 12V < 18 mA (GPS Sleep)  At 12V < 33 mA (nominal)      | 
|   Wireless   |  **Bluetooth:** Bluetooth 4.0 + Low Energy (BLE)  |    
|   Accelerometer   | Built in 3-axis accelerometer |
|   Automotive Interface    |  **Data:** K-Line, CAN bus data  **Data reading:**  Up to 32 vehicle onboard parameters, supported OBD protocols:  ISO 9141-2 (5 baud init, 10.4 kbaud)  ISO 14230-4 KWP (5 baud init, 10.4 kbaud)  ISO 14230-4 KWP (fast init, 10.4 kbaud)  ISO 15765-4 CAN (11 bit ID, 250 kbaud)  ISO 15765-4 CAN (11 bit ID, 500 kbaud)  ISO 15765-4 CAN (29 bit ID, 250 kbaud)  ISO 15765-4 CAN (29 bit ID, 500 kbaud)      |  
|   Data parameters support   |   **30+ Parameters from OBD port**  Mileage / Fuel / RPM / Speed / Engine temperature / DTC / Engine load value / Coolant temperature / Short and long term fuel trim bank / Fuel pressure / Intake MAP / Engine RPM / Vehicle speed / Timing advance / Intake air temperature / MAF throttle position / Run time since engine start / Fuel rail pressure relative / Fuel rail pressure direct / Commanded EGR / EGR error / Fuel level / Distance traveled codes cleared / Barometric pressure / Control module voltage / Absolute load value / OBD Ambient air temperature / Time since codes cleared / Absolute fuel rail pressure / Hybrid battery pack remaining life / Engine oil temperature / Fuel injector timing / Fuel rate / VIN / DTC value / Distance and time traveled since Malfunction Indicator Lamp ON/ EV Milage / EV Range / EV Battery level / Ignition status     |  
|   Input slots     |  **SIM Card:** Nano SIM – Comes with SIM card and subscription pre-installed      |   
|   Absolute Maximum  Operating Environment    |  **Operating Temperature:** -40° to +85° C (-40° to +185° F)  **Relative Humidity:** 5% to 95% Noncondensing      |  

## LED Lights of an AutoPi Mini Device
AutoPi Mini has 2 LED lights: Navigation LED and Status LED. These LED lights helps you understand the status of the GNSS and device's operating status. Both LED lights are described more in depth below: 

1. **Navigation LED(closer to the edge of the device):**
    
    This LED indicates the status of the GNSS (Global Navigation Satellite System).
    - **Green and blinking slowly:** The device is receiving a GNSS signal. 
    - **Solid green:** The device is not receiving a GNSS signal. 
    - **Off:** This may indicate the device is either in sleep mode or experiencing an issue. 

2.  **Status LED (farther from the edge of the device):**
    
    This LED reflects the device’s operating status.
    - **Blinking every second:** The device is in normal operating mode. 
    - **Blinking every 2 seconds:** The device is in sleep mode. 
    - **Fast blinking:** Indicates modem activity. 
    - **Off:** This could mean the device is not functioning. 

If either LED is not behaving as expected, it could be a sign of connectivity or 
hardware issues that need attention. Try to disconnect it from the OBD-II port, 
then reconnect it. Wait until both lights are green and blinking.  

![AutoPi Mini LED meaning](/img/getting_started/autopi_mini/data_troubleshooting/mini_light_placements_01.png)

---

## Introduction(9)

This section has a few guides written out that are specifically for the [AutoPi](https://www.autopi.io) [Mini](https://www.autopi.io/hardware/autopi-mini) devices. 

## Quick Links
[Getting Started](https://docs.autopi.io/getting_started/autopi_mini/) | [Device Specifications](https://docs.autopi.io/hardware/autopi_mini/device_specifications/) | [Create Loggers](https://docs.autopi.io/getting_started/autopi_mini/create-mini-loggers/) | [Data Troubleshooting](https://docs.autopi.io/getting_started/autopi_mini/mini-data-troubleshooting/) | [Advanced settings](https://docs.autopi.io/cloud/device_management/advanced_settings/autopi_mini/)

## Key Benefits
- **4G/LTE with global coverage:** The integrated modem with worldwide coverage.
- **Built in OBD interface:** Native OBD interface with support for legacy protocols, such as K-line and KWP.
- **Plug and play installation:** Our fastest installation to date.

## Accessories 
  * [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable?pr_prod_strat=jac&pr_rec_id=f2111200b&pr_rec_pid=8619775328605&pr_ref_pid=14961336746333&pr_seq=uniform) – Add extra reach for flexible placement.
  * [Dual Lock Extreme Velcro Strip](https://shop.autopi.io/products/dual-lock-extreme-velcro) – Secure, vibration-resistant mounting anywhere.
  * [Global SIM card solution](https://shop.autopi.io/products/global-sim-card-solution) - Our Global SIM card solution works in 188 countries, providing you with reliable and seamless connectivity wherever your solution is based.
  * [OBD-II Power Cable](https://shop.autopi.io/products/obd-ii-power-cable?pr_prod_strat=jac&pr_rec_id=17052e989&pr_rec_pid=8619774050653&pr_ref_pid=8609919074653&pr_seq=uniform) - Power the AutoPi Mini device with any 12-24 volt DC power supply.
  * [OBD-II Splitter Cable](https://shop.autopi.io/products/obd-ii-splitter-cable?pr_prod_strat=jac&pr_rec_id=70ef610e3&pr_rec_pid=8619777327453&pr_ref_pid=8619774050653&pr_seq=uniform) - Use this Y-splitter cable if you need to connect an additional OBD-II device at the same time as your AutoPi Mini.
  * [Tesla OBD-II Adapter Cable for Model 3 and Y](https://shop.autopi.io/products/tesla-obd2-adapter-cable-for-model-3-and-y) - Add an OBD-II port to your Tesla Model 3 or Model Y with this adapter cable.
  * [OBD-II to dual DB9](https://shop.autopi.io/products/obd2-to-dual-db9) - Connect two CAN bus nodes to the OBD2 port of the AutoPi Mini.

:::tip
You can download the official datasheet here: [Autopi Mini Datasheet](https://www.autopi.io/static/pdf/autopi_mini_datasheet.pdf)
:::

---

## Device Dimensions(Autopi_tmu_cm4)

---

In this guide, you’ll find all the necessary device dimensions to make sure your device fits seamlessly into your vehicle.

Need more flexibility for placement? No problem! You can grab an extension cable from our shop for extra reach, or use a velcro strip (also available in our shop) to securely attach the device wherever it works best for you. 
* Buy OBD-II Etension cable [here](https://shop.autopi.io/products/obd-ii-extension-cable)
* Buy Dual Lock Extreme Velcro [here](https://shop.autopi.io/products/dual-lock-extreme-velcro)

Here are device dimensions:

![Device dimensions](/img/hardware/autopi_tmu_cm4/device_dimensions/device_dimensions_4.png)

![Device dimensions](/img/hardware/autopi_tmu_cm4/device_dimensions/device_dimensions_5.png)

![Device dimensions](/img/hardware/autopi_tmu_cm4/device_dimensions/device_dimensions_6.png)

---

## Technical Specifications(Autopi_tmu_cm4)

---

This guide contains everything you need to know about the AutoPi TMU CM4 device's technical specifications. You can also read more on how to [Get started with AutoPi TMU CM4](https://docs.autopi.io/getting_started/autopi_tmu_cm4/). 

Download the official datasheet here: 
[TMU CM4 Datasheet](https://www.autopi.io/static/pdf/autopi_TMU_CM4_datasheet.pdf)

| **Name** | **Description** |
|:-----:|:--------:|
|   Processor **(NEW)**   |   Broadcom BCM2711 Quad-core Cortex-A72 (ARM v8) 64-bit SoC @ 1.5GHz    | 
|   Memory    |  1GB LPDDR4 SDRAM  **Upgrade:** 2GB, 4GB or 8GB LPDDR4 SDRAM (depending on model)     | 
|   Storage **(NEW)**    |   8GB on board eMMC  **Upgrade:** 16GB and 32GB (depending on model)     | 
|   Size, Weight and Casing    |   **Casing:** Improved expansion options with exchangeable back shield for external antennas, additional USB ports, ethernet port.     | 
|   Modem    |   Integrated 4G/LTE Cat 4 connection (3G/EDGE fallback)  150Mbit DL / 50Mbit UL  Worldwide support in a single device  **4G LTE Bands (Global):** B1 / B2 / B3 / B4 / B5 / B7 / B8 / B12 / B13 / B18 / B19 / B20 / B25 / B26 / B28 / B38 / B39 / B40 / B41  **3G Fallback (WCDMA):** B1 / B2 / B4 / B5 / B6 / B8 / B19  **EDGE Fallback:** B2 / B3 / B5 / B8 / Quad-band     |  
|   Certifications    |   EN 301 489-1 v2.2.0, EN55025:2008, EN 50498 and Directive 2004/104/EC, ISO 7637-2:2011, EN 301 489-3 V2.1.1, FCC 47 CFR Part 15, Class A:10–1–17 Edition     |  
|   Security Element **(NEW)**    |   Hardware Based Secure Key Management  **Public Key Algorithms:** RSA and ECC asymmetric, AES and DES symmetric cryptography algorithms. HMAC, CMAC, SHA-1, SHA-224/256/384/512 operations  **Crypto Curves:** ECC NIST, Brainpool, Twisted Edwards Ed2551, Montgomery Curve25519, Koblitz, Barreto-Naehrig Curve, Montgomery Curve448  Secure Storage of Keys, Certificates and Data  Unique Serial Number  Intrusion Detection   | 
|   GPS    |   Integrated GPS + A-GPS.  **Supports:** GPS/GLONASS/BeiDou/Galileo/QZSS     |  
|   Power    |  **Line Voltage:** 12.5V AC (Car battery power). Up to 35V (Trucks).  Support for trucks with up to 35V  Built-in Power Management system to prevent the vehicle’s battery from being drained     | 
|   Expansion **(NEW)**   |  **2 X USB:** USB 2.0  **Ethernet:** Built in Ethernet  **GPIO:** UART/I2C/SPI  |  
|   Wireless    |  Built on Cypress CYW43455 Chipset  **WiFi:** 2.4GHz and 5GHz IEEE 802.11.b/g/n/ac wireless LAN  **Bluetooth:** Bluetooth 5.0 + Bluetooth Low Energy (BLE      |  
|   Accelerometer    |  Built in 3-axis accelerometer      |  
|   Gyroscope   |   Built in 3-axis gyroscope     |  
|   Automotive Interface    |  **2 X CAN:** CAN interface with up to 1Mbps Data rate with integrated CAN data filter  **DoIP:** Upgradeable to allow support for DoIP      | 
|   Input slots     |  **SIM Card:** Nano SIM – Not Included      |  
|   Audio    |  Built-in speakers      | 
|   Video Out    |  HDMI @ 1080P60 Video Output      |   
|   Absolute Maximum  Operating Environment    |  **Operating Temperature:** -20° TO 70° C (-4° TO 158° F)  **Relative Humidity:** 0% TO 75% Noncondensing      |  
|   Operating System    |  Raspbian OS with preconfigured AutoPi Core      |

---

## Introduction(10)

This section contains comprehensive documentation for the [AutoPi TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device. While the content is tailored specifically for this device, many concepts may apply to earlier generation models.

## Quick Links
[Getting started](https://docs.autopi.io/getting_started/autopi_tmu_cm4/) | [Dimensions](https://docs.autopi.io/hardware/autopi_tmu_cm4/device_dimensions/) | [Specifications](https://docs.autopi.io/hardware/autopi_tmu_cm4/device_specifications/) | [State of the device](https://docs.autopi.io/hardware/autopi_tmu_cm4/led-and-button/) | [OBD connector pinout](https://docs.autopi.io/hardware/autopi_tmu_cm4/obd-connector-pinout/) | [Missing data](https://docs.autopi.io/getting_started/autopi_tmu_cm4/cm4-data-troubleshooting/) | [4G Troubleshooting](https://docs.autopi.io/getting_started/autopi_tmu_cm4/4g-internet-setup-troubleshooting/) 

## Core Features

| Feature | Description |
|:---------:|:-------------:|
| **Global 4G/LTE Connectivity** | Integrated modem with worldwide coverage |
| **Dual CAN Interface** | Native support for dual CAN bus connections with expansion capabilities |
| **Flexible Deployment** | Works as both factory-integrated OEM solution and aftermarket add-on |
| **Power Fail-Safe Design** | Proven fail-safe power management for seamless operation |
| **Full Linux OS** | Runs on proven, stable Raspberry Pi OS with long-term support |
| **Infinite Extensibility** | Customizable for business and personal use cases |
| **Upgradeable Hardware** | Support for CPU and RAM expansion |
| **Automotive Certified** | CE and FCC certified for global automotive use |
| **Built-in Security** | Secure data encryption and protection |

## Key Technical Highlights

### Advanced Automotive Interface
The device features a dual CAN interface with support for multiple parallel connections. The integrated Diagnostics over IP (DoIP) support enables advanced vehicle diagnostics capabilities.

### Linux-Based Operating System
Built on Raspberry Pi OS, AutoPi Core provides a robust, well-tested foundation with extensive possibilities for extensions and integrations. The open-source architecture ensures long-term stability and compatibility.

### Open-Source Architecture
Full access to open-source drivers and core implementations via the AutoPi GitHub repository enables custom development and community contributions.

### High-Performance Computing
Broadcom BCM2711 Quad-core Cortex-A72 processor (ARM v8) running at 1.5GHz delivers enterprise-grade performance. Includes 1GB LPDDR4 RAM with integrated GPU. Upgradeable to higher memory configurations for demanding applications.

## Optional Accessories

### Connectivity & Power
- [Global SIM Card Solution](https://shop.autopi.io/products/global-sim-card-solution) – Works in 188+ countries with reliable global connectivity
- [OBD-II Power Cable](https://shop.autopi.io/products/obd-ii-power-cable) – Power your device from any 12-24V DC power supply

### OBD Expansion & Interface
- [OBD-II Extension Cable](https://shop.autopi.io/products/obd-ii-extension-cable) – Extends reach for flexible device placement in any vehicle
- [OBD-II Splitter Cable](https://shop.autopi.io/products/obd-ii-splitter-cable) – Connect additional OBD-II devices simultaneously
- [OBD-II to Dual DB9 Adapter](https://shop.autopi.io/products/obd2-to-dual-db9) – Connect two CAN bus nodes to the OBD2 port
- [Tesla OBD-II Adapter (Model 3/Y)](https://shop.autopi.io/products/tesla-obd2-adapter-cable-for-model-3-and-y) – Add OBD-II port to Tesla vehicles

### Advanced Diagnostics
- [DoIP HAT](https://shop.autopi.io/products/doip-hat-v1-3) – Advanced Diagnostics over IP (DoIP) interface module for enhanced vehicle diagnostics

### Mounting & Integration
- [Dual Lock Extreme Velcro Strip](https://shop.autopi.io/products/dual-lock-extreme-velcro) – Secure, vibration-resistant mounting solution
- [Micro USB-A Adapter Cable](https://shop.autopi.io/products/micro-usb-to-usb-a-adapter-cable) – Compatible external USB adapter for TMU CM4

---

## Installing 3-in-1 External Antennas

---

:::caution Before proceeding with the upgrade
Please read the **whole guide** in order to have a good understanding of how all the components fit together.

You need to be careful not to tear or damange some of the cables when handling the casing of the device.
:::

If you've purchased the [Antenna Kit](https://shop.autopi.io/products/3in1-external-antenna-kit) 
alongside your [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4), this guide will help you through the 
installation process. The kit allows you to boost 4G/LTE connectivity and 
GPS signal strength, which is especially useful if you frequently drive
in areas with weak signal reception. 

**What's included:** 
- **3x SMA adapter cables** (for internal installation) 
- **1x 4G/LTE & GPS combo antenna** (with 3M adhesive pad and 300cm cable) 
- **1x Side shield** (for 3x SMA connectors) 

### Pre-installed Antennas
If you opted for pre-installed antennas through our shop or by contacting our 
sales team, your device will arrive with the antennas already in place. All that's
left to do is to connect the cables to the corresponding antenna ports. Please refer
to the image below for guidance. 

![Device with antenna](/img/hardware/autopi_tmu_cm4/installing_external_antennas/antenna_device.png)

Then all you need to do is to connect the device to the vehicle’s OBD-II and place
the adhesive pad on the dashboard or other suitable place.  

### Installing the Antennas: 

If you are installing the antennas yourself, follow the Step-by-Step guide.

:::success
**Prerequesites** for this guide:
- An [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device
- External antennas kit provided by [AutoPi](https://www.autopi.io)
:::

### Step-by-Step Guide

	
		Step 1: 
		Take your [AutoPi](https://www.autopi.io) and flip it so you can face the bottom of the device. Unscrew the bottom cover of the device and get out the shield that was previously installed and disconnect the internal antennas. 
	
	

	
		Step 2: 
		Next, plug in each of the antennas in their respective socket as seen in the picture bellow: 
		 
		 	The GPS antenna (the one that is separated) should be connected to the left side connector of the modem 
		 	The middle antenna (Main 4G) should be connected to the middle connector of the modem
			The right antenna (Alt. 4G) should be connected to the right connector of the modem
			
			
			Note: 
			Please make sure that the antennas are not stuck in between the casings or that they are accidentally screwed in when you put back the screws in the casing. Once installed,
			don't tighten the SMA nut anymore because the cables will twist and be damaged in the interior of the device.
	
	

	
		Step 3: 
		Mount the shield inside the small cutout that runs along the side of the device. 
		Note: 
			Please make sure that the antennas are not stuck in between the casings or that they are accidentally screwed in when you put back the screws in the casing.
	
	

	
		Step 4: 
		Screw back in the four metal screws that you took out in the beginning. You don’t have to worry about where to put them as they all have the same dimensions. 
	
	

	
		Step 5: 
		Check that all the components are placed in their place and that there are no spaces between the casing!
	
	

 

### Disscussion

	You have now successfully installed external antennas in your [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device.

---

## Installing 4-in-1 External Antennas

---

:::caution Before proceeding with the upgrade
Please read the **whole guide** in order to have a good understanding of how all the components fit together.

You need to be careful not to tear or damange some of the cables when handling the casing of the device.
:::

If you've purchased the [4-in-1 Antenna Kit](https://shop.autopi.io/products/4-in-1-car-antenna-lte-x2-gps-wifi) 
alongside your [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4), this guide will help you through the 
installation process. The kit allows you to boost 4G/LTE connectivity, 
GPS signal strength and BLE/WiFI signal, which is especially useful if you frequently drive
in areas with weak signal reception. 

**What's included:** 
- **4x SMA adapter cables** (for internal installation) 
- **1x 4G/LTE, GPS and BLE/WiFi combo antenna** (with 3M adhesive pad) 
- **1x Side shield** (for 4x SMA connectors) 

### Pre-installed Antennas
If you opted for pre-installed antennas through our shop or by contacting our 
sales team, your device will arrive with the antennas already in place. All that's
left to do is connect the cables to the corresponding antenna ports. Please refer
to the image below for guidance. 

	

Then all you need to do is to connect the device to the vehicle’s OBD-II and place
the adhesive pad on the dashboard or other suitable place.  

### Installing the Antennas: 

If you are installing the antennas yourself, follow the Step-by-Step guide.

:::success
**Prerequesites** for this guide:
- An [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device
- External 4-in-1 antennas kit provided by [AutoPi](https://www.autopi.io)
:::

### Step-by-Step Guide

	
		Step 1: 
		Take your [AutoPi](https://www.autopi.io) and flip it so you can face the bottom of the device. Unscrew the bottom cover of the device and get out the shield that was previously installed and disconnect the internal antennas. 
	
	

	
		Step 2: 
		The first antenna we need to install is the BLE/WiFI antenna. This is the left most antenna on the shield, seen from the outside. The u.Fl. connector connects to the Compute module as shown in the picture. 
	
	

	
		Step 3: 
		Next we need to connect the antennas to the modem. Plug in each of the antennas in their respective socket as seen in the picture bellow: 
		 
		 	The GPS antenna should be connected to the left side connector of the modem 
		 	The middle antenna (Main 4G) should be connected to the middle connector of the modem
			The right antenna (Alt. 4G) should be connected to the right connector of the modem
					
	
	

	
		Step 4: 
		Carefully insert the new SMA shield in the side of the device. 
		Note: 
		Please make sure that the antennas are not stuck in between the casings or that they are accidentally screwed in when you put back the screws in the casing. Once installed,
		don't tighten the SMA nut anymore because the cables will twist and be damaged in the interior of the device.
	
	

	
		Step 5: 
		Screw back in the four metal screws that you took out in the beginning. You don’t have to worry about where to put them as they all have the same dimensions. Check that all the components are placed in their place and that there are no spaces between the casing!
	
	

 

### Disscussion

	You have now successfully installed external antennas in your [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device.

---

## Install Heatsink

---

:::caution Before proceeding with the upgrade
Please read the **whole guide** in order to have a good understanding of how all the components fit together.

You need to be careful not to tear or damange some of the cables when handling the casing of the device.
:::

:::success
**Prerequesites** for this guide:
- An [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device
- Heatsink package provided by [AutoPi](https://www.autopi.io)
:::

### Step-by-Step Guide

	
		Step 1: 
		Open up the bag with the heatsink and the accessories.
	
	

	
		Step 2: 
		Find the 4 metal screws and the 4 spacers. 
	
	

	
		Step 3: 
		Apply the thermal tape to the Ethernet IC and the CPU as show on the image. 
	
	

	
		Step 4: 
		Fix the heatsink on the thermal tape and fasten it using the metal screw. Remember to use the spacer between the screw and the heatsink. 
	
	

### Disscussion

	You have now successfully installed a heatsink onto your [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device.

---

## LED and Button States(Autopi_tmu_cm4)

---

The [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) comes with an advanced smart power management (SPM) system, which will handle the lifecycle of the device. The status of SPM can be seen from the LEDs on the side of the device and can changed from software or from the Button also located on the side:

![LED and Button location](/img/hardware/autopi_tmu_cm4/led_and_button/led_button_location.png)

The following state diagram explains this lifecycle. The LED is the Blue LED on the side of the device.

![LED and Button states](/img/hardware/autopi_tmu_cm4/led_and_button/led_button_states.png)

## Button
With the button it is possible to control the state of the device:

| Action | State | Description |
| ------ | ------ | ------ |
| Long press (>3s) | Can be initated from any state. | SPM will go into **USER SETUP** state. |
| Click | **ON** State | SPM will go into **SHUTDOWN** state and thereby either into hibernate or sleep. |
| Click | **USER SETUP** State | SPM will go into **HIBERNATING** state. |
| Click | **SLEEPING** State | SPM will go into **BOOTING** state. |
| Click | **HIBERNATING** State | SPM will go into **BOOTING** state. |

## Status LEDs

### Blue LED

The blue LED indicates the current state of the [low-level ](/core/power_management/core-power-low) SPM system.

| LED State | Description |
| ------ | ------ |
| Turned off | SPM is in **OFF** state. |
| Constantly dimmed | SPM is in **HIBERNATING** state. |
| Fading in | SPM is in **BOOTING** state. |
| Fading out | SPM is in **SHUTTING DOWN** state. |
| Constantly bright | SPM is in **ON** state. |
| Breathing slow | SPM is in **SLEEP** state. |
| Flashing medium (once a second) | SPM is in **USER SETUP** state. |
| Flashing rapidly | eMMC is begin flashed |

### Green LED

The green LED indicates the current state of the [high-level](/core/power_management/core-power-high) system.

| LED State | Description |
| ------ | ------ |
| Turned off | Not running or in the process of booting up. |
| Flashing brightly | Up and running but NOT (yet) connected to the [Cloud](https://www.autopi.io/software-platform/cloud-management). |
| Constantly bright | Up and running and connected to the [Cloud](https://www.autopi.io/software-platform/cloud-management). |
| Flashing rapidly | [AutoPi](https://www.autopi.io) Core software upgrade in progress |

---

## Mounting Holes

---

Mounting holes can be used to create mounts for easier installation in the vehicle. 

![Mounting holes](/img/hardware/autopi_tmu_cm4/mounting_holes/mounting_holes.png)

We have a number of pre-designed mounts available for the [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4). You can see those [device mounts here ](/hardware/accessories/device_mounts)

---

## OBD Connector Pinout(Autopi_tmu_cm4)

---

This is an image of the OBD connector pinout. It is valid for the [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) editions generations of the [AutoPi](https://www.autopi.io).

![OBD connector pinout](/img/hardware/autopi_tmu_cm4/obd_connector_pinout/obd_pinout_CM4_ed01.png)

---

## Replacing the CM4

---

:::caution Before proceeding with the upgrade
Please read the **whole guide** in order to have a good understanding of how all the components fit together.

You need to be careful not to tear or damange some of the cables when handling the casing of the device.
:::

:::success
**Prerequesites** for this guide:
- An [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device
- New Raspberry Pi CM4
- You can buy the new CM4 from: https://www.raspberrypi.com/products/compute-module-4/?variant=raspberry-pi-cm4001000
:::

### Step-by-Step Guide

	
		Step 1: 
		Take your [AutoPi](https://www.autopi.io) and flip it so you can face the bottom of the device. Unscrew the bottom cover of the device and remove the shields. 
	
	

	
		Step 2: 
		Using a PH2 screwdriver, carefully remove the four screws that are securing the heatsink to the CM4, as indicated in the image below.
	
	

	
		Step 3: 
		Transfer the heat transfer pads from the original Raspberry Pi to the new Raspberry Pi CM4. 
	
	

	
		Step 4: 
		Using a 5mm screwdriver, loosen and remove the four screws that are securing the CM4 to the [AutoPi](https://www.autopi.io) board, as shown in the picture below.	
	
	

	
		Step 5: 
		Gently disconnect the CM4 from the [AutoPi](https://www.autopi.io) board, ensuring to handle both components with care to avoid any damage.
	
	

:::caution Before proceeding with the installation of the new CM4
Please take note of the orientation of the CM4 while detaching it from the [AutoPi](https://www.autopi.io) board. The two connectors on the CM4 doesn't have a symmetrical position in relation to the edge, so be mindful of aligning them correctly to ensure a proper connection.
:::

	

		Step 6: 
		After verifying the correct orientation, proceed with the installation of the new CM4. Ensure that the CM4 connectors are securely pushed in until fully seated.

	
		Step 7: 
		Reattach the 4 hexagonal screws that secure the CM4 to the [AutoPi](https://www.autopi.io) board, ensuring a firm and secure connection.	
	
	

	
		Step 8: 
 		Securely reattach the heatsink to the CM4 using the 4 screws and plastic washers provided. Ensure that each screw is tightened firmly for optimal heat dissipation. 
		When reattaching the heatsink, ensure that you align the cut in the heatsink with the SMA connector of the CM4.	
	
	

	
		Step 8: 
 		Carefully position the shield over the designated holes and insert it securely. Once the shields are in place, position the bottom case over the board, ensuring that all the components fit properly. Press down gently to ensure a snug fit between the bottom case and the board. 
		Using the 4 black hex screws provided, securely fasten the bottom case to the board. Tighten the screws firmly, but be careful not to overtighten and risk damaging the components.	
	
	

		Step 8: 
		To flash or reflash your [AutoPi](https://www.autopi.io) CM4 device, it is recommended to refer to the official manual provided with the device. The manual will contain specific instructions tailored to your [AutoPi](https://www.autopi.io) CM4 model, ensuring the proper and safe execution of the flashing process. Please consult the manual for detailed step-by-step guidance on how to flash or reflash your [AutoPi](https://www.autopi.io) CM4 device. 

[Reflashing your device](/developer_guides/reflashing_your_device.md)

	You have now successfully replaced your Raspberry Pi CM4 in your [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) device.

---

## Using the HAT

---

The [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4) comes with an integrated 40 pin header (1.27mm pitch). It is possible to use the header to design HAT (Hardware Attached on Top) boards that greatly extends the functionality of the device. The image below shows the placement of the HAT on the board. It has been designed, so that a new HAT can fit into the casing.

![HAT Placement](/img/hardware/autopi_tmu_cm4/using_hat/cm4_pcb_Pinlayout.png)

## HAT Component Parts

| **Type** | **Manufacturer** | **Part Number** | **Datasheet** | **Comments** |
|:-----:|--------|--------|--------|--------|
|   Male   |    Greenconn     |   GPEC209-2002B009C1BF    | [Datasheet](https://www.greenconn.com) | Alternative manufacturer available | 
|   Female   |    Amphenol ICC (FCI)    |   20021321-00040C1LF    | [Datasheet](https://cdn.amphenol-cs.com/media/wysiwyg/files/documentation/datasheet/boardwiretoboard/bwb_minitek127_btb.pdf) | Alternative manufacturer available | 

## Pinout
The following table is an explanation of each pinout. The type describes the usage of the pin as defined in the RP2040 firmware:

| **Pin** | **Name** | **Description** | **Type** | **Comments** |
|:-----:|--------|--------|--------|--------|
|   1   |    HS_CAN_HIGH / OBD_PIN_6    |  Connection to CAN0 High line and directly to OBD pin     | Bi-directional | | 
|   2    |   HS_CAN_LOW / OBD_PIN_14     | Connection to CAN0 Low line and directly to OBD pin      | Bi-directional | |
|   3    |   MS_CAN_HIGH / OBD_PIN_3     | Connection to CAN1 High line and directly to OBD pin      | Bi-directional | |
|   4    |   MS_CAN_LOW / OBD_PIN_11     | Connection to CAN1 Low line and directly to OBD pin      | Bi-directional | |
|   5    |   OBD_PIN_1     |   Directly connected to OBD pin     | Bi-directional | |
|   6    |   OBD_PIN_7     |    Directly connected to OBD pin    | Bi-directional | |
|   7    |   OBD_PIN_15     |  Directly connected to OBD pin      | Bi-directional | |
|   8    |   OBD_PIN_2     |   Directly connected to OBD pin     | Bi-directional | |
|   9    |   OBD_PIN_10     |  Directly connected to OBD pin      | Bi-directional | |
|   10    |  OBD_PIN_8      |  Directly connected to OBD pin      | Bi-directional | |
|   11    |  OBD_PIN_9      |  Directly connected to OBD pin      | Bi-directional | |
|   12    |  OBD_PIN_12      |  Directly connected to OBD pin      | Bi-directional | |
|   13   |   OBD_PIN_13     |  Directly connected to OBD pin      | Bi-directional | |
|   14    |  GND      |  Ground      | PWR | |
|   15    |  12V_CAR / OBD_PIN_16      |  Connection to 12V supply from the car on OBD pin 16      | PWR | |
|   16    |  RP2040_GPIO27      | Connection to RP2040 SPM on GPIO27      | Output | 3.3V Level - [See RPI2040 datasheet  for details](https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf) |
|   17    |  5V_EXT      |   Controlable 5V supply    | PWR | Maximum current rating 500mA |
|   18    |  3V3_EXT      |   Controlable 3.3V supply     | PWR | Maximum current rating 500mA |
|   19    |  DOIP_ACT      |  Connection to RP2040 SPM on DoIP activate pin      | Output | |
|   20    |  RPI_GPIO23      |  Raspberry Pi CM4 GPIO23      | Bi-directional | 3.3V Level - [See CM4 datasheet  for details](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf) |
|   21    |  RPI_GPIO24      |  Raspberry Pi CM4 GPIO24      | Bi-directional | 3.3V Level - [See CM4 datasheet  for details](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf) |
|   22    |  RPI_GPIO27      |  Raspberry Pi CM4 GPIO27      | Bi-directional | 3.3V Level - [See CM4 datasheet  for details](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf) |
|   23    |  GND      |    Ground    | PWR | |
|   24    |  GND      |  Ground      | PWR | |
|   25    |  5V      |  5V Supply     | PWR | Maximum current rating 500mA |
|   26    |  3V3      |  3.3V Supply      | PWR | Maximum current rating 500mA |
|   27    |  ETH_TD0-      |  Ethernet Data pin TD0-      | Bi-directional | |
|   28    |  ETH_TD0+      |  Ethernet Data pin TD0+      | Bi-directional | |
|   29    |  ETH_TD1-      |  Ethernet Data pin TD1-      | Bi-directional | |
|   30    |  ETH_TD1+      |  Ethernet Data pin TD1+      | Bi-directional | |
|   31    |  RPI_PWR      |   CM4 power status pin     | Output | 3.3V Level - [See CM4 datasheet  for details](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf) |
|   32    |  RP2040_GPIO17      |  Connection to RP2040 SPM on GPIO17      | Input | When high the CM4 will wake - 3.3V Level - [See RPI2040 datasheet  for details](https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf) |
|   33    |  RP2040_GPIO28      |  Connection to RP2040 SPM on GPIO28      | Output |3.3V Level - [See RPI2040 datasheet  for details](https://datasheets.raspberrypi.com/rp2040/rp2040-datasheet.pdf) |
|   34    |  USB_DP_EXT      |  USB4 D+ Data line - HAT USB      | Bi-directional | |
|   35    |  USB_DM_EXT      |  USB4 D- Data line - HAT USB        | Bi-directional | |
|   36    |  RPI_GPIO22      |  Raspberry Pi CM4 GPIO22       | Bi-directional | 3.3V Level - [See CM4 datasheet  for details](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf) |
|   37    |  RPI_ID_SD      |  Raspberry Pi CM4 ID_SD       | Bi-directional | 3.3V Level - [See CM4 datasheet  for details](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf) |
|   38    |  RPI_ID_SC      |  Raspberry Pi CM4 ID_SC       | Bi-directional | 3.3V Level - [See CM4 datasheet  for details](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf) |
|   39    |  I2C1_SDA      |  I2C1 Data line      | Bi-directional | 3.3V Level - [See CM4 datasheet  for details](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf) |
|   40    |  I2C1_SCL      |  I2C1 Clock line      | Bi-directional | 3.3V Level - [See CM4 datasheet  for details](https://datasheets.raspberrypi.com/cm4/cm4-datasheet.pdf) |

## Example Dimensions

The following picture shows an example layout of the HAT, together with positioning of the female connector. This specific HAT is designed to go around the CM4 board:

![HAT Example](/img/hardware/autopi_tmu_cm4/using_hat/HAT_dimensions.jpg)

---

## Connection Overview

## Connectivity

### Front Side

This diagram shows the 3.5 CAN-FD generation frontside connections possibilities

1. Sim card slot    
2. USER EXT 1
3. ETH CONN
4. GPIO pins for RPi and external connections
5. GPIO Jumper to always force 5V on the RPi
6. JST connector for external speaker
7. OBD-II connector to the vehicle
8. RTC battery connector
9. Micro USB connectors for external use

![connection overview front](/img/hardware/autopi_tmu_socketcan/connection_overview/side1.png)

### Back Side

This diagram shows the 3.5 CAN-FD generation backside connections possibilities

1. AP EXT 2 - BLE module connector
2. Upstream USB connector to RPi
3. AP EXT 1 - OBD2 pass through connector
4. Modem slot

![connection overview back](/img/hardware/autopi_tmu_socketcan/connection_overview/side2.png)

## Pinout

### GPIO Pins

This image is an overview of the GPIO pinout of the 3.5 CAN-FD generation [AutoPi](https://www.autopi.io).

Pins marked with "in use" cannot be used for anything else. This will interrupt the functionality
of the [AutoPi](https://www.autopi.io). This I2C bus is used by the [AutoPi](https://www.autopi.io), but can be shared with other devices. 

All other pins are free and their functionality follows that of the Raspberry Pi.

![GPIO pinout](/img/hardware/autopi_tmu_socketcan/connection_overview/gpio_pinout_gen3.5.png) 

### [AutoPi](https://www.autopi.io) Extension Port 1

![AP EXT 1 connector pinout](/img/hardware/autopi_tmu_socketcan/connection_overview/AP_EXT1.png)

### [AutoPi](https://www.autopi.io) Extension Port 2

![AP EXT 2 connector pinout](/img/hardware/autopi_tmu_socketcan/connection_overview/AP_EXT2.png)

### User Extension Port 1

![USER EXT 1 connector pinout](/img/hardware/autopi_tmu_socketcan/connection_overview/USER_EXT1.png)

The power to the extension ports can be controlled using the following commands:

`spm.query ext_pins [high|low|toggle]=ext_sw_3v3`

`spm.query ext_pins [high|low|toggle]=ext_sw_5v`

### Ethernet Connection Port

![ETH connector pinout](/img/hardware/autopi_tmu_socketcan/connection_overview/ETH_CONN.png)

---

## Device Dimensions(Autopi_tmu_socketcan)

![Device dimensions](/img/hardware/autopi_tmu_socketcan/device_dimensions/device_dimensions_4.png)

![Device dimensions](/img/hardware/autopi_tmu_socketcan/device_dimensions/device_dimensions_5.png)

![Device dimensions](/img/hardware/autopi_tmu_socketcan/device_dimensions/device_dimensions_6.png)

---

## Introduction(11)

This section has a few guides written out that are specifically for third generation (TMU) devices.
Some of the knowledge may be transferrable to second generation devices.

![Third generation AutoPi device](/img/hardware/autopi_tmu_socketcan/device.png)

## Jumper

This is a picture of the location of the 5V FORCE pins. You can put a jumper on these pins to
prevent the [AutoPi](https://www.autopi.io) from going to hibernation. More info [here](/developer_guides/jumpers.md).

![Third generation AutoPi Jumper location](/img/hardware/autopi_tmu_socketcan/jumper.jpg)

---

## Install External Antennas

:::caution Before proceeding with the upgrade
Please read the **whole guide** in order to have a good understanding of how all the components fit together.

You need to be careful not to tear or damange some of the cables when handling the casing of the device.
:::

:::success
**Prerequesites** for this guide:
- A rear shield with support for 3x SMA connectors
- 3x SMA Spacers
- 3x SMA Lock Rings
- 3x Nuts
- 2x external 4G/LTE antennas
- 1x external GPS antenna

We recommend using [**this**](https://shop.autopi.io/products/3in1-external-antenna-kit) antenna kit for expanding your [AutoPi](https://www.autopi.io).
:::

### Step-by-Step Guide

	
		Step 1: 
		Get the rear shield, spacers, lock rings, nuts and external antennas and position them like so.
	
	

	
		Step 2: 
		Insert the antennas in each hole.
	
	

	
	
		Step 3: 
		After inerting the antennas, you will need to screw in the spacers, rings and nuts that will fix the antennas
		in position.
	
	
		First, attach the spacers with the teeth facing inwards. 
	

	

	
		Step 4: 
		Then, attach the lock rings and finally, screw in the spacers. Make sure that the screws are well screwed in and
		that no space is left between the lock ring and the nut (Please note that the order of the components is crucial
		in the last three steps).
	
	

	
		Step 5: 
		Now, take your [AutoPi](https://www.autopi.io) and flip it so you can face the bottom of the device. Next, unscrew the bottom cover of
		the device and get out the shield that was previously installed.
	
	

	
		Step 6: 
		Unscrew the bottom cover of the device and get out the shield that was previously installed.
	
	

	
		Step 7: 
		Grab the rear shield that you have assembled with the installed antennas. Note that the cables of the antennas
		need to be facing the internals of the [AutoPi](https://www.autopi.io) device.
	
	

	
		
			Step 8: 
			Mount the shield inside the small cutout that runs along the rear of the device. Next, plug in each of the
			antennas in their respective socket. "The left antenna with the left socket, the middle antenna with the
			middle socket (the gps socket), and the right antenna with the right socket".
		
		
			To manage the excess antenna cable, you can form a loop around the cable itself.
		
		
			Note: 
			Please make sure that the antennas are clumped together so they don't accidentally get stuck in between the
			casings or that they are accidentally screwed in when you put back the screws in the casing. Once installed,
			also make sure that you don't screw in the antennas anymore because they will twist and be damanged in the
			interior of the device.
		
	
	

	
		Step 9: 
		Screw back in the four metal screws that you took out in the beginning. You don’t have to worry about where to
		put them as they all have the same dimensions.
	
	

	
		Step 10: 
		You can now screw in the 4G antennas and the External GPS antenna like in the following image.
	
	

### Disscussion

	You have now successfully installed an external antenna kit onto your Gen3.5 CAN-FD [AutoPi](https://www.autopi.io) device.

:::note
In case you have any questions, don't hesitate to contact us at [support@autopi.io](mailto:support@autopi.io).
:::

---

## Mounting Holes(Autopi_tmu_socketcan)

![Mounting holes](/img/hardware/autopi_tmu_socketcan/mounting_holes/mounting_holes.png)

---

## OBD Connector Pinout(Autopi_tmu_socketcan)

This is an image of the OBD connector pinout. It is valid for the [AutoPi](https://www.autopi.io) TMU SocketCAN versions of the [AutoPi](https://www.autopi.io).

![OBD connector pinout](/img/hardware/autopi_tmu_socketcan/obd_connector_pinout/obd_pinout_CAN-FD_ed-GND_chassis01.png)

---

## HW Introduction

This section explores the hardware components of the [AutoPi](https://www.autopi.io) and how they differ from one generation
to another.

## [AutoPi](https://www.autopi.io) Hardware
The [AutoPi](https://www.autopi.io) device is built with two major components - an [AutoPi](https://www.autopi.io) board and a Raspberry Pi. The 
[AutoPi](https://www.autopi.io) board has the OBD-II connector, used to plug the [AutoPi](https://www.autopi.io) device into your vehicle, but also
has many other components (chips) that work together to provide the full [AutoPi](https://www.autopi.io) experience.

  

The [AutoPi](https://www.autopi.io) board is then connected to the Raspberry Pi's GPIO pins and an extra USB connector to
build the full [AutoPi](https://www.autopi.io) device. There are two generations of [AutoPi](https://www.autopi.io) devices - Generation 2, which uses
a Raspberry Pi Zero W and a Generation 3 (also called TMU), which uses a Raspberry Pi 3A+. It is
also possible to use Pi 3B+ or Pi 4 with the TMU device.

Our latest generaetion devices is the [AutoPi](https://www.autopi.io) [TMU CM4](https://www.autopi.io/hardware/autopi-tmu-cm4), which is built on the Compute Module 4 from Raspberry Pi. This version is more industrialized. 

## Get Your Device Today and Get Started!

  

[![](/img/hardware/autopi_mini/AutoPi_Mini_5_Top_right.png) **AutoPi Mini** Build for fleet volume scaling and ease of install. CAN bus ready with support for legacy protocols. Support wide range of OEM Parameters. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-mini)

[![](/img/hardware/autopi_tmu_cm4/TMU_Floating_Topside_V1_scaled.png) **AutoPi TMU CM4** Based on Raspberry Pi Compute Module 4. Best for custom solutions requiring large computation power and expansion options. Comes with connectivity built-in. See price.](https://shop.autopi.io/products/autopi-telematics-unit-cm4-4g-lte-edition)

[![](/img/hardware/autopi_canfd_pro/canfd_pro_trans.png) **AutoPi CAN-FD Pro** Based on Raspberry Pi Compute Module 4. Our most powerful device to date, designed for full speed automotive datalogging of dual CAN-FD channels. See price.](https://shop.autopi.io/products/autopi-can-fd-pro)

[![](/img/shared/autopi_devices_trans.png) **Comparison of all AutoPi devices** Compare our devices and find the best fit for your requirements.](https://www.autopi.io/hardware/compare/)

## Tips for Best Device Performance

When installing the device in the car, there is a few tips on how to get the best performance of your device.

	
		Hint 1: Try to avoid installing the device in direct sun. Direct sun will heat up the device and in the summertime this can cause the CPU to throttle down, if the temperature gets too hot. 
	
	

	
		Hint 2: The device contains a GPS antenna inside. Make sure that there is no metal covering the device as this can affect the performance of the device. 
	
	

	
		Hint 3: The GPS antenna is located close the the logo on the device. To ensure the best performance of your device, make sure the logo side of the device is facing the sky.
	
	

	
		Hint 4: When powering the device, make sure you only power it through the OBD connector. The device can not be powered through any of the other ports.

---

## Connection Overview(Autopi_dongle)

This is a diagram shows the connection possibilities of the second generation [AutoPi](https://www.autopi.io).

1. Upstream USB connector to RPi
2. GPIO Jumper to always force 5V on the RPi (disables sleep timers from hardware)
3. OBD-II connector to vehicle
4. JST connector for external speaker
5. GPIO pins for RPi and external connections
6. SIM card slot
7. USB connectors for external use

![connection overview](/img/hardware/legacy_devices/autopi_dongle/connection_overview/connection_overview.jpeg)

---

## Introduction(Legacy_devices)

In this section, we will explore specifics about the generation 2 devices. On this page, you will
find general information like the GPIO pinout and where to put the jumper if you need it.

![Second generation AutoPi device](/img/hardware/legacy_devices/autopi_dongle/device.png)

## Pinout

This image is an overview of the GPIO pinout of the 2<sup>nd</sup> generation [AutoPi](https://www.autopi.io).

Pins marked with "in use" cannot be used for anything else. This will interrupt the functionality
of the [AutoPi](https://www.autopi.io). This I2C bus is used by the [AutoPi](https://www.autopi.io), but can be shared with other devices. 

All other pins are free and their functionality follows that of the Raspberry Pi.

![Second generation AutoPi GPIO Pinout](/img/hardware/legacy_devices/autopi_dongle/gpio_pinout.jpg)

## Jumper

This is a picture of the location of the 5V FORCE pins. You can put a jumper on these pins to
prevent the [AutoPi](https://www.autopi.io) from going to hibernation. More info [here](/developer_guides/jumpers.md).

![Second generation AutoPi Jumper location](/img/hardware/legacy_devices/autopi_dongle/jumper.jpg)

---

## OBD Connector Pinout(Autopi_dongle)

This is an image of the OBD connector pinout. It is valid for all generations of the [AutoPi](https://www.autopi.io).

![OBD connector pinout](/img/hardware/legacy_devices/autopi_dongle/obd_connector_pinout/obd_connector_pinout.png)

:::note
In case you have any questions, don't hesitate to contact us at [support@autopi.io](mailto:support@autopi.io).
:::

---

## Setup Your Gen 2 DiY Edition

Congratulations on your [AutoPi](https://www.autopi.io) Device, DiY Edition! We're sure that you have some great plans on how to use
the device to your liking, but of course, first, you need to set it up. This is a guide that shows the
steps that need to be taken to get the device in running condition.

:::note
This guide is for Gen 2 DiY boards. For Gen 3 (TMU) DiY boards, take a look at
[this](/hardware/legacy_devices/autopi_dongle_gen3/setup_your_tmu_diy_edition.md) guide.
:::

## Connecting the Raspberry Pi
Here is a small guide on connecting a RPi Zero to you [AutoPi](https://www.autopi.io).

1. Get your Raspberry Pi Zero and the 40-pin header that came with your [AutoPi](https://www.autopi.io):
![rpi_zero_pinless](/img/hardware/legacy_devices/autopi_dongle/setup_your_gen_2_diy_edition/rpi_zero_pinless.jpeg) 

2. Solder the pin header to the Raspberry Pi:
![rpi_zero_pins_attached](/img/hardware/legacy_devices/autopi_dongle/setup_your_gen_2_diy_edition/rpi_zero_pins_attached.jpeg) 

3. Connect the flat micro-USB cable that came with your [AutoPi](https://www.autopi.io). One end needs to be connected to the
vertical USB connector on the [AutoPi](https://www.autopi.io) board and the other end needs to be connected to the USB out on
the Raspberry Pi: 
![connect_diy_board_usb](/img/hardware/legacy_devices/autopi_dongle/setup_your_gen_2_diy_edition/connect_diy_board_usb.jpeg) 

4. Mount the Raspberry Pi on the [AutoPi](https://www.autopi.io). Use the screws that came with your [AutoPi](https://www.autopi.io), to fasten the
Raspberry Pi: 
![fasten_rpi_with_diy_board](/img/hardware/legacy_devices/autopi_dongle/setup_your_gen_2_diy_edition/fasten_rpi_with_diy_board.jpeg) 

## Connecting to the [Cloud](https://www.autopi.io/software-platform/cloud-management)
Should you want to use the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management), then you can use this image found here to setup your device:

https://github.com/autopi-io/autopi-core/releases

The image has been optimized for Raspberry Pi Zero.

:::tip
Etcher can write the compressed image directly to the SD card. We recommend using a Class 10
SD card with minimum 8Gb storage.
:::

### Logging in to the Device

The device is initially configured to use the following credentials:

*WiFi*  
SSID: AutoPi-Initial  
Password: autopi2018  

*SSH*  
User: pi  
Password: autopi2018  

**You should consider changing these to something else once you get up and running.**

### Getting Access to the [Cloud](https://www.autopi.io/software-platform/cloud-management)
To get your device on the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) you need to get an ID for your device, see the below steps.

1. Ensure that the `/etc/salt/minion` config file has the master specified. Look for the line:

    ```
    master: hub01.autopi.io
    ```

2. Remember to configure the APN settings.
3. Write to support with your unit_id (Find by logging into the local hotspot, or see file
`/etc/salt/minion_id`) and ask (support@autopi.io) for it to be approved in the system (the dongle
needs to be online at least once before this can be done).

:::caution
The [AutoPi](https://www.autopi.io) *always* needs to be powered through the OBD connector to function properly.
Powering the board through the micro-USB (or USB-C for RPi 4) power plug on the Raspberry Pi could damage your
board. If you need to test the [AutoPi](https://www.autopi.io) in a lab environment, we encourage you to get the
[OBD power connector](https://shop.autopi.io/en/products/obd-ii-power-cable-10/) from our shop.
:::

## Get 4G and GPS Connectivity
If you are looking to use a 4G SIM card or for GPS tracking to be enabled on your device, you will
have to purchase your own modem, as one isn't included in the DiY Edition of the [AutoPi](https://www.autopi.io). The modem
that we assemble the rest of our devices with is the Quectel EG25-G mini PCIe modem. This is the
modem that we also test all of our devices with and as such is the one, we recommend. However, since
the modem is based on the Qualcomm chipset, other modems that are also based on the Qualcomm chipset
should work as well.

Once you've purchased your modem, you will need to install it in the modem slot on the back of the
AutoPi board. Once you've done that, you will need to set one of the system settings to enable the
`ec2x` manager. You can do that by going over to the Device > Advanced Settings > System page and looking
for the Setup > Mpcie > Module setting. There you can select the `ec2x` option which will install
the driver for the modem.

---

## Update Firmware of EG25-G Module

:::caution
This firmware update applies to 2nd Generation 4G/LTE dongles, shipped out before September 1st,
2019 (i.e. **ONLY the EG25 modem**). All devices shipped after this date have their firmware
upgraded.
:::

This guide shows how to install the firmware revision *EG25GGBR07A07M2G_01.002.01.002* onto the
EG25-G module. This firmware update fixes the GNSS auto-start issue (505 - Session not active). To
check if your device is affected, please look in your minion logs for this line:

```bash
Unable to determine GNSS location: {'reason': '505', 'type': 'CME'}
```

This firmware update only applies to the 2nd generation 4G/LTE [AutoPi](https://www.autopi.io) dongles with the EG25-G
module installed. If you are unsure which generation your 4G/LTE [AutoPi](https://www.autopi.io) dongle is then please
contact [support@autopi.io](http://mailto:support@autopi.io) and provide your device ID.

You can always check your current firmware version by running the following command in the [Cloud](https://www.autopi.io/software-platform/cloud-management)
terminal:

```bash
ec2x.query "at+qgmr"
```

If you see the revision number below you already have this firmware update installed:

```
EG25GGBR07A07M2G_01.002.01.002
```

## Installation Steps

1. Power on the [AutoPi](https://www.autopi.io) Dongle by inserting it into the OBD-II connector of the vehicle. It is
  highly recommended to have the engine running to prevent any sleep timers from powering the
  device off.

2. [Connect via SSH](/developer_guides/how_to_ssh_to_your_device.md).

3. Download the firmware package on the device by running the shell command below (please note that
  the package size is 90MB):

  ``` bash
  sudo wget -P /opt/ https://www.autopi.io/media/share/EG25GGBR07A07M2G_01.zip
  ```

4. Unpack the zip file:
  ```bash
  sudo unzip /opt/EG25GGBR07A07M2G_01.zip -d /opt/
  ```

5. Run the installation script:
  ```bash
  sudo /opt/EG25GGBR07A07M2G_01/install.sh /opt/EG25GGBR07A07M2G_01/
  ```

6. Allow system to reboot automatically when announced. During the update the system will speak and
  notify what is happening. 

7. After installation of the firmware and a final reboot, the revision can be checked by running
  the shell command:
  ```bash
  autopi ec2x.query "at+qgmr"
  ```

---

## Using GPIO and HDMI

This is a step-by-step guide on how to access the HDMI on your dongle. 

This guide does require that you have a little bit of DIY abilities/skills, but you can still manage it even if you are not DIY savvy. 

1. First, you need to make sure you have the following; your dongle separated, a knife, and a lighter.

![tools_needed.jpg](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/tools_needed.jpg)

2. The first step is you need a sharp knife, we recommend a hobby/pocket knife; then use the lighter. 

3. Place the knife above the flame and slowly heat up the knife, so it can cut through the device easier. 

4. Once you have the dongle separated, inside the top casing, you’ll be able to see the subtle markings of where to cut.

![subtle_markings_of_hdmi_cutout](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/subtle_markings_of_hdmi_cutout.jpg)

5. On the broad side of the top casing, there is this subtle square indent, and here is where you should cut if you want to access the mini HDMI port.  

![hdmi_cutting_the_casing_1](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/hdmi_cutting_the_casing_1.jpg)
![hdmi_cutting_the_casing_2](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/hdmi_cutting_the_casing_2.jpg)
![hdmi_cutting_the_casing_3](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/hdmi_cutting_the_casing_3.jpg)

6. For the GPIO pins, there is a rectangular cutout marking on the top casing. This is where you should cut if you want to use it for the GPIO pins. 
![subtle_markings_of_gpio_cutout](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/subtle_markings_of_gpio_cutout.jpg)
![gpio_cutting_the_casing_1](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/gpio_cutting_the_casing_1.jpg)
![gpio_cutting_the_casing_2](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/gpio_cutting_the_casing_2.jpg)

7. Remember to be methodical, careful and slow when cutting in order not to hurt yourself or do damage to the device. 

8. Congratulations, you can now access both the GPIO pins, and the mini HDMI port.

![final_result_1](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/final_result_1.jpg)
![final_result_2](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/final_result_2.jpg)
![final_result_3](/img//hardware/legacy_devices/autopi_dongle/using_gpio_and_hdmi_with_the_gen_2/final_result_3.jpg)

---

## Using the RPi3 Adapter

**Please note:** The [AutoPi](https://www.autopi.io) always needs power through the OBD connector, to function properly. Powering the board through the micro usb power plug on the Raspberry Pi could damage your board. If you need to test the [AutoPi](https://www.autopi.io) in a lab environment, we encourage you to get the [OBD power connector](https://shop.autopi.io/en/products/obd-ii-power-cable-10/) from the shop.

This is a step-by-step instructions on how to set-up your Raspberry Pi3 adapter. You will need the following tools to get started:

- Your RPi3 adapter (with screws, spacers and nuts)
- Screwdriver
- Your Raspberry Pi 3 (isn't included in the kit)
- Your [AutoPi](https://www.autopi.io) dongle

Here is what you need to do:

1. Remove the casing from your [AutoPi](https://www.autopi.io) (if you have a 4G or WiFi edition)

2. Remove the Raspberry Pi Zero from the [AutoPi](https://www.autopi.io) dongle, leaving only the black [AutoPi](https://www.autopi.io) base board.

3. Your RPi3 adapter comes with screws that you’ll have to insert (from the bottom side, upwards) in four corners of your RPi3, once you do that, you can put the spacers down unto your screws. Be gentle with the screws since they are made of plastic. The following image illustrates how it should look:

![bottom_of_rpi3_with_screws](/img/hardware/legacy_devices/autopi_dongle/using_the_rpi3_adapter/bottom_of_rpi3_with_screws.jpg)

It is important that you insert your screws first, from the bottom so the spacers can be put on:

![spacers_showcased](/img/hardware/legacy_devices/autopi_dongle/using_the_rpi3_adapter/spacers_showcased.jpg)

4. Hereafter, insert 4 screws downward the four inner holes on your RPi3 adapter, and screw them closed with 4 nuts. 

![adapter_board_bottom_view](/img/hardware/legacy_devices/autopi_dongle/using_the_rpi3_adapter/adapter_board_bottom_view.jpg)

Make sure the screws are faced downwards in the four inner holes. 

![adapter_board_top_view](/img/hardware/legacy_devices/autopi_dongle/using_the_rpi3_adapter/adapter_board_top_view.jpg)

Put on the nuts and tighten the screws in place by rotating them clockwise.

5. Then, push down your RPi3 adapter unto the RPi3 (where the left side black box will fit the headerpins on the RPi3).

![adapter_board_and_rpi3_connected](/img/hardware/legacy_devices/autopi_dongle/using_the_rpi3_adapter/adapter_board_and_rpi3_connected.jpg)

This is what it should like once you have safely pushed the adapter down on the RPi3

6. After you have securely and safely attached the adapter to the RPi3, use 4 nuts to tighten the screws in place. 

7. Hereafter, align your dongle correctly so the headpins of the adapter fits with the black box of the dongle and push them gently, but firmly unto each other. 

8. Lastly, all you need to do is insert three screws in the three inner holes of the dongle, and be careful and gentle, too much pressure and screwing them too tightly can break the screw tops off. Once, you’ve done that you are; 

9. This step only applies if you have a 4G edition and you want to use the modem. To enable the modem you need to connect the [AutoPi](https://www.autopi.io) to the RPi3 using the flat Micro USB cable that came with your [AutoPi](https://www.autopi.io). Insert the USB cable into the micro USB to USB adapter that came with your Raspberry Pi 3 Adapter. Then insert it into the RPi3. You can see how in this image (red circles):

![usb_connection_rpi3](/img/hardware/legacy_devices/autopi_dongle/using_the_rpi3_adapter/usb_connection_rpi3.jpg)

If you have another micro USB to USB cable, you can also use that. Anyone will work. 

10. To get your [AutoPi](https://www.autopi.io) (RPi3 edition) online in the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management), it needs to be registred again. The reason for this is that your Dongle ID is generated from the Raspberry Pi. So now that you've upgradet you [AutoPi](https://www.autopi.io) to the RPi3, it's received a new ID. You can get this ID from the local terminal with this command:
```
grains.get id
```
or from the SSH promt:
```
cat /etc/salt/minion_id
```
or from the web terminal
```
cmd.run 'cat /etc/salt/minion_id'
```

This ID needs to be accepted by [AutoPi](https://www.autopi.io). So you need to send the correct ID to support@autopi.io, so that it can be accepted by our servers. 

11. Finished and completely done :)

The final result should look something similar to this. 

![final_result_1](/img/hardware/legacy_devices/autopi_dongle/using_the_rpi3_adapter/final_result_1.jpg)

![final_result_2](/img/hardware/legacy_devices/autopi_dongle/using_the_rpi3_adapter/final_result_2.jpg)

![final_result_3](/img/hardware/legacy_devices/autopi_dongle/using_the_rpi3_adapter/final_result_3.jpg)

---

## Connection Overview(Autopi_dongle_gen3)

## Connectivity

### Front Side

This diagram shows the 3<sup>rd</sup> generation frontside connections possibilities

1. USER EXT 1
2. USER EXT 2
3. GPIO pins for RPi and external connections
4. GPIO Jumper to always force 5V on the RPi
5. JST connector for external speaker
6. OBD-II connector to the vehicle
7. RTC battery connector
8. Micro USB connectors for external use
9. SD card slot

![connection overview front](/img/hardware/legacy_devices/autopi_dongle_gen3/connection_overview/side1.png)

### Back Side

This diagram shows the 3<sup>rd</sup> generation backside connections possibilities

1. AP EXT2 - BLE module connector
2. Upstream USB connector to RPi
3. AP EXT1 - OBD2 pass-through connector
4. Modem slot

![connection overview back](/img/hardware/legacy_devices/autopi_dongle_gen3/connection_overview/side2.png)

## Pinouts

### GPIO Pins

This image is an overview of the GPIO pinout of the 3<sup>rd</sup> generation (TMU) [AutoPi](https://www.autopi.io).

Pins marked with "in use" cannot be used for anything else. This will interrupt the functionality
of the [AutoPi](https://www.autopi.io). This I2C bus is used by the [AutoPi](https://www.autopi.io), but can be shared with other devices. 

All other pins are free and their functionality follows that of the Raspberry Pi.

![Third generation AutoPi GPIO Pinout](/img/hardware/legacy_devices/autopi_dongle_gen3/connection_overview/gpio_pinout_gen3.png)

### [AutoPi](https://www.autopi.io) Extension Port 1

![AP EXT 1 connector pinout](/img/hardware/legacy_devices/autopi_dongle_gen3/connection_overview/AP_EXT1.png)

### [AutoPi](https://www.autopi.io) Extension Port 2

![AP EXT 2 connector pinout](/img/hardware/legacy_devices/autopi_dongle_gen3/connection_overview/AP_EXT2.png)

### User Extension Port 1

![USER EXT 1 connector pinout](/img/hardware/legacy_devices/autopi_dongle_gen3/connection_overview/USER_EXT1.png)

### User Extension Port 2

![USER EXT 2 connector pinout](/img/hardware/legacy_devices/autopi_dongle_gen3/connection_overview/USER_EXT2.png)

---

## Developer Kit

In this guide we will explore how you can get started with your [AutoPi](https://www.autopi.io) Developer Kit. We will talk
about how to get the device some power, what you're able to connect to it and how to get the
antennas attached.

## Power

Let's start off by getting the power sorted out. Included in your developer kit, you have a power
cable, one side of that power cable is a female OBD-II port and the other is a female DC connector.
This is the cable we're going to use to provide power to it. On one side, plug the [AutoPi](https://www.autopi.io) device
(OBD side) and on the other - your DC power supply.

:::tip
You can connect the OBD side of the power cable to your device and use the DC connector to easily
switch on and off the power provided to the device. It is easier than plugging and unplugging the
OBD-II port.
:::

:::danger
NEVER connect a micro-USB power cable to the Raspberry Pi's power input port. The intended way for
the [AutoPi](https://www.autopi.io) to receive power is through the OBD-II port. Connecting a micro-USB power cable to the
Raspberry Pi will likely result in a short-cirtuit.
:::

## Connectivity

The [AutoPi](https://www.autopi.io) has three IO ports:

1. **Micro-USB cable**, which you can use to connect any usb device to your [AutoPi](https://www.autopi.io).
2. **HDMI**, which you can use to connect a monitor to your [AutoPi](https://www.autopi.io).
3. **Audio jack**, which you can use for headphones or speakers.

![available I/O](/img/hardware/legacy_devices/autopi_dongle_gen3/developer_kit/available-io.jpg)

## Antennas

The developer kit also has included three antennas. Two of the antennas look the same, they are the
antennas for 4G/LTE connectivity. The third, longer one, is the GPS antenna. Usually, we recommend
to place the GPS antenna as close to a window as possible.

The GPS antenna port is located in the middle, between two 4G/LTE antenna ports. Here is an image
that shows those ports.

![antenna port locations](/img/hardware/legacy_devices/autopi_dongle_gen3/developer_kit/antennas-pre-setup.jpg)

In the middle port, connect the GPS antenna. On the two ports on the side, connect the 4G/LTE
antennas. After you're done, your device should look a bit like the following:

![complete dev kit](/img/hardware/legacy_devices/autopi_dongle_gen3/developer_kit/finished-dev-kit.jpg)

:::note
In case you have any questions, don't hesitate to contact us at [support@autopi.io](mailto:support@autopi.io).
:::

---

## Introduction(12)

This section has a few guides written out that are specifically for third generation (TMU) devices.
Some of the knowledge may be transferrable to second generation devices.

![Third generation AutoPi device](/img/hardware/legacy_devices/autopi_dongle_gen3/device.png)

## Jumper

This is a picture of the location of the 5V FORCE pins. You can put a jumper on these pins to
prevent the [AutoPi](https://www.autopi.io) from going to hibernation. More info [here](/developer_guides/jumpers.md).

![Third generation AutoPi Jumper location](/img/hardware/legacy_devices/autopi_dongle_gen3/jumper.jpg)

---

## Installing External Antennas

This is a step-by-step guide on how to install external 4G and GPS antennas on your [AutoPi](https://www.autopi.io).

This guide will require a medium level of DIY abilities/skills, and it will involve drilling into
the plastic casing of the [AutoPi](https://www.autopi.io) TMU.

**Step 1:** First, you will have to make sure that you have access to the following:

* The External Antenna Kit (you can purchase one [here](https://shop.autopi.io/products/3in1-external-antenna-kit))
* [AutoPi](https://www.autopi.io) TMU 3rd Gen
* A drill

**Step 2:** Disassemble the device by opening the four screws located on the backside.

![Unscrewed device](/img/hardware/legacy_devices/autopi_dongle_gen3/installing_external_antennas/unscrewed_device.jpeg)

**Step 3:** Turn the device around and lift the **top part** while being careful not to damage the
antenna cable.

![Lift top part of AutoPi casing](/img/hardware/legacy_devices/autopi_dongle_gen3/installing_external_antennas/lift_top_part_of_autopi_casing.jpeg)

**Step 4:** Remove the black antenna cable by pulling straight up, while being careful not to
damage the modem.

![Remove antenna cable](/img/hardware/legacy_devices/autopi_dongle_gen3/installing_external_antennas/remove_antenna_cable.jpeg)

**Step 5:** Hold the OBD connector and lift the device slowly out of the enclosure.

:::caution
*Be careful* as the speaker and the battery are connected still to the device and the enclosure.
:::

![Lifting device out of the enclosure](/img/hardware/legacy_devices/autopi_dongle_gen3/installing_external_antennas/lifting_device_out_of_the_enclosure.jpeg)

**Step 6:** Remove the speaker and the battery connector, while keeping in mind the location of the
connectors.

**Step 7:** Now that you have separated the enclosure from the device, you will see that there are
dots located around the casing. These dots show placement location for possible antennas.

Please note there are **5** possible locations on the side opposite to the OBD port, and 1 on each
side of the device.

![Drill locations](/img/hardware/legacy_devices/autopi_dongle_gen3/installing_external_antennas/drill_locations.jpeg)

**Step 8:** To drill, use a **6.5 mm** drill bit, and drill directly on top of the dots.

**Step 9:** After drilling, insert the SMA cables through the holes you have created.

![SMA cable inserted](/img/hardware/legacy_devices/autopi_dongle_gen3/installing_external_antennas/sma_cable_inserted.jpeg)

**Step 10:** Next, we are starting the reassembly process. First the battery and speaker will be
connected, then the device will be slowly put in the enclosure, while being very careful not to
pinch any wires.

**Step 11:** The next step is to reconnect the SMA cable to the modem by positioning them above the
connector and pushing down gently until a click is heard. Please keep in mind that the GPS SMA
cable will be in the middle of the three connectors. In the picture below, the GPS antenna is the
GRAY SMA cable.

![SMA cable connected](/img/hardware/legacy_devices/autopi_dongle_gen3/installing_external_antennas/sma_cable_connected.jpeg)

**Step 12:** The top lid of the enclosure will be mounted using the 4 black screws.

![Antenna ready device](/img/hardware/legacy_devices/autopi_dongle_gen3/installing_external_antennas/antenna_ready_device.jpeg)

**Step 13:** Next, the antennas will be connected to the SMA cables, while keeping in mind not to
mix the GPS antenna with the 4G antenna.

![Antennas connected to device](/img/hardware/legacy_devices/autopi_dongle_gen3/installing_external_antennas/antennas_connected_to_device.jpeg)

:::note
In case you have any questions, don't hesitate to contact us at [support@autopi.io](mailto:support@autopi.io).
:::

---

## OBD Connector Pinout(Autopi_dongle_gen3)

This is an image of the OBD connector pinout. It is valid for all generations of the [AutoPi](https://www.autopi.io).

![OBD connector pinout](/img/hardware/legacy_devices/autopi_dongle_gen3/obd_connector_pinout/obd_connector_pinout.png)

:::note
In case you have any questions, don't hesitate to contact us at [support@autopi.io](mailto:support@autopi.io).
:::

---

## Setup your TMU DiY Edition

Congratulations on your [AutoPi](https://www.autopi.io) Device, DiY Edition! We're sure that you have some great plans on how to use
the device to your liking, but of course, first, you need to set it up. This is a guide that shows the
steps that need to be taken to get the device in running condition.

:::note
This guide is for TMU (Gen 3) DiY boards. For Gen 2 DiY boards, take a look at
[this](/hardware/legacy_devices/autopi_dongle/setup_your_gen_2_diy_edition.md) guide.
:::

## Connecting the Raspberry Pi
The steps you need to take are very simple. In this case, we are using a Raspberry Pi 3 A+,
however this can work with a Raspberry Pi 3 B+ or a Raspberry Pi 4.

![autopi_board_and_raspberry](/img/hardware/legacy_devices/autopi_dongle_gen3/setup_your_tmu_diy_edition/autopi_board_and_raspberry.jpg)

1. Mount the Raspberry Pi on the [AutoPi](https://www.autopi.io), connecting the pins of the Raspberry to the open holes in the
[AutoPi](https://www.autopi.io) board.

![autopi_board_and_raspberry_connected](/img/hardware/legacy_devices/autopi_dongle_gen3/setup_your_tmu_diy_edition/autopi_board_and_raspberry_connected.jpg)

2. Connect the USB cable that's attached to the [AutoPi](https://www.autopi.io) board to one of the open USB ports of your Raspberry Pi

![board_cable_connected_to_raspberry](/img/hardware/legacy_devices/autopi_dongle_gen3/setup_your_tmu_diy_edition/board_cable_connected_to_raspberry.jpg)

3. Lastly, place the four screws to secure the two boards fastly together.

![screw_board](/img/hardware/legacy_devices/autopi_dongle_gen3/setup_your_tmu_diy_edition/screw_board.jpg)

## Connecting to the [Cloud](https://www.autopi.io/software-platform/cloud-management)
Should you want to use the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) solution, you can use the image found in [this](https://github.com/autopi-io/autopi-core/releases) link to flash an SD card. Make sure to download the correct image for
your device - since you're reading this guide, you are most likely to be needing to download the
TMU image, instead of the GEN 2 image.

:::tip
Etcher can write the compressed image directly to the SD card. We recommend using a Class 10 SD card
with a minimum of 8GB storage.
:::

### Logging in to the Device
The device is initially configured with the following credentials:

*WiFi*  
SSID: AutoPi-Initial  
Password: autopi2018

*SSH*  
User: pi  
Password: autopi2018

**We highly recommend that you change those settings as soon as you are able to do so.**

### Getting Access to the [Cloud](https://www.autopi.io/software-platform/cloud-management)
To get your device on the [AutoPi](https://www.autopi.io) [Cloud](https://www.autopi.io/software-platform/cloud-management) you need to get the unit ID of your device. You can find out
your device's ID by reading out the `/etc/salt/minion_id` file. Once you have that ID, you should write to
our support team (support@autopi.io) asking for it to be added to the system. Make sure that the dongle has
been online at least once before doing this.

:::caution
The [AutoPi](https://www.autopi.io) *always* needs to be powered through the OBD connector to function properly.
Powering the board through the micro usb (or usb-c for RPi 4) power plug on the Raspberry Pi could damage your
board. If you need to test the [AutoPi](https://www.autopi.io) in a lab environment, we encourage you to get the
[OBD power connector](https://shop.autopi.io/en/products/obd-ii-power-cable-10/) from our shop.
:::

## Get 4G and GPS Connectivity
If you are looking to use a 4G SIM card or for GPS tracking to be enabled on your device, you will
have to purchase your own modem, as one isn't included in the DiY Edition of the [AutoPi](https://www.autopi.io). The modem
that we assemble the rest of our devices with is the Quectel EG25-G mini PCIe modem. This is the
modem that we also test all of our devices with and as such is the one, we recommend. However, since
the modem is based on the Qualcomm chipset, other modems that are also based on the Qualcomm chipset
should work as well.

Once you've purchased your modem, you will need to install it in the modem slot on the back of the
[AutoPi](https://www.autopi.io) board. Once you've done that, you will need to set one of the system settings to enable the
`ec2x` manager. You can do that by going over to the Device > Advanced Settings > System page and looking
for the Setup > Mpcie > Module setting. There you can select the `ec2x` option which will install
the driver for the modem.

---

## Connection Overview(Autopi_tmu_can_fd)

## Connectivity

### Front Side

This diagram shows the 3.5 CAN-FD generation frontside connections possibilities

1. Sim card slot    
2. USER EXT 1
3. ETH CONN
4. GPIO pins for RPi and external connections
5. GPIO Jumper to always force 5V on the RPi
6. JST connector for external speaker
7. OBD-II connector to the vehicle
8. RTC battery connector
9. Micro USB connectors for external use

![connection overview front](/img/hardware/legacy_devices/autopi_tmu_can_fd/connection_overview/side1.png)

### Back Side

This diagram shows the 3.5 CAN-FD generation backside connections possibilities

1. AP EXT 2 - BLE module connector
2. Upstream USB connector to RPi
3. AP EXT 1 - OBD2 pass through connector
4. Modem slot

![connection overview back](/img/hardware/legacy_devices/autopi_tmu_can_fd/connection_overview/side2.png)

## Pinout

### GPIO Pins

This image is an overview of the GPIO pinout of the 3.5 CAN-FD generation [AutoPi](https://www.autopi.io).

Pins marked with "in use" cannot be used for anything else. This will interrupt the functionality
of the [AutoPi](https://www.autopi.io). This I2C bus is used by the AutoPi, but can be shared with other devices. 

All other pins are free and their functionality follows that of the Raspberry Pi.

![GPIO pinout](/img/hardware/legacy_devices/autopi_tmu_can_fd/connection_overview/gpio_pinout_gen3.5.png) 

### AutoPi Extension Port 1

![AP EXT 1 connector pinout](/img/hardware/legacy_devices/autopi_tmu_can_fd/connection_overview/AP_EXT1.png)

### AutoPi Extension Port 2

![AP EXT 2 connector pinout](/img/hardware/legacy_devices/autopi_tmu_can_fd/connection_overview/AP_EXT2.png)

### User Extension Port 1

![USER EXT 1 connector pinout](/img/hardware/legacy_devices/autopi_tmu_can_fd/connection_overview/USER_EXT1.png)

The power to the extension ports can be controlled using the following commands:

`spm.query ext_pins [high|low|toggle]=ext_sw_3v3`

`spm.query ext_pins [high|low|toggle]=ext_sw_5v`

### Ethernet Connection Port

![ETH connector pinout](/img/hardware/legacy_devices/autopi_tmu_can_fd/connection_overview/ETH_CONN.png)

---

## Device Dimensions(Autopi_tmu_can_fd)

![Device dimensions](/img/hardware/legacy_devices/autopi_tmu_can_fd/device_dimensions/device_dimensions_4.png)

![Device dimensions](/img/hardware/legacy_devices/autopi_tmu_can_fd/device_dimensions/device_dimensions_5.png)

![Device dimensions](/img/hardware/legacy_devices/autopi_tmu_can_fd/device_dimensions/device_dimensions_6.png)

---

## Introduction(13)

This section has a few guides written out that are specifically for third generation (TMU) devices.
Some of the knowledge may be transferrable to second generation devices.

![Third generation AutoPi device](/img/hardware/legacy_devices/autopi_tmu_can_fd/device.png)

## Jumper

This is a picture of the location of the 5V FORCE pins. You can put a jumper on these pins to
prevent the [AutoPi](https://www.autopi.io) from going to hibernation. More info [here](/developer_guides/jumpers.md).

![Third generation AutoPi Jumper location](/img/hardware/legacy_devices/autopi_tmu_can_fd/jumper.jpg)

---

## Install External Antennas(Autopi_tmu_can_fd)

:::caution Before proceeding with the upgrade
Please read the **whole guide** in order to have a good understanding of how all the components fit together.

You need to be careful not to tear or damange some of the cables when handling the casing of the device.
:::

:::success
**Prerequesites** for this guide:
- A rear shield with support for 3x SMA connectors
- 3x SMA Spacers
- 3x SMA Lock Rings
- 3x Nuts
- 2x external 4G/LTE antennas
- 1x external GPS antenna

We recommend using [**this**](https://shop.autopi.io/products/3in1-external-antenna-kit) antenna kit for expanding your [AutoPi](https://www.autopi.io).
:::

### Step-by-Step Guide

	
		Step 1: 
		Get the rear shield, spacers, lock rings, nuts and external antennas and position them like so.
	
	

	
		Step 2: 
		Insert the antennas in each hole.
	
	

	
	
		Step 3: 
		After inerting the antennas, you will need to screw in the spacers, rings and nuts that will fix the antennas
		in position.
	
	
		First, attach the spacers with the teeth facing inwards. 
	

	

	
		Step 4: 
		Then, attach the lock rings and finally, screw in the spacers. Make sure that the screws are well screwed in and
		that no space is left between the lock ring and the nut (Please note that the order of the components is crucial
		in the last three steps).
	
	

	
		Step 5: 
		Now, take your [AutoPi](https://www.autopi.io) and flip it so you can face the bottom of the device. Next, unscrew the bottom cover of
		the device and get out the shield that was previously installed.
	
	

	
		Step 6: 
		Unscrew the bottom cover of the device and get out the shield that was previously installed.
	
	

	
		Step 7: 
		Grab the rear shield that you have assembled with the installed antennas. Note that the cables of the antennas
		need to be facing the internals of the [AutoPi](https://www.autopi.io) device.
	
	

	
		
			Step 8: 
			Mount the shield inside the small cutout that runs along the rear of the device. Next, plug in each of the
			antennas in their respective socket. "The left antenna with the left socket, the middle antenna with the
			middle socket (the gps socket), and the right antenna with the right socket".
		
		
			To manage the excess antenna cable, you can form a loop around the cable itself.
		
		
			Note: 
			Please make sure that the antennas are clumped together so they don't accidentally get stuck in between the
			casings or that they are accidentally screwed in when you put back the screws in the casing. Once installed,
			also make sure that you don't screw in the antennas anymore because they will twist and be damanged in the
			interior of the device.
		
	
	

	
		Step 9: 
		Screw back in the four metal screws that you took out in the beginning. You don’t have to worry about where to
		put them as they all have the same dimensions.
	
	

	
		Step 10: 
		You can now screw in the 4G antennas and the External GPS antenna like in the following image.
	
	

### Disscussion

	You have now successfully installed an external antenna kit onto your Gen3.5 CAN-FD [AutoPi](https://www.autopi.io) device.

:::note
In case you have any questions, don't hesitate to contact us at [support@autopi.io](mailto:support@autopi.io).
:::

---

## Mounting Holes(Autopi_tmu_can_fd)

![Mounting holes](/img/hardware/legacy_devices/autopi_tmu_can_fd/mounting_holes/mounting_holes.png)

---

## OBD Connector Pinout(Autopi_tmu_can_fd)

This is an image of the OBD connector pinout. It is valid for the [AutoPi](https://www.autopi.io) TMU CAN-FD versions of the [AutoPi](https://www.autopi.io).

![OBD connector pinout](/img/hardware/legacy_devices/autopi_tmu_can_fd/obd_connector_pinout/obd_pinout_CAN-FD_ed-GND.png)

:::note
In case you have any questions, don't hesitate to contact us at [support@autopi.io](mailto:support@autopi.io).
:::

---

## AutoPi Documentation

Welcome to the official documentation for the [AutoPi platform](https://autopi.io).

Build, deploy, and scale connected vehicle solutions with confidence. This documentation gives you everything you need to work with AutoPi hardware, AutoPi Core software running on your devices, and our cloud solution at [my.autopi.io](https://my.autopi.io).

From first-time setup to advanced production workflows, you will find guides for onboarding, fleet operations, device management, APIs, integrations, troubleshooting, and custom development.

## Get Your Device Today and Get Started!

  

## What is [AutoPi](https://www.autopi.io)?

[AutoPi](https://autopi.io) combines rugged telematics hardware with a flexible cloud platform and open software architecture. It is designed for developers, engineering teams, and fleet operations that need reliable access to vehicle data and control.

AutoPi helps you move faster from pilot to production with:

- Open architecture for custom integrations
- Secure remote access and centralized device management
- API-first automation for scalable deployments
- Hardware options for different vehicle and project needs

The platform has two core parts: AutoPi Cloud and AutoPi Core.

- [AutoPi Cloud](https://my.autopi.io) is the central control layer for your devices, data, and automations.
- **AutoPi Core** runs on the device and handles edge logic, communication, and data collection.

Together, they deliver an end-to-end workflow for connected vehicle products.

## Why Choose AutoPi?

- Faster development with open [APIs](https://api.autopi.io)
- Scalable fleet operations in one cloud platform
- Flexible hardware for multiple vehicle types
- Developer-friendly [workflows](https://docs.autopi.io/cloud/device_management/custom-code/) for custom data pipelines and integrations
- Log raw and decoded CAN/CAN-FD/J1939/OBD-II data
- Integrate through [REST API](https://docs.autopi.io/getting_started/api/) and [MQTT](https://docs.autopi.io/developer_guides/configuring-mqtt/)
- Run custom edge applications with [Docker](https://docs.autopi.io/cloud/docker-on-autopi/)
- Manage [OTA updates](https://docs.autopi.io/cloud/device_management/software-updates/) and device [templates](https://docs.autopi.io/cloud/device_management/templates/) at fleet scale

Learn more about the platform at [autopi.io](https://autopi.io) and access the cloud at [my.autopi.io](https://my.autopi.io).

## AutoPi Devices 

[![](/img/hardware/autopi_mini/AutoPi_Mini_5_Top_right.png) **AutoPi Mini** Built for fleet scaling and easy installation. CAN bus ready with support for legacy protocols. Supports a wide range of OEM parameters. Comes with built-in connectivity. View pricing.](https://shop.autopi.io/products/autopi-mini)

[![](/img/hardware/autopi_tmu_cm4/TMU_Floating_Topside_V1_scaled.png) **AutoPi TMU CM4** Based on Raspberry Pi Compute Module 4. Best for custom solutions that require higher compute performance and expansion options. Comes with built-in connectivity. View pricing.](https://shop.autopi.io/products/autopi-telematics-unit-cm4-4g-lte-edition)

[![](/img/hardware/autopi_canfd_pro/canfd_pro_trans.png) **AutoPi CAN-FD Pro** Based on Raspberry Pi Compute Module 4. Our most powerful device to date, designed for high-speed automotive data logging on dual CAN-FD channels. View pricing.](https://shop.autopi.io/products/autopi-can-fd-pro)

[![](/img/shared/autopi_devices_trans.png) **Comparison of all AutoPi devices** Compare our devices and find the best fit for your requirements.](https://www.autopi.io/hardware/compare/)

## Documentation

Explore the documentation by area. Whether you are getting started or building advanced workflows, you can quickly navigate to the section that fits your use case.

[![](/img/shared/favicon-194x194.png) **Core Documentation** Understand how the AutoPi Core works.](/core/index.md)

[![](/img/shared/laptop_autopi_3_scaled.png) **Cloud Documentation** Learn how to make the most of your AutoPi Cloud Solution.](/cloud/index.md)

[![](/img/shared/guides_trans.png) **Guides** Get inspiration from our rich set of guides.](/getting_started/autopi_tmu_cm4/index.md)

[![](/img/hardware/autopi_tmu_cm4/TMU_Floating_Topside_V1_scaled.png) **Hardware** View hardware specific documentation.](/hardware/index.md)

[![](/img/getting_started/api/api_intro/api_frontpage.jpg) **API** Explore our rich API.](https://api.autopi.io/)

## Most Used Guides

Use these quick links to jump into the guides most teams use first. We maintain a broad set of guides across devices, cloud, hardware, and developer workflows so teams can move from setup to production with clear, practical steps.

### AutoPi TMU CM4

- [TMU CM4 Getting Started](https://docs.autopi.io/getting_started/autopi_tmu_cm4/): start here for setup, key concepts, and essential workflows.
- [Create Loggers](https://docs.autopi.io/getting_started/autopi_tmu_cm4/create-loggers-cm4/): configure logging to capture the data points you need.
- [Data Troubleshooting](https://docs.autopi.io/getting_started/autopi_tmu_cm4/cm4-data-troubleshooting/): diagnose common issues with missing or unexpected data.
- [4G Internet Setup Troubleshooting](https://docs.autopi.io/getting_started/autopi_tmu_cm4/4g-internet-setup-troubleshooting/): resolve connectivity issues on cellular deployments.

### AutoPi CAN-FD Pro

- [CAN-FD Pro Getting Started](https://docs.autopi.io/getting_started/autopi_canfd_pro/): get your device online and ready for data collection.
- [CAN-FD Pro User Guide](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-user-guide/): review the most important setup and usage steps in one place.
- [Accessing Files via SFTP/SCP](https://docs.autopi.io/getting_started/autopi_canfd_pro/accessing-files-via-sftp-on-autopi/): transfer logs and files securely to and from the device.
- [Set Up AWS S3 Bucket](https://docs.autopi.io/getting_started/autopi_canfd_pro/set_up_AWS_S3_bucket/): configure cloud storage for exporting and retaining data.
- [Data Troubleshooting](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-data-troubleshooting/): diagnose common issues with missing or unexpected data.
- [4G Internet Setup Troubleshooting](https://docs.autopi.io/getting_started/autopi_canfd_pro/pro-4g-internet-setup-troubleshooting/): resolve connectivity issues on cellular deployments.

### AutoPi Mini

- [AutoPi Mini Getting Started](http://docs.autopi.io/getting_started/autopi_mini/): learn the core setup flow for AutoPi Mini devices.
- [Create Mini Logger](https://docs.autopi.io/getting_started/autopi_mini/create-mini-loggers/): build your first logger for Mini-specific use cases.
- [Data Troubleshooting](https://docs.autopi.io/getting_started/autopi_mini/mini-data-troubleshooting/): troubleshoot common data and configuration issues.

### Cloud Solution

- [Cloud Overview](https://docs.autopi.io/cloud/fleet_management/): understand the structure and capabilities of the AutoPi Cloud.
- [Devices](https://docs.autopi.io/cloud/device_management/): manage and monitor your devices from one place.
- [Loggers](https://docs.autopi.io/cloud/device_management/device-loggers/): create and manage cloud-side loggers at scale.
- [Custom Code](https://docs.autopi.io/cloud/device_management/custom-code/): add advanced cloud workflows with custom scripts.
- [Diagnostics](https://docs.autopi.io/cloud/fleet_management/fleet-diagnostics/): investigate fleet health and identify device or data issues quickly.
- [Reports](https://docs.autopi.io/cloud/fleet_management/reports/): generate operational summaries and performance insights for your fleet.

## Developers
Want to dig right into the source code? Get full access here:

[![](/img/shared/github.png) **AutoPi Core Github** Get the open-source code for the AutoPi Core.](https://github.com/autopi-io/autopi-core)

[![](/img/shared/github.png) **AutoPi Documentation Github** Participate in the documentation, it's open-source.](https://github.com/autopi-io/documentation)

### Developer Guides (Advanced)

- **Advanced diagnostics (DoIP):** Use the [DoIP hat](https://shop.autopi.io/products/doip-hat-v1-3) to expand diagnostic and maintenance capabilities. Start here: [How to set up DoIP](https://docs.autopi.io/developer_guides/setting-up-doip/)
- **Remote access:** Connect directly with [SSH to your device](https://docs.autopi.io/developer_guides/how-to-ssh-to-your-device/) or use [Tailscale](https://docs.autopi.io/getting_started/autopi_canfd_pro/how_to_connect_to_tailscale/)
- **Containerized workloads:** Run services on-device with [Setting up Docker on your device](https://docs.autopi.io/developer_guides/setting-up-docker/)
- **Development setup:** Follow the [Local development workflow](https://docs.autopi.io/developer_guides/local-development-workflow/), power safely with an [external power supply](https://docs.autopi.io/developer_guides/using-the-autopi-with-an-external-power-supply/), and use the [AutoPi Local API overview](https://docs.autopi.io/developer_guides/local-api-overview/)
- **Data routing and broker integration:** Send data to your own infrastructure with [Configuring MQTT](https://docs.autopi.io/developer_guides/configuring-mqtt/)
- **Power and wake control:** Access sleeping devices remotely with [Remotely waking up your device](https://docs.autopi.io/developer_guides/remotely-waking-up-your-device/)
- **Troubleshooting and recovery:** Collect diagnostics with [AutoPi Logs](https://docs.autopi.io/developer_guides/autopi-logs/) and recover devices with [Reflashing your device](https://docs.autopi.io/developer_guides/reflashing-your-device/)
- **Hardware extensions:** Add peripherals with [Installing a camera on your AutoPi](https://docs.autopi.io/developer_guides/installing-a-camera-on-your-autopi/) and configure BLE workflows via [How to use bluepy with AutoPi edge devices](https://docs.autopi.io/developer_guides/how-to-use-bluepy-with-autopi-edge-devices/)
- **Raw GPS data access:** Collect and inspect raw GNSS output for advanced location workflows with [Accessing Raw GPS Data](https://docs.autopi.io/developer_guides/accessing-raw-gps-data/)
- **Data visualization for Pro devices:** Visualize telemetry with custom dashboards and real-time metrics using [Build Grafana Dashboard](https://docs.autopi.io/developer_guides/build-grafana-dashboard/)
- **Custom event automation:** Define custom triggers and actions for specialized logger logic with [How to Create a Custom Event](https://docs.autopi.io/developer_guides/how-to-create-custom-event-for-custom-logger/)
- **Remote CAN workflows:** Enable remote CAN bus access for diagnostics and development tasks with [Remote CAN Access](https://docs.autopi.io/developer_guides/can-bridge/)
- **RFID workflows:** Integrate RFID-based identification workflows with your setup using [RFID Integration](https://docs.autopi.io/developer_guides/rfid-integartion/)

## For AI Tools & RAG

The AutoPi documentation is published in LLM-friendly formats so you can plug it
directly into ChatGPT, Claude, Cursor, Continue, or your own RAG pipeline - no
scraping required.

- [`llms.txt`](https://docs.autopi.io/llms.txt) - an index of every documentation page, following the [llmstxt.org](https://llmstxt.org/) standard.
- [`llms-full.txt`](https://docs.autopi.io/llms-full.txt) - the complete AutoPi documentation as one machine-readable Markdown document, ready to ingest.
- Every page is also available as clean Markdown by appending `index.md` to its URL (e.g. `https://docs.autopi.io/cloud/index.md`).

These files are regenerated on every documentation build, so anything you index
stays in sync with the site.