Skip to main content

Quickstart Guide

Welcome to Atym! This guide will get you started with Atym by walking you through the essential steps: setting up your development environment, configuring a target device, and connecting it to the Atym Hub.

This guide uses Linux (x86_64 PC or Raspberry Pi) as the example platform because it provides the simplest path to getting started—no firmware flashing or special hardware required. By the end of this guide, you'll understand Atym's core concepts and have a device ready to run containerized applications.

Using Other Hardware Platforms

This quickstart uses Linux as the example platform for the simplest getting started experience. Atym also supports a range of microcontroller boards and other hardware platforms. If you're working with different hardware, refer to the Board Support section for platform-specific setup guides.

Prerequisites​

Before getting started, ensure you have the necessary hardware and software components.

Hardware​

  1. Development Computer running Windows, macOS, or Linux (for installing the Atym tools)
  2. Target Device - For this quickstart, you'll need one of the following Linux devices:
    • x86_64 Linux PC (physical or virtual machine), or
    • Raspberry Pi 4 or 5 (aarch64)
  3. Internet Connection for downloading tools and accessing the Atym Hub

Software​

Text Editor (optional)​

While not strictly required, a good text editor will be helpful when working with configuration files and creating containerized applications. Visual Studio Code is a popular free option.

Installing the Atym CLI​

The Atym CLI is the primary tool we'll use for managing devices, building containers, and deploying to the Atym Hub. Installing it is the first step in setting up your Atym environment.

Step 1: Download the Atym CLI​

Download the appropriate build for your operating system and architecture:

On your Debian/Ubuntu client:

  1. Add the distribution repository (one-time): 
    echo "deb [trusted=yes] http://apt.dist.atym.io stable main" \
    | sudo tee /etc/apt/sources.list.d/myrepo.list
  2. Install via apt: 
    sudo apt update
    sudo apt install atym

Step 2: Verify the Installation​

Confirm that the CLI is installed correctly by checking the version:

atym version

You should see output similar to:

Atym CLI
Version: v1.0.3

If you see the version information, the installation was successful!

Step 3: Login to the Atym Hub​

Before you can manage devices and deploy containers, you need to authenticate with the Atym Hub:

atym login

Follow the prompts to complete the authentication process. Once logged in, you're ready to proceed to device setup.

Set Up Your Device​

Now that you have the Atym CLI installed, you're ready to set up your target device and connect it to the Atym Hub. For this quickstart, we'll use Linux as the example platform.

The Atym Linux Runtime works on x86_64 PCs and Raspberry Pi devices without requiring any firmware flashing, making it an ideal starting point for learning Atym.

Step 1: Create a Device Identity in the Atym Hub​

First, create a digital identity for your device using the Atym CLI on your development computer:

atym add device --deviceName "testDevice" --description "My test device" --serialNumber "1234567890"

If successful, you'll receive credentials including your deviceUUID and pskSecret:

{
  "deviceUUID": "67c1c350-cc1c-482d-bde9-875688ff9b23",
  "pskSecret": "IEAaeWHKhYs4fAScF5ApQ0C9eGcXu123",
  "tenantUUID": "2C9D9E73-702E-49DF-8181-F7B56849B864"
}

Copy these values to a secure location. You'll also need your tenant ID:

atym show config

Copy the Tenant ID value from the output.

Step 2: Download and Install the Atym Runtime​

On your Linux device, download the appropriate runtime for your architecture:

wget https://atympublicshare.blob.core.windows.net/runtime/linux/latest/atym-runtime-ubuntu-x86_64.tar.gz
tar -xzf atym-runtime-ubuntu-x86_64.tar.gz
cd atym-runtime

Step 3: Configure and Connect Your Device​

Run these commands on your device

The following commands must be run on your target device's shell, not on your development (commissioning) computer.

Configure your device with the credentials from Step 1:

atym config set device/id deviceUUID@tenantID
atym config set device/psk pskSecret
atym config set server/endpoint coapgw.prod.atym.io
atym config set server/port 5684

Replace deviceUUID, tenantID, and pskSecret with your actual values.

Verify your configuration:

atym config show

Once the configuration looks correct, press Ctrl+C to stop the runtime, then restart it to apply the new settings:

./bin/atym-runtime

When your device successfully connects, you'll see:

Client connected successfully

Your device is now connected to the Atym Hub and ready for container deployment!

Next Steps​

Now that you have your device connected to the Atym Hub, you are ready to start building and deploying containerized applications. Check out the Build and Deploy Containers guide to learn how to create, build, and deploy your first application to your device.

Additional Resources​

Need help? Contact us at eval@atym.io for evaluation program support.