diff --git a/.gitignore b/.gitignore index ff4af50..c96c82b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,6 @@ doctrees docs/ +_build/ *.bak *.swp diff --git a/src/en/Quickstart_Guide/Linux/Quickstart_Linux_ubuntu.rst b/src/en/Quickstart_Guide/Linux/Quickstart_Linux_ubuntu.rst index 479c846..33efb7a 100644 --- a/src/en/Quickstart_Guide/Linux/Quickstart_Linux_ubuntu.rst +++ b/src/en/Quickstart_Guide/Linux/Quickstart_Linux_ubuntu.rst @@ -106,6 +106,8 @@ Alternative Flashing Tools and Information `lupyuen <https://lupyuen.github.io/articles/pinecone#other-flashing-tools>`_ has an overview of alternative tools as well as an overview of the different components of the ROM. +.. _devcube-flashing-linux: + BouffaloLabDevCube ^^^^^^^^^^^^^^^^^^ diff --git a/src/en/Quickstart_Guide/Mac/Quickstart_macOS.rst b/src/en/Quickstart_Guide/Mac/Quickstart_macOS.rst new file mode 100644 index 0000000..adfcf1b --- /dev/null +++ b/src/en/Quickstart_Guide/Mac/Quickstart_macOS.rst @@ -0,0 +1,138 @@ +macOS Starter Guide +=================== + +This document explains how to set up a macOS environment, build the ``sdk_app_helloworld`` application, flash it to the BL602 and verify the output through a serial port reader. + +Installing prerequisites and cloning repository +----------------------------------------------- + +The project requires the Xcode Command Line Tools, which include the ``clang`` compiler and other build tools like ``make``, to be installed. Install the tools using one of the following methods: + +- Run ``xcode-select --install`` in Terminal. A dialog box will ask if you want to download and install the tools. +- `Apple Developer Downloads <https://developer.apple.com/download/all/?q=xcode>`_ offers the tools as a stand-alone dmg, which is smaller than full Xcode. +- Install `Xcode <https://apps.apple.com/us/app/xcode/id497799835>`_ from the Mac App Store. On the first run, Xcode should prompt to install the Command Line Tools. + +Next, clone the SDK repository: + +.. code-block:: bash + + git clone --recursive https://github.com/pine64/bl_iot_sdk + +Compiling +---------------------- + +First, set ``BL60X_SDK_PATH`` to the location of the ``pine64/bl_iot_sdk`` repository. +Next, set ``CONFIG_CHIP_NAME`` to the make of the chip in this case ``BL602``. +If the repository is already cloned, ``pwd`` can be used to correctly set the environment variable: + +.. code-block:: bash + + cd bl_iot_sdk + export BL60X_SDK_PATH=$(pwd) + export CONFIG_CHIP_NAME=BL602 + +In order to build all example projects run ``make`` in the project directory. +In order to build only a single example go to the directory of the example and run ``make``. +In order to build ``sdk_app_helloworld``: + +.. code-block:: bash + + cd customer_app/sdk_app_helloworld + make + +Build artifacts will be located in the ``build_out`` folder in each example. +Change into the output of the example you want to flash and ensure that the ``.bin`` file exists: + +.. code-block:: bash + + cd build_out + ls -la *.bin + +Connecting the Hardware +----------------------- + +Set the jumper on ``IO8`` to cover ``IO8`` and ``H`` (the jumper should be closest to the edge of the board). + +.. figure:: ../imgs/Pine64-BL602-EVB-ver-11.png + :alt: + + Pine64 BL602 EVB ver 1.1 board. ``IO8`` jumper, ``LED2``, the ``RESET`` button and the USB-C connection have been highlighted. + +Connect the board to the computer. +After connecting the board to the computer the ``RESET`` button can be used after changing the jumper setting to without repowering the device. + +.. _flashing-mac: + +Flashing +-------- + +Download the latest `blflash <https://github.com/spacemeowx2/blflash/releases>`_ version for macOS and ``chmod`` it to be executable: + +.. code-block:: bash + + chmod +x blflash* + +Invoke the ``blflash`` binary with the ``flash <project_name>.bin --port <port>`` arguments. + +You may get an error that says that ``blflash-macos-amd64`` can't be run because macOS can't verify it's free of malware, or that the identity of the developer can't be confirmed. To fix this, control-click on the downloaded ``blflash-macos-amd64`` executable in the Finder and ``Open`` from the context menu. You should now see the same warning again, but with an ``Open`` button. After clicking ``Open`` once, the warning should be cleared and ``blflash`` commands in Terminal should run from this point on. + +On macOS, the port should usually be ``/dev/tty.usbserial-1420``. +If in doubt, get a list of USB ports with ``ls -la /dev/ | grep usbserial``. + +.. code-block:: bash + + ./blflash-macos-amd64 flash sdk_app_helloworld.bin --port /dev/tty.usbserial-1420 + +If flashing is not successful ensure that: + +1. The device is connected to the computer correctly (red LED (``LED2``) should be lit). + +2. The ``IO8`` jumper is correctly set to cover the ``H`` position. Press ``RESET`` to make sure the jumper change is in effect. + +3. The ``sdk_app_helloworld.bin`` file exists and is correctly built at the correct location. + +4. The correct port is used. + +5. If attempting to flash something that is not the ``sdk_app_helloworld`` example, try flashing that first to ensure that the toolchain is working. + +Alternative Flashing Tools and Information +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +`mkroman <https://github.com/mkroman/awesome-bouffalo#rom-tools>`_ keeps a feature matrix of alternative flashing tools. + +`lupyuen <https://lupyuen.github.io/articles/pinecone#other-flashing-tools>`_ has an overview of alternative tools as well as an overview of the different components of the ROM. + +BouffaloLabDevCube +^^^^^^^^^^^^^^^^^^ + +**Note:** This section has not yet been fully tested. + +Bouffalo Lab has a macOS version of their own proprietary flashing program, but it does not always seem to run reliably. +It can be found at `their official site <https://dev.bouffalolab.com/download>`_. +If a login page is reached, click the button labeled ``Dev Zone``. + +Extract the ``.zip`` file and execute ``BLDevCube``. + +If Dev Cube launches on your Mac, then the Linux flashing instructions for Dev Cube at :ref:`devcube-flashing-linux` should work (with the appropriate macOS port name). More information can be found at :ref:`devcube-index`. + +Testing the output +------------------ + +Change the jumper on ``IO8`` to cover ``L`` and press the reset button. + +Download `CoolTerm <https://freeware.the-meiers.org/>`_. Use CoolTerm to connect using a baud rate of ``2000000`` (two million) and the same port used in :ref:`flashing-mac`. See `lupyuen's instructions <https://lupyuen.github.io/articles/flash#watch-the-firmware-run>`_ for a screenshot of the CoolTerm configuration. + +The terminal should be blank. +If you're being spammed with unknown symbols change jumper pin ``IO8`` to ``L`` and press ``RESET``. +After pressing ``RESET`` the following should be in the terminal: + +.. code-block:: bash + + [helloworld] start + [helloworld] helloworld + [helloworld] end + +The above should appear on the terminal every time ``RESET`` is pressed. + +Further information on the ``sdk_app_helloworld`` example can be found at :ref:`helloworld-index`. + diff --git a/src/en/index.rst b/src/en/index.rst index e731bca..95de33f 100644 --- a/src/en/index.rst +++ b/src/en/index.rst @@ -18,6 +18,7 @@ The microcontroller supports flashing and communication over `UART <https://en.w Quickstart_Guide/Linux/Quickstart_Linux_ubuntu Quickstart_Guide/Windows/Quickstart_Windows_msys Quickstart_Guide/Windows/Quickstart_Windows_wsl + Quickstart_Guide/Mac/Quickstart_macOS Quickstart_Guide/connecting_the_hardware .. toctree::