> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/deployment/self-hosted/enterprise/deployment-manager/setting-up/set-up-a-roboflow-os-lite-device.md).

# Set Up a Roboflow OS Lite Device

Get a Raspberry Pi ready to run your computer vision models: create an image in Roboflow, write it to a microSD card and power the device on.

Roboflow OS Lite gets a Raspberry Pi ready to run your computer vision models. In Roboflow, you create an image for your device, write it to a microSD card, and power the device on. It connects to your Roboflow Workspace by itself. You don't type any commands. You only need an app on your computer that writes the card.

{% hint style="info" %}
Each image is made for one device. It holds that device's sign-in details and your network settings. To set up another device, add it and create its own image.
{% endhint %}

## Before You Start

You need:

* A Raspberry Pi 4 or Raspberry Pi 5, with its power supply.
* A microSD card. Its contents are erased.
* A computer (Mac, Windows or Linux) with a microSD card reader and the free app [balenaEtcher](https://etcher.balena.io/).
* An Ethernet cable, or the name and password of a Wi-Fi network.

## Create the Device Image

{% stepper %}
{% step %}

### Add the device

1. In Roboflow, open "Deployments", then the "Edge Devices" tab.
2. Click "Add Device".
3. Enter a "Device Name".
4. Under "Device Type", choose "Roboflow OS Lite", then click "Continue".

The device is added to your Workspace, and the "Build Device Image" step opens.

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-a4fe7e836a59cbc596962298c1419ac6c5d0984c%2Fos-lite-add-device.gif?alt=media" alt="Adding a Roboflow OS Lite device in Roboflow"><figcaption><p>Add a device and choose "Roboflow OS Lite".</p></figcaption></figure>
{% endstep %}

{% step %}

### Choose the board and network

1. Under "Board", choose "Raspberry Pi 4" or "Raspberry Pi 5".
2. Optional: enter a "Hostname" (the device's name on your network).
3. Under "Ethernet", keep "DHCP" unless your network needs a fixed address. For a fixed address, choose "Static IP" and enter the "Address". Open "Advanced" to set the "Prefix Length", "Gateway" and "DNS Servers" your network needs.
4. To use Wi-Fi, turn on "Wi-Fi", then enter the "Network Name (SSID)". Choose "WPA2/WPA3 Personal" for a network with a password (the device connects with WPA2), or "Open" for one without. Enter the "Password" and the "Country" (a two-letter code, ex: US, DE). Select "Hidden network" if the network doesn't show its name.

If you set up both, the device prefers Ethernet and uses Wi-Fi when Ethernet isn't connected.

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-c6722839127dc0cc003cf829d69b578fc2f239ab%2Fos-lite-board-network.gif?alt=media" alt="Choosing Raspberry Pi 5 and entering Wi-Fi settings"><figcaption><p>Choose the board, then set up Ethernet or Wi-Fi.</p></figcaption></figure>
{% endstep %}

{% step %}

### Create and download the image

1. Click "Build Image". The build takes several minutes. You can close the window while it runs. Wait until "Your image is ready" shows.
2. Click "Download Image". Download the image before the link expires. The page shows when it expires.

The file name ends in `.img.xz`. Don't unzip it.

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-8acf68daa67ac0cdd891258ca0e97966ace9d33d%2Fos-lite-build-image.gif?alt=media" alt="Creating and downloading the SD card image for a Raspberry Pi"><figcaption><p>Create the image, then download it.</p></figcaption></figure>
{% endstep %}
{% endstepper %}

## Write the Card

Open balenaEtcher, choose the `.img.xz` file, choose your microSD card, and start the write. Wait for it to finish.

Raspberry Pi Imager also works: in "Choose OS", select "Use custom", then select the file.

## Start the Device

1. Put the card in the device.
2. Connect the Ethernet cable if you use one.
3. Plug in the power.

On the first start, the device downloads its settings and the software it needs to run models. This usually takes several minutes, and can take 30 minutes or more on a slow network.

To follow along, open the device in Roboflow ("Deployments", then "Edge Devices"). Until the device connects, it shows "Waiting for first connection". Click "View Setup Steps" to see each step and its download progress. When the setup steps finish and the device shows "Online", it is ready.

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-9f82e5222ba355544ed16513d9a45e0dfa5eba8e%2Fos-lite-first-boot-steps.png?alt=media" alt="Setup steps on the device page during the first start"><figcaption><p>The device page shows each setup step.</p></figcaption></figure>

{% hint style="info" %}
While the device sets up, build the model it will run. You can have an AI agent build it for you: see [Train a Computer Vision Model in ChatGPT with Roboflow](https://roboflow.com/blog/train-computer-vision-models-in-chatgpt).
{% endhint %}

## Keep the Image Safe

The image file and the card hold the sign-in details that let the device join your Workspace. Treat them like a password:

* Don't share the image file. Delete it after you write the card.
* Wipe the card before you use it for another device.
* If you lose a card or share an image by mistake, delete the device in Roboflow ("Delete Device" in the device menu) and confirm it no longer appears under "Edge Devices". This revokes its Roboflow sign-in details. If you set a Wi-Fi password, treat that password as exposed and change it on your network. Then add the device again and create a new image with the new network settings.

## Get a New Image

To write a new card for a device (ex: to replace a card or change its Wi-Fi network), open the device, click the device menu (⋮), then click "Build Device Image". The new image is for the same board. If the previous download is still available, you can download it again, or click "Build New Image" to change its settings. If its link has expired, click "Build New Image". Check the settings, then click "Build Image".

A Workspace creates one image at a time. If another image is being created, wait for it to finish, then try again.

<figure><img src="https://1583372177-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FoksNmwps1HmYr8TqHDnX%2Fuploads%2Fgit-blob-f946f1bb96160108ce6179bd8d0d1e7e74c11c8f%2Fos-lite-download-device-image.gif?alt=media" alt="Opening Build Device Image from the device menu"><figcaption><p>Get a new image from the device menu.</p></figcaption></figure>

## Troubleshooting

* The device never connects: if you use Wi-Fi, check the network name, password and country. The network must accept WPA2 (or be "Open"); a WPA3-only network doesn't work. Or connect an Ethernet cable, which the device prefers over Wi-Fi. To fix the Wi-Fi settings, [get a new image](#get-a-new-image). Unplug the power, take the card out, write the new image to it, put it back in the device, then plug the power back in.
* Writing the card fails or the device doesn't start: write the card again with balenaEtcher, using the same `.img.xz` file without unzipping it. If it fails again, try another card.
* The download link expired: open the device, click "Build Device Image", then "Build New Image". Check the settings, then click "Build Image".

## Next Steps

* [Add a Stream](https://docs.roboflow.com/deployment/self-hosted/enterprise/deployment-manager/setting-up/add-a-stream.md) to connect a camera and run a Workflow.
