How to create an image for your device

There are multiple ways to prepare OS image and install an edge device. Synpse does not care which Operating system it is running on as long as few requirements are met:

1. An operating system(OS) is Linux based
2. SystemD support
3. Docker support

But if you are starting from scratch, we will cover a few ways to do so. Feel free to choose your preference. And as always, if you struggle with any of the steps, please drop us a line on Discord and we will help you out!

###Method 1: Build from scratch

Download [rpi-imager](https://www.raspberrypi.org/software/ and install to your workstation. It’s a small application that will help you prepare SD card for your device.

Chose OS of your preference and SD card to write to:

Insert an SD card to device and connect it to the screen and keyboard. You will have to run several commands on your device.

Synpse relies on Docker to be preset. Once OS boots up, you will need to install it on your device.

Open a terminal and run the following commands:

1

curl -sSL https://get.docker.com | sh

Open the page https://cloud.synpse.net in your browser, login to it and navigate to Device section so you can copy and paste the Synpse installation command:

Important: If installing Synpse step is not clear, please read this blog post.

Paste the command into device CLI window:

Assuming device is connected to the internet - you should be done!

Method 2: Synpse image builder (Preview feature)

We are working on a new way to build Synpse enabled images. Currently we have WIP conceptual builder ready in synpse CLI based on Cloud-init method 3 bellow. You can either try CLI version of it, or use an advanced cloud-init method itself.

Anyway feedback on this topic is very welcome as we are still in the early stage of this feature.

CLI builder currently works on Linux only (Ubuntu subsystem for Windows is not supported)

In the long run, this should become cloud based service available in Synpse Cloud!

Prerequisites

1. Linux based machine (Ubuntu subsystem for Windows is not supported)
2. Synpse CLI installed and logged into Synpse Cloud
3. CLI must be ran as privileged user, because an image builds are using mount to build the image

After build, an image startup might take 10-15 minutes for updates and install process to complete. Time might wary based on your internet and device speed.

List available images

Chose base image you want to use for your build. If you don’t find base images you would like, let us know in Discord to see how we can help!

1

synpse machine-images list-base

Output example:

1
2
3

  OS      IMAGE                                               NAME                               ARCHITECTURE
  ubuntu  ubuntu-20.04.2-preinstalled-server-arm64+raspi.img  Ubuntu Server 20.04.2 LTS (ARM64)  arm64
  ubuntu  ubuntu-20.04.2-preinstalled-server-armhf+raspi.img  Ubuntu Server 20.04.2 LTS (ARM32)  arm32

Run build command with build parameters (parameters can be found by executing synpse build -h)

1
2
3
4
5
6

synpse build \
--hostname "synpse-edge" \
--image ubuntu-20.04.2-preinstalled-server-arm64+raspi.img \
--image-output $(pwd)/images \
--wifi-name WIFI_SSID_NAME \
--wifi-password $WIFI_PASSWORD

If --project-id or --registration-token is not provided CLI attempt to get the default provisioning token for the project configured in CLI. User must have access to read Device Provisioning Tokens in RBAC.

If --unixUser is not provided synpse user will be created.

Build using config file

For more re-usable build you can use config file build:

1

synpse build --config-file config.yaml

Where config file example is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

---
builderConfig:
  image: ubuntu-20.04.2-preinstalled-server-arm64+raspi.img
  outputDir: /home/user/images
synpseConfig:
  controllerURI: https://cloud.synpse.net/api
  projectID: prj_1qtJj73NFMHm0QoRj2uPWxxxxxx
  registrationToken: drt_1qtJj55aIhGiMrXs5BDAvxxxxx
hostConfig:
  hostname: synpse-edge
  unixUser: synpse
  sshKey: ssh-rsa ABCD
  #locale: en_US.UTF-8
  #timezone: Europe/Vilnius
  networks:
    - wifiAccessPointName: WIFI_SSID
      wifiAccessPointPassword: Wifi_Password

When build finishes successfully, you will find your image in --image-output directory. Once this image boots up, it should automatically connect to your wifi network and register to Synpse Cloud.

###Method 3: Cloud-init (advanced)

Here we will explain how to build an image in the advanced mode using cloud-init as the bootstrap method. It allows to produce re-usable images for mass usage or configure your device without access to them. This is an advanced method and requires some knowledge of cloud-init. You can use this way to construct your own CI/CD pipelines or flows to create re-usable images.

We will walk you through the whole process. These scripts will work with any image, which supports cloud-init. But we recommend using Ubuntu 20.04.2 LTS image.

1. Clone helper scripts repository:

1

git clone https://github.com/synpse-hq/image-tools && cd image-tools

2. Download image into assets/images directory. This can be done manually or with make download-base:

1

curl https://cdimage.ubuntu.com/releases/20.04.2/release/ubuntu-20.04.2-preinstalled-server-arm64+raspi.img.xz?_ga=2.31403323.502427891.1618417281-105156824.1616928492  -o assets/images/ubuntu-20.04.2.img.xz

3. Decompress Image. Extract image so we could use it:

1

unxz assets/images/ubuntu-20.04.2.img.xz

4. Add your Synpse project details and wi-fi credentials. Create a configuration for your local home setup:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# copy env.example fine
cp env.example env

# update env file with your configuration
export HOSTNAME=synpse
export UNIX_USER=synpse
export UNIX_PASSWORD=<unix password of you choosing>
# generate ssh key for SSH access. You can generate one by running `go run ./hack/genssh`
export SSH_KEY=$(cat ./assets/id_rsa.pub)
export LOCALE="en_US.UTF-8"
export TIMEZONE="Europe/Vilnius"
export WIFI_ACCESS_POINT_NAME="<my_awesome_wifi_ssid>"
export WIFI_ACCESS_POINT_PASSWORD="<my_awesome_wifi_password>"

# get cloud.synpse.net project_id and registration_token for device registration
export AGENT_PROJECT=prj_xxxxxxxxxxxxxxxx
export AGENT_REGISTRATION_TOKEN=drt_xxxxxxxxxxxxxxxx

5. Generate image

Generate cloud-init configuration and create a pre-configured image for RPI:

1

make generate-image

6. Write the image to an SD card

Once this is done, you can use any existing image “burning” tools to write this image into SD card. We recommend using one of these:

• RPI Builder
• Rufus
• Unetbootin

###./wrap_up

We understand that all this can be a bit overwhelming. We are working to make this easier for you to use and if you have any suggestions, ideas, or feedback, please let us know in our forum.