The AI-Native Device Platform
User Manual

Add existing device - LINUX

This page guides you through connecting an existing Linux device to awaBerry by setting a device name, installing necessary software, and verifying the connection.

Add existing device - LINUX

Summary

The 'Add existing device - LINUX' page is the starting point for integrating your Linux-based device with the awaBerry system. This multi-step process ensures a secure and functional connection. You will begin by assigning a unique name to your device, followed by on-screen instructions to prepare your Linux machine, including verifying or installing OpenSSH. Crucially, you will copy specific commands from this page to run in your device's terminal, initiating the awaBerry client software installation. The system then waits for your device to report its online status, eventually leading to a successful connection and readiness for remote management.

Page Access

You can access this page by navigating to: /connect_steps_existing?os=linux

Page Functionalities

  • Linux Setup Requirements Box: This section provides vital information and commands to prepare your Linux device.
    • Check if OpenSSH is Running: Displays a command (sudo systemctl status ssh) to verify if OpenSSH is active on your Linux system. A copy option is provided for convenience.
    • Install OpenSSH (if not already installed): Offers a command (sudo apt-get update && sudo apt-get install -y openssh-server openssh-client && sudo systemctl start ssh && sudo systemctl enable ssh) to install and enable OpenSSH. A copy option is provided.
  • Device Name Input Field: A text field where you enter a unique name for your new awaBerry device. This name helps identify your device within the awaBerry portal.
    • Validation: The system ensures the name is at least 3 characters long and not already in use by another one of your devices.
  • Installer URL Command: A command (curl $urlSoftwareDownload/data/software/awaberrybaseinstaller/install.sh -o install.sh) to download the awaBerry installer script. You can easily copy this command to your clipboard and paste it into your device's terminal.
  • Installer Start Command: A command (sudo chmod +x install.sh && sudo ./install.sh) to execute the downloaded installer script. This also has a copy option for use in your terminal.
    • Note: The installer requires root privileges, meaning you'll need to run it with sudo.
  • Device ID Display and Copy: After entering a device name, this section shows a unique Device ID generated for your device. You must copy this ID and paste it into the awaBerry installer running in your terminal.
  • Waiting for Device Online: Once the installer is running and the Device ID is entered, this section displays a progress bar indicating that awaBerry is waiting for your device to connect and report its online status.
    • Timeout: If the device doesn't come online within a few minutes, an error message appears with an option to 'Try Again'.
  • Successful Connection Details: Upon successful connection, this section confirms the connection, displays basic device information (like IP address and memory), and shows a progress indicator for the final configuration steps.
  • Continue Button: Advances you to the next step in the connection process after providing a device name or after the device ID is displayed.
  • Back Button: Allows you to return to the previous step in the connection process.
  • Error Message Area: If any issues arise (e.g., invalid device name, network problems, device not coming online), relevant error messages will be displayed here.

Scenario Executions

Possible usage steps within this page

Scenario 1: Successful Device Connection (New Device Name)

  1. Step 1: Enter Device Name. On the "Add existing device - LINUX" page, locate the "Provide the name of the device" text field. Enter a unique and descriptive name for your Linux device (e.g., "HomeServer-Linux").
  2. Step 2: Continue. Click the "Continue" button. The system will validate the name and proceed to generate a unique Device ID.
  3. Step 3: Copy Device ID. The next screen will display your generated Device ID. Click on the Device ID to automatically copy it to your clipboard.
  4. Step 4: Execute Installer on Device. Open a terminal on your Linux device.
    • First, copy the "Installer URL Command" provided on the awaBerry page (e.g., curl ... install.sh -o install.sh) and paste it into your terminal, then press Enter. This downloads the installer script.
    • Next, copy the "Installer Start Command" (e.g., sudo chmod +x install.sh && sudo ./install.sh) and paste it into your terminal, then press Enter. This starts the awaBerry installer.
    • When prompted by the installer in your terminal, paste the Device ID you copied in Step 3 and press Enter.
  5. Step 5: Wait for Connection. Return to the awaBerry web page. It will display a "Waiting for device" message with a progress bar. The system is now waiting for your device to report its online status.
  6. Step 6: Connection Successful. Once your device successfully connects and reports its online status (this might take a minute or two), the page will update to "Device connection successful," displaying device details like IP and memory, and will proceed to the device configuration.

Scenario 2: Successful Device Connection (Pre-configured OpenSSH)

  1. Step 1: Review Linux Setup Requirements. Before entering a device name, check the "Linux Setup Requirement" box. If OpenSSH is already installed and running on your Linux device (which you can verify using the provided sudo systemctl status ssh command), you can proceed.
  2. Steps 2-6: Follow Scenario 1. Continue with steps 2 through 6 as described in "Scenario 1: Successful Device Connection (New Device Name)".

Possible errors which may occur on this page

Error: Invalid Device Name

How it happens: You attempt to enter a device name that is too short (less than 3 characters). For example, entering "ab" instead of "mydevice".

What you see: An error message will appear below the device name field, such as "At least 3 chars".

How to fix: Enter a device name that is 3 or more characters long.

Error: Device Name Already in Use

How it happens: You try to use a device name that you have previously assigned to another device within your awaBerry account. For example, if you already have a device named "MyRaspberryPi" and you try to use that name again.

What you see: An error message will be displayed prominently above the device name field, stating something like "A device with name [YourChosenName] exists already. Please choose another device name."

How to fix: Choose a different, unique name for your new device.

Error: Device Fails to Come Online (Timeout)

How it happens: After you have entered the device name, copied the Device ID, and run the installer commands on your Linux device, the awaBerry web page enters a "Waiting for device" state. If your Linux device fails to connect to awaBerry and report its online status within approximately 4 minutes (240 seconds), a timeout error occurs.

What you see: The progress bar disappears, and an error message like "Device did not send an online state after 4 minutes." appears. Below it, a message "Please double check the installation in the terminal." and a "Try again" button will be shown.

How to fix:

  1. Check Terminal Output: Review the output in your Linux device's terminal where you ran the installer. Look for any error messages or unexpected behavior.
  2. Verify OpenSSH: Ensure OpenSSH is correctly installed and running on your Linux device, as outlined in the "Linux Setup Requirement" box.
  3. Network Connectivity: Confirm that your Linux device has active internet access and can reach the awaBerry servers.
  4. Re-run Installer: If unsure, you can try re-running the installer commands on your Linux device.
  5. Try Again: Click the "Try again" button on the awaBerry web page to restart the waiting process.

Navigate ← Add existing device - select operating system ← Add Device - how to connect ← Connect New Devices Mainpage ← awaBerry Device Management ← awaBerry User Manual Main Page