Add existing device - select operating system -> Add existing device - WINDOWS

Add existing device - WINDOWS

Summary

This manual page explains how to connect your existing Windows device to the Awaberry platform. You will be guided through setting a unique name for your device, installing necessary software by copying commands into your device's terminal, and verifying its successful connection. The process ensures your device is properly recognized and ready for use within the Awaberry ecosystem.

Page Access

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

Page Functionalities

Device Name Input Field

Purpose: Use this field to enter a memorable name for your Windows device. This name will help you easily identify your device within the Awaberry Portal.

Validation: The name you choose must be at least 3 characters long and unique. If the name is too short or has already been taken by another device in your account, an error message will appear.

Windows Icon

This icon visually confirms that you are currently in the process of connecting a Windows device.

Instruction Text (Windows Subsystem for Linux)

This text reminds you that for Windows devices, the Windows Subsystem for Linux (WSL) must be installed and running on your device before you proceed with the software installation steps.

Software Download Command

This is a pre-written command that you need to copy. Paste this command directly into the terminal window of your Windows device (specifically within your WSL environment) to download the Awaberry installer script.

Installer Start Command

Another pre-written command to copy and paste into your device's terminal after the download is complete. Executing this command will start the Awaberry installer. Important: This command must be run with administrator (root) privileges on your device (e.g., by using sudo).

"Continue" Button

After you have entered a valid and unique device name, and initiated the software download and installation on your Windows device, click this button to proceed to the next step of the connection process.

Device ID Display (Next Screen)

On the subsequent screen, a unique identifier (Device ID) for your newly registered device will be shown. This ID is crucial for establishing the final connection.

Copy Device ID Button (Next Screen)

This button allows you to quickly copy the displayed Device ID to your clipboard with a single click, preventing manual typing errors.

Instruction Text (Paste Device ID - Next Screen)

This instruction guides you to paste the copied Device ID into the terminal or console of your Windows device to finalize its setup.

Waiting Indicator (Waiting Screen)

This section will appear after you've provided the Device ID. It displays a message like "Waiting for device to come online..." along with a progress bar. The system is actively waiting for your Windows device to connect and report its online status to Awaberry.

Error Message Area (Waiting Screen)

If your device fails to connect within approximately 2 minutes (120 seconds), an error message will appear here, typically advising you to re-check the installation. A "Try Again" button will also be provided to re-initiate the waiting process.

Success Message (Final Screen)

Upon successful connection, this page will display a clear message confirming that your Windows device has been connected to Awaberry.

Device Information Display (Final Screen)

This section will show key details about your connected device, such as its local IP address and available memory.

Configuration Progress (Final Screen)

After a successful connection, you will see a message and a progress bar indicating that your device is undergoing final configuration and installation steps. This page will automatically redirect you once the process is complete.

Scenario Executions

Possible usage steps within this page

1. Successful Device Connection from Start to Finish

This scenario describes the complete, successful process of connecting a new Windows device to Awaberry.

  1. Step 1: Set Device Name & Install Software.
    • On the "Add existing device - WINDOWS" page, locate the "Device name" input field.
    • Enter a unique name for your device, for example, MyNewWindowsPC.
    • Ensure Windows Subsystem for Linux (WSL) is installed and running on your Windows machine. Open a WSL terminal.
    • Copy the command displayed under "Copy the installer URL and paste it in the terminal of your device to start the download." (e.g., curl [download_url] -o install.sh).
    • Paste this command into your WSL terminal and press Enter to download the installer script.
    • Copy the command displayed under "To start the installer, copy and paste the following commands to the terminal of your device." (e.g., sudo chmod +x install.sh && sudo ./install.sh).
    • Paste this command into your WSL terminal and press Enter. Provide your administrator password if prompted to run the installer with root privileges.
    • After the commands are executed on your device, click the "Continue" button on the Awaberry web page.
  2. Step 2: Copy Device ID.
    • The page will transition to "Connecting device: MyNewWindowsPC - Please copy the displayed device id and paste it in the console."
    • Locate the displayed Device ID (a long string of characters).
    • Click the "copy" icon next to the Device ID to copy it to your clipboard.
    • Paste this copied Device ID into the terminal of your Windows device (WSL) as instructed by the installer script running there.
    • Click the "Continue" button on the Awaberry web page.
  3. Step 3: Wait for Device to Come Online.
    • The page will now display "Connecting device: MyNewWindowsPC - Waiting for online notification."
    • You will see a progress bar indicating that the system is waiting for your device to establish its connection and report its online status.
    • During this time, your Windows device (via the installer script) should be communicating with the Awaberry platform.
  4. Step 4: Connection Successful & Configuration.
    • Once your device successfully connects, the page will change to "Device connection successful."
    • You will see a success message, details about your device (like its IP address and memory), and a new progress bar indicating "Waiting for device configuration and installation."
    • After a short period (typically 1-2 minutes), this page will automatically redirect you to the device configuration section within the Awaberry Portal, signaling that your device is fully connected and ready to be managed.

Possible errors which may occur on this page

1. Error: Device Name Too Short

  • How it happens: You attempt to proceed after entering a device name with fewer than three characters, for example, "PC".
  • What you see: Directly below the "Device name" input field, an error message appears in red text: "At least 3 chars".
  • Why this error occurs: Awaberry requires device names to be descriptive enough for easy identification, thus enforcing a minimum length of 3 characters.
  • How to fix: Simply edit the "Device name" field to include at least three characters (e.g., "MyPC").

2. Error: Device Name Already in Use

  • How it happens: You attempt to proceed after entering a device name that has already been registered with another device in your Awaberry account, for example, "OfficeServer" if you previously connected a device with that name.
  • What you see: At the very top of the page, within a prominent red box, an error message is displayed: "Device name is already in use - please use another one."
  • Why this error occurs: Each device connected to your Awaberry account must have a unique identifier (name) to prevent conflicts and ensure correct management.
  • How to fix: Choose a different, unique name for your device that has not been used before in your account.

3. Error: Device Not Online (Installation/Connectivity Timeout)

  • How it happens: After you have successfully entered a device name, copied the Device ID, and clicked "Continue" on the Device ID page, the system enters a waiting period for your Windows device to report its online status. If your device fails to establish this connection within approximately 2 minutes (120 seconds), this error occurs. Common causes include incorrect software installation on your Windows device, network issues preventing communication, or the device simply being offline.
  • What you see: The "Waiting for device to come online..." screen will eventually change. A prominent red error box will appear at the top, stating: "Device did not send an online state after 4 minutes." Below this, you will see a text prompt: "Please double check the installation in the terminal." and a "Try Again" button.
  • Why this error occurs: The Awaberry platform did not receive the expected "online" signal from your newly configured Windows device within the allocated time. This indicates a problem with the device's setup or network communication.
  • How to fix:
    1. Verify Installation: Go back to your Windows device's WSL terminal. Carefully review the output from the sudo chmod +x install.sh && sudo ./install.sh command. Look for any error messages or failed steps during the installation process. Ensure the Device ID was pasted correctly into the running installer.
    2. Check Network: Confirm that your Windows device has an active and stable internet connection.
    3. Restart Installation: If you suspect an installation issue, it might be best to restart the entire installation process on your Windows device, ensuring all commands are run correctly.
    4. Retry Connection: Once you've checked or re-executed the installation steps, click the "Try Again" button on the Awaberry web page. This will restart the waiting process. If the issue persists, you might consider restarting the entire connection flow from the "Set Device Name" step.

Up to User Manual Main Page