Skip to main content

Bitboy Simulator Guide

This guide will comprehensively walk you through the installation and configuration process of the Bitboy simulator to meet your development needs. The Bitboy simulator provides developers with a fully functional simulation environment, enabling you to test and develop applications on the Bitboy OS platform without requiring actual hardware devices, greatly improving development efficiency.

What You'll Achieve

After completing this guide, you'll have a fully functional Bitboy simulator environment for developing and testing Bitboy OS applications. This will significantly accelerate your development process, allowing you to conduct comprehensive application testing and debugging without relying on physical hardware.

Prerequisites​

Before beginning the installation process, ensure your system meets the following requirements:

  • Sufficient disk space: Reserve at least 5GB of available space for installing Android Studio and simulator-related files
  • Administrator/sudo privileges: Essential for installing and configuring system components
  • Stable internet connection: Recommended speed of at least 10 Mbps to ensure smooth downloading of necessary installation packages
  • Compatible hardware environment: Computer equipped with virtualization technology support (must be enabled in BIOS)
  • Basic system requirements:
    • Processor: 64-bit processor, recommended at least 4 cores
    • Memory capacity: Minimum requirement of 8GB (16GB or higher configuration recommended for a smoother experience)
    • Operating system: Windows 10 64-bit, macOS 10.14 (Mojave) or higher, or Linux 64-bit system

Downloading Required Files​

Setting up the Bitboy simulator environment requires downloading two main components:

1. Android Studio Installation Package​

Android Studio is the foundation platform for running the Bitboy simulator, providing the necessary development environment and tools, including the critical Android Virtual Device (AVD) manager.

  • Download the latest version of the Android Studio installation package from the official website
  • Choose the appropriate version for your operating system (Windows, macOS, or Linux)
  • The installation package is approximately 1GB in size, so ensure your internet connection is stable and reliable

2. AOSP Simulator Package​

Download the AOSP simulator package that matches your operating system architecture. These packages contain customized Bitboy OS system images and necessary configuration files, which are core components for the simulator to function properly.

note

Be sure to download the software package that exactly matches your system architecture. Using mismatched packages may cause serious performance issues or compatibility errors, affecting the normal operation of the simulator.

Installation Steps​

1. Installing Android Studio​

Android Studio is the foundation platform for the Bitboy simulator environment. Please follow these steps carefully to ensure correct installation:

  1. Launch the Android Studio installer:

    • Windows: Run the downloaded .exe file and follow the installation wizard's instructions
    • macOS: Open the downloaded .dmg file and drag the Android Studio icon to the Applications folder
    • Linux: Extract the downloaded .tar.gz file, then run the studio.sh script to start installation

  2. Setup Wizard Configuration:

    • When prompted during installation, select "Standard Installation"
    • This option automatically includes the most commonly used and necessary components for Android development, simplifying the installation process
    • The installation wizard will automatically download and install core components such as Android SDK, emulator, and platform tools

  3. First Launch Setup:

    • After installation is complete, launch the Android Studio application
    • If prompted, you can choose to import previous settings or select "Don't import settings" to start with a fresh configuration
    • Android Studio will perform initialization setup and environment configuration; please be patient during this process

  4. Configure SDK Platform Tools:

    a) Open the SDK Manager in Android Studio:

    SDK Manager

    • Click on Tools > SDK Manager in the main menu
    • Or click directly on the SDK Manager icon in the toolbar for quick access

    b) Locate and note down the Android SDK Location path:

    SDK location

    • This path is typically located in the ~/Library/Android/sdk directory on Mac systems
    • Or in the C:\Users\<username>\AppData\Local\Android\Sdk directory on Windows systems
    • Be sure to record this path, as you will need it when configuring the Bitboy simulator later

    c) Configure SDK Platform components:

    SDK tool

    • In the "SDK Platforms" tab, check the "Show Package Details" option in the bottom right corner
    • Scroll to find the "Android 11.0 (R)" section
    • Select the following key components:
      • Android SDK Platform 30 (base platform component)
      • For Intel/AMD system users: AOSP A TD Intel x86_64 Atom System Image
      • For ARM architecture systems (such as M1/M2 Mac): AOSP A TD ARM 64 v8a System Image

    d) Click the "Apply" button and confirm the changes

    • The system will begin downloading and installing the selected components
    • This process may take anywhere from a few minutes to tens of minutes, depending on your internet connection speed and computer performance
Important Note

Selecting the correct system image for your hardware architecture is crucial. Devices with Intel/AMD processors should use the x86_64 image, while devices with ARM architecture processors (such as Apple Silicon chips) must use the ARM 64 v8a image. Selecting the wrong image will result in the simulator not functioning properly or experiencing severe performance degradation.

2. Configuring AVD Manager​

The Android Virtual Device (AVD) manager is the core tool for setting up and managing virtual devices:

  1. In Android Studio, go to Tools > AVD Manager via the menu bar
  2. Important note: If you have previously installed simulators, first select them and click the "Delete" button to avoid conflicts with the new Bitboy simulator. This step is crucial for the proper functioning of the Bitboy simulator; do not skip it.

3. Installing the AOSP Simulator​

The AOSP simulator installation process needs to follow specific steps to ensure proper integration with Android Studio and your development environment for seamless collaboration.

If you have already installed a simulator, you need to first delete the original simulator instance in the AVD manager:

AOSP install

Extracting the Package​

  1. Extract the downloaded AOSP simulator package to a directory with an English name (e.g., "aosp")

    • Important note: Only use English characters in the path; avoid using Chinese, Japanese, or other non-English characters to prevent potential compatibility issues
    • Also avoid using spaces or special characters in directory names, as these may cause unexpected errors during command-line operations

The graphical launcher is the recommended installation method in the original documentation, with simple and intuitive operation:

  1. Navigate to the location of the extracted folder
  2. Find and double-click the bitboy_launcher.exe file (Windows) or bitboy_launcher (macOS) to start the installation program
  3. When the launcher interface opens, you need to configure the following key paths:
    • Set the Android SDK path to the location you noted down during Android Studio setup
    • Set the AVD path (typically located at ~/.android/avd on Mac systems or C:\Users\<username>\.android\avd on Windows systems)
  4. Click the "Install" button to continue the installation process; the launcher will automatically complete the remaining configuration

Command Line Installation Method (Traditional Method)​

note

This method is for reference only and has been deprecated by the official team. It is strongly recommended to use the launcher program mentioned above for installation. Consider this method only if you are an advanced user or have special requirements.

Steps for Mac users:

  1. Open the Terminal application
  2. Use the cd command to navigate to the location of the extracted folder
  3. Run the following command, replacing the paths with your actual SDK and AVD paths:
./install.sh -s /Users/<username>/Library/Android/sdk -a /Users/<username>/.android/avd

Steps for Windows users:

  1. First download and install Git for Windows from git-scm.com
  2. After installation, open the Git Bash terminal
  3. Use the cd command to navigate to the location of the extracted folder
  4. Run the following command, replacing the paths with your actual SDK and AVD paths:
./install.sh -s C:/Users/<username>/AppData/Local/Android/sdk -a C:/Users/<username>/.android/avd
  1. When prompted during installation, respond with 'y' (indicating agreement) to all options to continue the installation

4. Configuring AVD in Android Studio​

After completing the basic installation with the launcher, you need to configure the actual virtual device parameters in Android Studio:

  1. In Android Studio, open the Virtual Device Manager interface:

avd manager

  1. Find and click to open the edit box for the BitboyEmu simulator:

avd manager

  1. As shown in the image below, click the Change buttons next to Device Profile and SDK for detailed configuration:

avd manager

  1. Set up the Device Profile:
    • Click the Import Hardware Profile option
    • Navigate to the extracted aosp directory and select the device.xml file
    • After successful import, find and select BitboyEmu from the list, then click OK to confirm
    • Note: If you have previously imported a profile, you need to right-click and delete the old profile first, then reimport to avoid conflicts

avd manager avd manager

  1. Set up the SDK (system image):
    • Confirm the selection and click the OK button

avd manager

  1. Click the "Finish" button at the bottom of the AVD configuration page to save and complete the AVD configuration:

avd manager

  1. Close the Device Manager dialog (Important: Do not run the simulator directly from the AVD manager):

avd manager

Launching the Simulator​

Before launching the simulator, ensure you have correctly completed all configuration steps to avoid potential issues.

Pre-launch Preparation​

  • Windows users must ensure that Hyper-V virtualization support is enabled (can be enabled in BIOS settings)
  • Some Windows systems may require separate installation of the Microsoft Visual C++ runtime library; please install as prompted

Launching with the Launcher​

This is the officially recommended method for launching the simulator, which is simple and reliable:

  1. Find and open bitboy_launcher.exe (Windows) or bitboy_launcher (macOS) from the extracted AOSP folder
  2. In the launcher interface, select a skin/theme you like from the available options
  3. Click the "Launch" button, then patiently wait for the simulator to complete the startup process
  4. Please note that the first launch usually takes longer (possibly a few minutes) as the system needs to initialize and configure

Installing Applications on the Simulator​

After successfully launching the simulator, you can install applications using the following two convenient methods:

  1. Drag and Drop Installation: Directly drag and drop the APK file onto the simulator window, and the system will automatically begin the installation process
  2. ADB Command Installation: Use the Android Debug Bridge command-line tool to install applications:
adb install <path-to-apk-file>

Debugging React Native Applications​

When developing React Native applications on the Bitboy simulator, you can use the following steps to connect and debug your application:

  1. First, check the list of available devices by running:
adb devices

This command will display all connected devices, with output similar to:

List of devices attached
emulator-5554   device
1234567890abcdef   device
  1. To run your React Native application on a specific simulator device, use the --deviceId parameter:
npx react-native run-android --deviceId=emulator-5554

Replace emulator-5554 with the actual device ID shown in the adb devices output.

Support and Help​

If you encounter any issues or difficulties not covered in this guide during use, please feel free to contact the Bitboy developer support team for professional assistance. Our technical team is ready to help you resolve various issues, ensuring your development experience is as smooth and efficient as possible. Whether it's technical consultation or troubleshooting, we are committed to providing you with support.