User Manual
Add existing device - MAC
This manual page guides you through connecting your existing Mac device to awaBerry, including setting up remote access, installing necessary tools, and registering your device.
Add existing device - MAC
Summary
This page provides comprehensive instructions for connecting your existing Mac device to the awaBerry system. It guides you through essential prerequisites such as enabling remote SSH access and installing Homebrew, allowing you to then register your device by assigning a unique name. Following successful registration, you will receive a device ID to be used in the terminal, after which the system will monitor for your device to come online and finalize its configuration.
Page Access
You can access this page by navigating to: /connect_steps_existing?os=mac
Page Functionalities
This page facilitates the connection of your Mac device to awaBerry by providing a structured flow of information and interactive elements:
- Mac Setup Requirement Box: Displays crucial steps to prepare your Mac, including instructions on how to enable "Remote Login" through your Mac's System Settings (General > Sharing). This is essential for awaBerry to communicate with your device.
- Homebrew Installation Requirement Box: Guides you through installing Homebrew, a package manager for macOS, which is needed to install other tools. It includes the exact command you need to run in your Terminal.
- Device Name Input: A text field labeled "Device name" where you can enter a unique name for your Mac within the awaBerry system. This name must be at least 3 characters long.
- Installer Download Command: A copyable command to download the awaBerry installer script directly to your Mac via the Terminal.
- Installer Execution Command: A copyable command to make the downloaded installer script executable and then run it in your Terminal.
- Error Message Area: A dedicated section that becomes visible to display clear, non-technical error messages if there are issues during device name entry or connection.
- "Continue" Button: Proceeds to the next step in the connection process after you have provided a valid device name and initiated the installation on your Mac.
- Device ID Display: On the subsequent page, your unique "Device ID" is shown. You can click on this ID to easily copy it to your clipboard for pasting into your Mac's Terminal.
- Progress Indicator: While waiting for your device to come online and finalize its setup, a progress bar will be displayed, indicating that the system is monitoring the connection.
- Success Message: Upon successful connection and initial configuration, a message will confirm that your device is connected, along with its IP address and memory information.
Scenario Executions
Possible usage steps within this page
Scenario: Successfully connecting a new Mac device.
- Prepare your Mac: Follow the instructions in the "Mac Setup Requirement" box to enable "Remote Login" in your Mac's System Settings (General > Sharing).
- Install Homebrew: Open your Mac's Terminal (Applications > Utilities > Terminal). Copy the Homebrew installation command provided in the "Ensure to install Homebrew (brew)" box and paste it into the Terminal, then press Enter. Follow any on-screen prompts.
- Enter Device Name: In the "Device name" field on this page, type a unique name for your Mac (e.g., "MyMacStudio" or "OfficeiMac"). Ensure it's at least 3 characters long.
- Download awaBerry Installer: Copy the installer URL command (starting with
curl) from this page and paste it into your Mac's Terminal. Press Enter to download theinstall.shscript. - Run awaBerry Installer: Copy the installer execution command (starting with
chmod) from this page and paste it into your Mac's Terminal. Press Enter to start the installation. - Copy Device ID: Once the page updates to display your unique "Device ID", click on the displayed ID to automatically copy it to your clipboard.
- Paste Device ID: Switch back to your Mac's Terminal. The awaBerry installer will prompt you for the Device ID. Paste the copied ID into the Terminal and press Enter.
- Finalize Connection: Click the "Continue" button on the awaBerry connection page. The system will now wait for your Mac to establish a connection. A progress indicator will show the monitoring process.
- Connection Confirmation: After a short wait, a success message will appear, confirming your Mac is connected to awaBerry. You will then be guided to further configure your device.
Possible errors which may occur on this page
Error: Device Name is too short.
- How it happens: If you try to enter a device name that has fewer than 3 characters (e.g., "my"), the system will not accept it.
- What you see: An error message "At least 3 chars" will appear below the device name input field.
- How to fix: Simply enter a device name that contains 3 or more characters.
Error: Device Name is already in use.
- How it happens: If you enter a device name that you have already used for another device connected to your awaBerry account, the system will prevent duplication.
- What you see: An error message like "A device with name [YourDeviceName] exists already. Please choose another device name." will appear in the error message area.
- How to fix: Choose a different, unique name for your Mac and try again.
Error: Device did not come online within the expected time.
- How it happens: After you've entered the device ID into your Mac's Terminal and clicked "Continue" on the awaBerry page, the system expects your Mac to come online within a few minutes. If the Mac does not establish a connection within this timeframe, possibly due to issues with remote login, Homebrew, or the installer script, this error occurs.
- What you see: The progress indicator will stop, and an error message "Device did not send an online state after 4 minutes." will appear, along with a suggestion to "Please double check the installation in the terminal." and a "Try again" button.
- How to fix:
- Revisit the "Mac Setup Requirement" and "Homebrew Installation Requirement" sections on this page. Ensure remote login is correctly enabled and Homebrew is installed and working on your Mac.
- Check your Terminal for any error messages that might have appeared during the awaBerry installer script execution. Address those issues.
- You can click the "Try again" button to restart the waiting process after resolving any underlying installation problems.
