boards/beagleplay/05-demos.rst

@@ -178,6 +178,7 @@ Demos and tutorials
     demos-and-tutorials/using-grove
     demos-and-tutorials/using-mikrobus
     demos-and-tutorials/using-qwiic
+    demos-and-tutorials/using-nodered
     demos-and-tutorials/using-rtc
     demos-and-tutorials/using-oldi
     demos-and-tutorials/using-csi
@@ -185,4 +186,4 @@ Demos and tutorials
     demos-and-tutorials/beagleplay-kernel-development
     demos-and-tutorials/greybus-host
     demos-and-tutorials/understanding-boot
-    demos-and-tutorials/using-nodered
+    demos-and-tutorials/low-power-video-doorbell

boards/beaglev/fire/05-demos.rst

@@ -22,6 +22,7 @@ Demos
     demos-and-tutorials/gateware/gateware-full-flow
     demos-and-tutorials/gateware/gateware-tcl-scripts-structure
     demos-and-tutorials/gateware/customize-cape-gateware-verilog
+    demos-and-tutorials/gateware/deploy-and-program-picorv-softcore
     demos-and-tutorials/gateware/running-the-bitstream-builder-on-windows
     demos-and-tutorials/gateware/exploring-gateware-design-libero
     demos-and-tutorials/gateware/gateware-design-simulation-libero

boards/beaglev/fire/demos-and-tutorials/gateware/deploy-and-program-picorv-softcore.rst

+.. _beaglev-fire-softcore-usage:
+
+How to use PicoRV Softcore on BeagleV-Fire
+##########################################
+
+Introduction
+************
+
+The PicoRV Softcore is a 32-bit RISC-V CPU subsystem on the BeagleV-Fire's FPGA fabric, functionally equivalent to the PRU subsystem on the BeagleBone Black. 
+The core is designed for low-latency I/O operations and offloading smaller tasks like PWM, LEDS, etc .
+
+Prerequisites
+*************
+
+To be able to use the softcore component, you'll need to have following packages installed on your host computer:
+
+- gcc-riscv64-unknown-elf
+- picolibc-riscv64-unknown-elf
+
+.. note::
+
+    These packages are used for compiling the code for the softcore.
+
+For debian-based systems like ubuntu, you can use following commands:
+
+.. code-block:: console
+
+    sudo apt install gcc-riscv64-unknown-elf picolibc-riscv64-unknown-elf
+
+If you are using any other linux distro these packages can be downloaded from respective package managers.
+But, it is highly recommended to use docker for accurate results.
+
+`Docker installation steps <https://docs.docker.com/engine/install>`_.
+
+Once you have docker installed:
+
+1. Start a container with ubuntu image.
+2. Install the required toolchain using above mentioned command (remember not to use 'sudo' in docker).
+
+.. code-block:: console
+
+    Sudo docker run -it ubuntu:latest
+
+After installing the necessary tools, you are all set for using the Softcore. 
+
+How to use the Softcore
+***********************
+
+1. Boot the softcore with firmware
+==================================
+
+Step 1
+------
+
+Navigate to ``sources/FPGA-design/script_support/components/SOFTCORE/PICO_RISCV/firmware`` in the BeagleV-Fire repository.
+
+Step 2
+------
+
+Edit the firmware.c file by adding your code in the main function. You can create your own custom file but remember to use firmware.h file for pre-defined functions to access gpios.
+
+Step 3
+------
+
+Now run the ``generatehex.sh`` to compile the code. (remember to edit the file name in the script of you are using custom file)
+
+.. code-block:: console
+
+    . ./generatehex.sh
+
+If you are using docker clone the repository on your docker container or use docker copy, then compile the program and use docker copy to obtain the hex file.
+
+To copy file from local system to docker container:
+
+.. code-block:: console
+
+    docker cp ./path/to/file CONTAINER:/path/to/directory
+
+To copy file from docker container to local system:
+
+.. code-block:: console
+
+    docker cp CONTAINER:/path/to/file /path/to/directory
+
+To check the name of docker 'CONTAINER':
+
+.. code-block:: console 
+
+    docker ps -a
+
+This will list all the running and stopped containers
+To restart a stopped container, use:
+
+.. code-block:: console
+
+    sudo docker start name_of_container -i 
+
+Step 4
+------
+
+Select PicoRV build option for bitstream generation
+
+Once the code is compiled, build the bitstream using the 'build-bitstream.py' script.
+
+.. code-block:: console
+
+    python build-bitstream.py ./build-options/picorv-softcore.yaml 
+
+.. note::
+
+    The Gitlab CI does not support the softcore code compilation yet, so the bitstream must be generated locally.
+
+Step 5
+------
+
+Program BeagleV-Fire With Your `Custom Bitstream <https://docs.beagleboard.org/boards/beaglev/fire/demos-and-tutorials/gateware/customize-cape-gateware-verilog.html>`_.
+
+
+2. Programming the softcore in run-time
+=======================================
+
+Step 1
+------
+
+- Program the softcore with custom bitstream with picorv-softcore build-option.
+- Follow the steps mentioned in previous section.
+
+Step 2
+------
+
+- Edit and compile your new code in your local machine.(BeagleV-Fire does not support on-board compilation for softcore programs yet, this feature will be added soon.)
+- Follow Steps 2 and 3 in previous section for compiling your new program.
+
+Step 3
+------
+
+Copy the firmware directory from BeagleV-Fire repository to your board.
+
+.. code-block:: console
+
+    sudo scp -r path/to/firmware beagle@192.168.7.2:/home/beagle 
+
+Step 4
+------
+
+- Overwritting softcore's program memory.
+- Compile the 'AXI_test.c' file using gcc and execute it.
+
+.. code-block:: console
+
+    gcc -o AXI_test AXI_test.c
+    sudo ./AXI_teste 
+
+
+- This will open a interactive menu with various option that you can try out and access the program memory of the softcore.
+- Here we will select *option 2* to upload the hex file we just compiled to the softcore.
+
+.. note::
+
+    This compilation in step 2 is to generate a hex file to program the Softcore, while the compilation in Step 3 is performed to command the Linux system on-board to access the program memory of the Softcore.
+
+.. note::
+    
+    The filename in **AXI_test.c** for the hex file is set as ``firmware.hex``, so make sure the name of the hex file you compiled is the same else change the filename pointer in **AXI_test.c**.
+
+Repository
+==========
+
+`PicoRV softcore builder <https://openbeagle.org/gsoc/2024/riscv-io-core/>`_.

boards/beagley/ai/01-introduction.rst

@@ -96,7 +96,7 @@ Board components location
 Front components
 =================
 
-.. figure:: images/components-location/front.*
+.. figure:: images/components-location/beagley-ai-board-front-annotated.*
     :width: 1400
     :align: center
     :alt: BeagleY-AI board front components location 
@@ -143,7 +143,7 @@ Front components
 Back components
 ================
 
-.. figure:: images/components-location/back.*
+.. figure:: images/components-location/beagley-ai-board-back-annotated.*
     :width: 1400
     :align: center
     :alt: BeagleY-AI board back components location 

boards/beagley/ai/05-demos.rst

@@ -6,8 +6,6 @@ Demos and tutorials
 .. toctree::
    :maxdepth: 1
 
-.. todo:: Isn't including "beagley-ai" in the filename superfluous?
-
    demos/beagley-ai-using-gpio
    demos/beagley-ai-using-pwm
    demos/beagley-ai-using-rtc

boards/capes/index.rst

@@ -49,7 +49,8 @@ Find the instructions below on using each cape:
    :maxdepth: 2
    :hidden:
 
-   /boards/capes/cape-interface-spec
-   /boards/capes/relay
-   /boards/capes/comms
+   cape-interface-spec
+   relay
+   comms
+   motor_cape
 

boards/pocketbeagle-2/01-introduction.rst

@@ -67,7 +67,7 @@ description of the major components and interfaces that make up the board.
    +=========================+=========================================================================================================================================+
    | **Processor**           | `Texas Instruments AM6232 <https://www.ti.com/product/AM623>`_                                                                          |
    +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
-   | **SDRAM Memory**        | LPDDR4 3200MHz (512MB) Kingston D2516AN9EXGXN-TU                                                                                        |
+   | **SDRAM Memory**        | 512MB DDR4 (Kingston D2516AN9EXGXN-TU)                                                                                                  |
    +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
    | **PMIC**                | TPS6521903                                                                                                                              |
    +-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+

boards/pocketbeagle-2/02-quick-start.rst

@@ -92,26 +92,193 @@ Once the flashing is done, you will see the following screen.
 
 Your microSD card is now ready to boot PocketBeagle 2.
 
-Methods of operation
-*********************
-
-1.  Directly tethered to a PC via USB-C port.
-2.  With TechLab Cape for sesors, USB host, LEDs and Buttons.
-
-.. todo:: add link to TechLab Cape
-
 .. _pocketbeagle-2-main-connection-scenarios:
 
 Main Connection Scenarios
-============================
+*************************
 
 This section describes how to connect and power the board and serves as a slightly more detailed 
-description of the Quick Start Guide included in the box. The board can be configured in several 
+description of the quick start guide included in the box. The board can be configured in several 
 different ways, but we will discuss the two most common scenarios.
 
-* Tethered to a PC via the USB cable  
-* Attached to a cape like TechLab Cape
+1.  Directly tethered to a PC via pocketbeagle 2 USB-C port.
+2.  With `TechLab Cape <https://www.beagleboard.org/boards/techlab>`_ or `GamePup Cape <https://www.beagleboard.org/boards/pocketbeagle-gamepup-cape>`_  for sensors, USB host, LEDs and Buttons.
+
+.. _pocketbeagle-2-tethered-scenario:
+
+Tethered Connection
+====================
+
+In this scenario, the board is directly connected to a PC via USB-C port. This is the simplest way to get started with the board.
+Optionally you can connect rpi debug probe to 3-pin JST-SH connector to see boot log, board console access and for general debugging.
+
+
+.. figure:: images/connection-diagrams/tethered-connection.*
+   :align: center
+   :alt: Tethered Connection
+
+   Tethered Connection
+
+USB connection
+---------------
+
+1. Connect the USB-C cable to the PocketBeagle 2 and the other end to the PC.
+2. The board will power up and boot from the microSD card.
+3. The board will show up as a USB device on the PC.
+4. You can access the board via ``SSH`` or board ``serial`` connection or though ``Visial Studio Code Server`` web interface.
+
+.. tab-set::
+   .. tab-item:: Visial Studio Code Server
+
+      After connecting the board to the PC, you can access the board via a web browser by entering the IP address of the board in the address bar.
+
+      .. code-block:: text
+
+         https://192.168.7.2:3000/
+
+      .. figure:: images/misc/vscode-server.png
+         :align: center
+         :alt: Visual Studio Code Server
+
+         Visual Studio Code Server
+
+   .. tab-item:: SSH
+
+      After connecting the board to the PC, you can access the board via SSH executing the following command in your terminal.
+
+      .. code-block:: bash
+
+         ssh <username>@192.168.7.2
+
+      Where ``<username>`` is the username you selected during the microSD card flashing process.
+
+      .. figure:: images/misc/ssh-connection.png
+         :align: center
+         :alt: SSH connection
+
+         SSH connection
+
+   .. tab-item:: Serial
+
+      PocketBeagle 2 has a built-in UART debug connection. You can connect to the board console using a serial 
+      console application (e.g. Putty) on the PC just like your would connection using any external UART debug probe
+
+      If PocketBeagle 2 is the old device connected with UART, on linux you can use `tio` utility, replace ``ttyACMx`` with the actual device name.
+
+      .. code-block:: bash
+
+         tio /dev/ttyACMx
+
+      .. figure:: images/misc/serial-connection.png
+         :align: center
+         :alt: Serial connection
+
+         Serial connection
+
+Once you have access to the console using any of the methods above, you might want to share interne connection with the board.
+You can do this by running ``pb2-internet.sh`` file on your PocketBeagle 2 board. and the follow OS specific steps to share internet connection.
+
+First you have to create ``pb2-internet.sh`` file on PocketBeagle 2 with the following content,
+
+.. code-block:: bash
+
+   #!/bin/sh -e
+   #
+
+   if ! id | grep -q root; then
+           echo "must be run as root"
+           exit
+   fi
+
+   if [ -f /etc/default/bb-boot ] ; then
+           . /etc/default/bb-boot
+   fi
+
+   if [ "x${USB_CONFIGURATION}" = "x" ] ; then
+           USB0_SUBNET=192.168.7
+           DNS_NAMESERVER=8.8.8.8
+   fi
+
+   /sbin/route add default gw ${USB0_SUBNET}.1 || true
+
+   ping -c1 ${DNS_NAMESERVER}
+   echo "nameserver ${DNS_NAMESERVER}" >> /etc/resolv.conf
+
+   #
+
+then execute following commands,
+
+.. code-block:: bash
+
+   chmod +x pb2-internet.sh
+   sudo ./pb2-internet.sh
+
+On PC you have to follow OS specific steps to share internet connection with the board.
+
+.. tab-set::
+
+   .. tab-item:: Linux
+
+      First you have to identify your WiFi interface name and PocketBeagle 2 Ethernet interface name using following command,
+
+      .. code-block:: bash
+
+         ip a
+
+      If you have your WiFi connected to router and PB2 connected to one of the USB the you should see four interfaces listed
+
+      - 1: lo
+      - 2: wlp0s20f3
+      - 3: enp0s20f0u2
+      - 4: enp0s20f0u2i2
+
+      Out of which ``wlp0s20f3`` is the WiFi interface and ``enp0s20f0u2`` is the PocketBeagle 2 Ethernet interface. 
+      
+      Once you know the interface names, you have to create ``pc-internet.sh`` file on PC with the following content,
+
+      .. code-block:: bash
+
+         sudo sysctl net.ipv4.ip_forward=1
+         sudo iptables --table nat --append POSTROUTING --out-interface wlp0s20f3 -j MASQUERADE
+         sudo iptables --append FORWARD --in-interface enp0s20f0u1 -j ACCEPT
+
+      make sure to update line 2 and 3 with your WiFi and PocketBeagle 2 Ethernet interface names. Then execute following commands,
+
+      .. code-block:: bash
+
+         chmod +x pc-internet.sh
+         sudo ./pc-internet.sh
+
+   .. tab-item:: Windows
+
+      .. todo:: Add steps to share internet connection on Windows
+
+   .. tab-item:: MacOS
+
+      .. todo:: Add steps to share internet connection on MacOS
+
+UART serial debug connection
+----------------------------
+
+1. Connect the rpi debug probe to the 3-pin JST-SH connector on the board.
+2. Connect the other end of the probe to the PC.
+3. Use command line utility like `tio` with default setting or a serial console application (e.g. Putty) to accress your board.
+4. You will see the boot log and can access the board console.
+
+.. figure:: images/misc/serial-debug.png
+   :align: center
+   :alt: Serial debug
+
+   Serial debug
+
+.. _pocketbeagle-2-cape-scenario:
+
+Cape Connection
+================
 
-.. todo:: Add connection information in detail
+In this scenario, the board is connected to a cape like `TechLab Cape <https://www.beagleboard.org/boards/techlab>`_ 
+or `GamePup Cape <https://www.beagleboard.org/boards/pocketbeagle-gamepup-cape>`_. This is the most common way to 
+use the board for sensor interfacing, USB host, LEDs and Buttons. 
 
+.. todo:: Add cape connection diagram and steps to use examples.