diff --git a/cats.rst b/cats.rst new file mode 100644 index 0000000000000000000000000000000000000000..a573db217347d65973d79060a94cd00c87061849 --- /dev/null +++ b/cats.rst @@ -0,0 +1,207 @@ +.. SPDX-FileCopyrightText: Huawei Inc. +.. +.. SPDX-License-Identifier: CC-BY-4.0 + +.. include:: ./definitions.rst + +############## +CATS Blueprint +############## + +.. contents:: + :depth: 4 + +******** +Overview +******** + +The CATS (Context Aware Touch Screen) Blueprint provides support for touch screen which responds +to tapped buttons on it and sends further signal. + +************ +The Hardware +************ + +Needed components +================= + +..TODO + +************ +The Software +************ + +Get sources +=========== +#. + Get |main_project_name| sources as described in the :ref:`blueprints workspace documentation <Workspace>`. + For this specific build, you need to + clone `meta-oniro-blueprints-doorlock <https://gitlab.eclipse.org/eclipse/oniro-blueprints/doorlock/meta-oniro-blueprints-doorlock>`_. + + .. code-block:: bash + + $ cd $CHECKOUT_DIR + $ git clone --recursive https://gitlab.eclipse.org/eclipse/oniro-blueprints/core/meta-oniro-blueprints-core.git + $ git clone --recursive git@gitlab.eclipse.org:eclipse/oniro-blueprints/context-aware-touch-screen/meta-oniro-blueprints-cats.git + $ cd meta-oniro-blueprints-cats + $ git checkout brgl/cats-linux + +.. note:: + + Make sure you define or replace + `CHECKOUT_DIR` as described in :ref:`blueprints workspace documentation <Workspace>`. + +#. + If you already have sources cloned, update them to the most recent revision + +.. code-block:: bash + + user@pc:~/oniroproject$ repo sync -d + +Also, update the `meta-oniro-blueprint` git checkout. + +Build the software +================== +#. To build the image for this blueprint, you need to set the corresponding distro in the conf/local.conf file or on the command line as seen below: + + .. code-block:: bash + + $ TEMPLATECONF=../oniro/flavours/zephyr . ./oe-core/oe-init-build-env build-oniro-doorlock + +#. Add the `meta-oniro-blueprints-doorlock`` & `meta-oniro-blueprints-core` layers to the build. + + This is only needed once after initializing a new build. + + .. code-block:: bash + + $ bitbake-layers add-layer $CHECKOUT_DIR/meta-oniro-blueprints-core + $ bitbake-layers add-layer $CHECKOUT_DIR/meta-oniro-blueprints-cats + + +#. Start building the image + + .. code-block:: bash + + DISTRO=oniro-linux-blueprint-cats MACHINE=raspberrypi4-64 bitbake blueprint-cats-image + +Flash the software when built with bitbake +========================================== +#. After building the image, prepare the board by connecting the board's USB port to your computer and putting the board into flashing mode by double-pressing the reset button. +#. Use `BOSSA <https://github.com/arduino/BOSSA>`_ to flash the image to the board. You can build BOSSA from source (use the nrf branch), or you can try a prebuilt version of BOSSA for many Linux distributions in `The Oniro Project OBS repository <https://build.opensuse.org/repositories/home:oniroproject:tools>`_. If you're using OpenMandriva, you can ``dnf install bossa`` from the distribution's repositories. +#. You also need the python serial module (which may or may not be installed in your distribution by default). Most if not all Linux distributions have a package for this module, typically called python-serial or python3-serial. Use the distribution's package manager to install this package. +#. Flash the door lock software to the board: + + .. code-block:: bash + + $ DISTRO="oniro-zephyr-blueprint-doorlock" MACHINE=arduino-nano-33-ble bitbake zephyr-blueprint-doorlock -c flash_usb + +Alternative way of building the software (using west) +===================================================== +#. You can also use Zephyr's build system to build the image, e.g. to try working with a git snapshot of the Zephyr OS. To do that (assuming you have the Zephyr toolset, consisting of west and the Zephyr SDK, installed): + + .. code-block:: bash + + $ mkdir doorlock + $ cd doorlock + $ west init --mr v2.7.0 + $ west update + $ git clone https://gitlab.eclipse.org/eclipse/oniro-blueprints/doorlock/doorlock-zephyr.git + $ west build -p auto -b arduino_nano_33_ble doorlock-zephyr + +Flashing the software when built with west +========================================== +#. After building the image, prepare the board by connecting the board's USB port to your computer and putting the board into flashing mode by double-pressing the reset button. +#. Use `BOSSA <https://github.com/arduino/BOSSA>`_ to flash the image to the board. You can build BOSSA from source (use the nrf branch), or you can try a prebuilt version of BOSSA for many Linux distributions in `The Oniro Project OBS repository <https://build.opensuse.org/repositories/home:oniroproject:tools>`_. If you're using OpenMandriva, you can ``dnf install bossa`` from the distribution's repositories. +#. If BOSSA is not provided for your distribution, use: + + .. code-block:: bash + + $ git clone -b nrf https://github.com/arduino/BOSSA + $ cd BOSSA + $ make bossac + $ sudo cp bin/bossac /usr/local/bin # (or any other place in your PATH) + +#. Use BOSSA to flash the software + + .. code-block:: bash + + $ bossac -p ttyACM0 -R -e -w -v -b build/zephyr/zephyr.bin + +.. note:: + You may need to replace `ttyACM0`. + + +Resources +========= + +.. _ResourcesDL: + +- See `Door lock's requirement <https://git.ostc-eu.org/OSTC/requirements/-/issues/12>`_ + +.. + We probably have to move those requirement to gitlab.eclipse + +******************* +Using the door lock +******************* + +Initial setup +============= +After initial flashing, you get to select the pin that will unlock the lock. +The red LED on the Arduino board flashes quickly while waiting for your new pin. + +Setting a pin +============= +You can use any combination of keys, including pressing multiple keys simultaneously. +Enter the pin you would like to use, and finish by holding the "*" key and pressing "#". +For example, if you want to use pin 1 23 4 (where 3 has to be pressed while 2 is still being held down), press and release 1, press and hold 2, press 3, release 2 and 3, press and release 4, press and hold * , press #, release * and #. + +Driving the lock +================ +Simply enter your pin using the matrix keypad to unlock the lock. + +Changing the pin +================ +Within 10 seconds of entering your pin to unlock the lock, hold the "*" key and press "#". +At this point, the red LED on the board will flash quickly, and you can enter a new pin +as described in "Setting a pin". + +Forgotten pin +============= +There is no "master key". If you've forgotten your pin, flash the separate `factory reset app <https://gitlab.eclipse.org/eclipse/oniro-blueprints/doorlock/doorlock-factoryreset>`_, boot it, then reflash the doorlock app. + +Build the factory reset firmware +================================ +#. Make sure you have the Zephyr toolset, consisting of west and the Zephyr SDK, installed, then run: + + .. code-block:: bash + + $ mkdir doorlock-factoryreset + $ cd doorlock-factoryreset + $ west init --mr v2.7.0 + $ west update + $ git clone https://gitlab.eclipse.org/eclipse/oniro-blueprints/doorlock/doorlock-factoryreset.git + $ west build -p auto -b arduino_nano_33_ble doorlock-factoryreset + +Flashing the factory reset firmware +=================================== +#. After building the image, prepare the board by connecting the board's USB port to your computer and putting the board into flashing mode by double-pressing the reset button. +#. Use `BOSSA <https://github.com/arduino/BOSSA>`_ to flash the image to the board. You can build BOSSA from source (use the nrf branch), or you can try a prebuilt version of BOSSA for many Linux distributions in `The Oniro Project OBS repository <https://build.opensuse.org/repositories/home:oniroproject:tools>`_. If you're using OpenMandriva, you can ``dnf install bossa`` from the distribution's repositories. +#. If BOSSA is not provided for your distribution, use: + + .. code-block:: bash + + $ git clone -b nrf https://github.com/arduino/BOSSA + $ cd BOSSA + $ make bossac + $ sudo cp bin/bossac /usr/local/bin # (or any other place in your PATH) + +#. Use BOSSA to flash the software + + .. code-block:: bash + + $ bossac -p ttyACM0 -R -e -w -v -b build/zephyr/zephyr.bin + +.. note:: + You may need to replace `ttyACM0`. + \ No newline at end of file