User Manual
Add existing device - WINDOWS
This page guides you through connecting an existing Windows device to your awaBerry account, from setting up Windows Subsystem for Linux (WSL) to registering your device name and installing the necessary software.
Add existing device - WINDOWS
Summary
This comprehensive guide helps you connect your existing Windows device to awaBerry. The process involves several key steps: first, ensuring your Windows Subsystem for Linux (WSL) is properly installed and configured. Next, you will assign a unique name to your device within the awaBerry platform. After successful registration of the device name, the system provides you with a unique device ID and installation commands to be executed on your Windows device (within WSL). Finally, the system will monitor for your device to come online and complete its setup, confirming a successful connection and preparing your device for use with awaBerry.
Page Access
You can access this page by navigating to: /connect_steps_existing?os=windows
Page Functionalities
Step 1: Set Device Name (Windows Setup)
This is the starting point for connecting your Windows device. It provides crucial setup instructions and allows you to name your device.
- Error Message Area: At the top, a red box will appear if any errors occur during the device naming or registration process.
- Windows Setup Requirement Box: This section provides instructions specific to Windows devices, guiding you through the installation of Windows Subsystem for Linux (WSL).
- 1. Ensure WSL is Installed: A link to the official Microsoft documentation helps you install WSL.
- 2. Download WSL Autostart Script: A download link for a script (`setup_wsl_autostart_for_awaberry.ps1`) that automates WSL and awaBerry startup.
- 3. Run the Installation Script: Detailed steps for executing the downloaded script in Windows PowerShell (Admin), including a command to enable script execution if necessary and the command to run the script itself. Both commands can be copied directly.
- Device Name Input Field: Here you enter a desired name for your device. The name must be at least 3 characters long.
- Start Windows Linux Subsystem: A reminder to ensure your WSL terminal is open and ready.
- Installer URL Copy Option: This provides a command to download the awaBerry installer script. Click the text to copy it and paste it into your device's terminal (within WSL) to begin the download.
- Installer Start Command Copy Option: After downloading the script, this provides the command to make it executable and run it. Copy and paste this into your terminal (within WSL) to start the installation.
- Continue Button: After providing a device name and understanding the installation steps, click this button to proceed to the next step.
Step 2: Show Device ID
After successfully providing a device name, this page displays a unique ID for your device.
- Back Button: Allows you to return to the previous step if you need to change the device name.
- Device ID Display: Your unique device ID is shown. Click on the ID to automatically copy it to your clipboard.
- Instruction: A message guides you to paste this device ID into your device's terminal when prompted by the awaBerry installer.
- Continue Button: Once you have copied and used the device ID in your terminal, click this button to move forward.
Step 3: Waiting for Device
This page monitors the connection status, waiting for your device to come online after you have run the installer.
- Waiting Message: Displays 'Waiting for device to come online...'.
- Progress Indicator: A linear bar shows the progress of the waiting period. The system waits for up to 2 minutes for your device to report its online status.
- Error Message (if timeout): If the device does not come online within the specified time, an error message will appear: 'Device did not send an online state after 4 minutes.' accompanied by a suggestion to double-check your installation and a 'Try Again' button.
- Try Again Button: If the connection times out, clicking this button will take you back to the 'Set Device Name' step to restart the process.
Step 4: Device Connection Successful
This final page confirms that your device has successfully connected to awaBerry and is undergoing final configuration.
- Success Banner: A prominent message confirms 'Device connection successful' and specifies the name of your connected device.
- Device Information: Displays key details about your newly connected device, such as its local IP address and memory in MB.
- Configuration Progress: A progress indicator and messages like 'Waiting for device configuration and installation' and 'Usually takes 1-2 minutes.' inform you that the final setup is underway.
Scenario Executions
Possible usage steps within this page
Here are common scenarios demonstrating how a user would successfully connect a Windows device to awaBerry.
Scenario: Successful New Device Connection on Windows
This scenario covers the full, successful process of connecting a new Windows device.
- Initial Access: You navigate to the 'Add existing device - WINDOWS' page.
- WSL Setup: You follow the instructions in the 'Windows Setup Requirement' box to install WSL, download the autostart script, and run the installation script in PowerShell (Admin) on your Windows machine.
- Name Your Device: You enter a unique and descriptive name (e.g., "MyHomeServer") into the 'Device name' field.
- Proceed to Device ID: You click the 'Continue' button. The page transitions to display your unique 'Device ID'.
- Installer Execution: You copy the provided 'Installer URL' command, open your WSL terminal (ensuring Linux is running), paste and execute the command to download the installer.
- Start Installer: You then copy the 'Installer Start Command' (`sudo chmod +x install.sh && sudo ./install.sh`), paste it into your WSL terminal, and execute it. When prompted by the installer, you paste the copied 'Device ID'.
- Confirm Device ID Usage: Back in the browser, you click the 'Continue' button on the 'Show Device ID' page.
- Waiting for Online Status: The page changes to 'Waiting for device to come online...', showing a progress bar. You wait for this process to complete, which indicates your device has connected to the awaBerry backend.
- Final Configuration: The page then updates to 'Device connection successful', showing a final progress bar for 'Waiting for device configuration and installation'. After a short wait, you are automatically redirected to the device configuration page.
Possible errors which may occur on this page
These scenarios describe potential issues and how the system responds.
Error: Device Name Too Short
If you enter a device name that is less than 3 characters long (e.g., "ab") and click 'Continue', the system will prevent you from proceeding. An error message will appear directly below the input field, stating: "At least 3 chars". You must provide a longer name to continue.
Error: Device Name Already in Use
If you attempt to register a device name that is already in use by another one of your devices (e.g., "ExistingServerName") and click 'Continue', a full-width error message will appear at the top of the page. It will inform you: "Device name exists in devices: ExistingServerName. Choose another device name." You will need to enter a different, unique name to proceed.
Error: Device Does Not Come Online
After providing a device name and proceeding to the 'Waiting for device' step, if your physical Windows device (running WSL and the awaBerry installer) does not successfully connect to the awaBerry servers within approximately 2 minutes (120 seconds), the waiting process will time out. The page will then display a full-width error message: "Device did not send an online state after 4 minutes." It will also advise you to "Please double-check your installation." and offer a 'Try Again' button to restart the connection process from the 'Set Device Name' step.
