How to download, check and write the IoT box image¶

Download the Viindoo IoT Box image of your series from the Viindoo/iot-hw releases page, check its checksum, then write it to a microSD card with Raspberry Pi Imager, without any OS customisation. The box makes its own host name, passwords and certificate at its first start.

Who	The IoT Integrator who sets up the box.
App	Internet of Things

Before you start

You have the hardware listed in What you need before you set up an IoT box.
Your computer has a microSD card slot, or a USB card reader that takes microSD cards. A slot for full-size SD cards works with a microSD-to-SD adapter.
Raspberry Pi Imager is installed on your computer.

How do I find the release for my series?¶

In Viindoo, open Settings ‣ General Settings and scroll to the About block. It shows the version of your database; its series is the first part of that version, up to the first digit after the dot.
Open the releases page of the box software: Viindoo/iot-hw releases.
Take a release that is not marked Pre-release and whose title (Viindoo IoT Box followed by the series) and image file name (viindoo-iot-box- followed by the series) carry your series. Do not simply take the most recent release: it may belong to another series.
If no release for your series is listed, contact support (apps.support@viindoo.com) before you buy hardware for a new site.

How do I download and check the files?¶

Download two files of the release into one folder: the image viindoo-iot-box-<series>-<release>.img.xz and SHA256SUMS, which holds the checksum of the image. manifest.txt, on the same page, lists what the image holds; the check does not need it.

Open a terminal in that folder and check the image:

Linux: sha256sum --check SHA256SUMS
macOS: shasum -a 256 --check SHA256SUMS
Windows: certutil -hashfile viindoo-iot-box-<series>-<release>.img.xz SHA256, then compare the checksum it prints with the one beside the file name in SHA256SUMS (Windows has no option that compares them for you).

On Linux and macOS the answer must be <image file>: OK. If it says FAILED, download the image again.

Do not unpack the .img.xz file: Raspberry Pi Imager writes it as it is.

How do I write the card?¶

Put the microSD card in the card slot or the card reader of your computer. Writing erases everything on the card.
Open Raspberry Pi Imager on your computer.
For the operating system, choose the custom image option (“Use custom”) and pick the .img.xz file.
Choose the microSD card and write it. Check that you chose the card and not another disk of your computer.
Do not apply any OS customisation: the box makes its own host name, passwords and certificate at its first start.
Wait until Raspberry Pi Imager says that the card is written, then take the card out.

After the card is written, your computer may say that it cannot read a partition of the card and offer to format it. Cancel: the card is ready for the box as it is.

Common errors¶

Problem	What to do
The check says `FAILED`.	The download is damaged or incomplete. Download the image again and check it again.
On Windows, the checksum that `certutil` prints differs from the one in `SHA256SUMS`.	Check that you compared the line of the same file name, then download the image again.
Raspberry Pi Imager does not list the card.	Take the card out and put it in again, or try another card reader.
No release of my series is listed.	Contact support (apps.support@viindoo.com) before you buy hardware for a new site.

Next steps¶

How to start the IoT box and connect it to your network: put the card in the board and start the box.