docs/renesas-ra: Add renesas-ra docs files.

Signed-off-by: Takeo Takahashi <takeo.takahashi.xv@renesas.com>

8 files changed, 292 insertions, 0 deletions

diff --git a/docs/renesas-ra/tutorial/img/ek_ra6m2_how_to_connect.jpg b/docs/renesas-ra/tutorial/img/ek_ra6m2_how_to_connect.jpg
new file mode 100644
index 000000000..3457e102f
--- /dev/null
+++ b/docs/renesas-ra/tutorial/img/ek_ra6m2_how_to_connect.jpg
diff --git a/docs/renesas-ra/tutorial/img/ra4m1_clicker_how_to_connect.jpg b/docs/renesas-ra/tutorial/img/ra4m1_clicker_how_to_connect.jpg
new file mode 100644
index 000000000..a37e9c8bc
--- /dev/null
+++ b/docs/renesas-ra/tutorial/img/ra4m1_clicker_how_to_connect.jpg
diff --git a/docs/renesas-ra/tutorial/index.rst b/docs/renesas-ra/tutorial/index.rst
new file mode 100644
index 000000000..bde8307b5
--- /dev/null
+++ b/docs/renesas-ra/tutorial/index.rst
@@ -0,0 +1,16 @@
+.. _renesas-ra_tutorial:
+
+MicroPython tutorial for Renesas RA port
+========================================
+
+This tutorial is intended to get you started using MicroPython on the Renesas RA port.
+
+.. toctree::
+   :maxdepth: 1
+   :numbered:
+
+   intro.rst
+   using_peripheral.rst
+   program_in_flash.rst
+   reset.rst
+   troubleshooting.rst
diff --git a/docs/renesas-ra/tutorial/intro.rst b/docs/renesas-ra/tutorial/intro.rst
new file mode 100644
index 000000000..6c41f4397
--- /dev/null
+++ b/docs/renesas-ra/tutorial/intro.rst
@@ -0,0 +1,67 @@
+.. _renesas-ra_intro:
+
+Getting started with MicroPython on the Renesas RA
+==================================================
+
+This tutorial will guide you through setting up MicroPython,
+getting a prompt, using the hardware peripherals, using internal
+flash file system, reset and boot modes, and Factory reset the
+internal file system.
+
+Requirements
+------------
+
+You need a board. For the information of available boards,
+please refer to the general information about Renesas RA port: :ref:`renesas-ra_general`.
+
+You need a USB-Serial conversion cable to connect the board and your PC.
+Please get a type with separate signal pins so that you can connect to
+the UART TX and RX pins on the board.
+
+Flashing the MicroPython image with J-Link OB
+---------------------------------------------
+
+The board has a builtin programmer interface called J-Link OB.
+Using the J-Link Software, you can flash the binary image "firmware.hex"
+of MicroPython on the board via J-Link OB.
+
+You can download the J-Link Software and Documentation pack from https://www.segger.com/downloads/jlink/.
+
+After installing J-Link Software, start J-Flash-Lite program.  Then specify following device in Device select menu in J-Flash-Lite.
+
+===============  ================
+    Board             Device
+---------------  ----------------
+ EK-RA4M1           R7FA4M1AB
+ EK-RA4W1         R7FA4W1AD2CNG
+ EK-RA6M1           R7FA6M1AD
+ EK-RA6M2           R7FA6M2AF
+ RA4M1 CLICKER      R7FA4M1AB
+===============  ================
+
+Select a firmware hex file in Data File of J-Link-Lite, and push Program Device button to flash the firmware.
+
+Getting a prompt of MicroPython
+-------------------------------
+
+Cross connect USB-Serial conversion cable RX/TX/GND pins to TX/RX/GND pins on the board.
+
+===============  ===============  ===============
+     Board        USB Serial RX    USB Serial TX
+---------------  ---------------  ---------------
+ EK-RA4M1             P411             P410
+ EK-RA4W1             P205             P206
+ EK-RA6M1             P411             P410
+ EK-RA6M2             P411             P410
+ RA4M1 CLICKER        P401             P402
+===============  ===============  ===============
+
+Access the MicroPython REPL (the Python prompt) via USB serial or UART with 115200 baud rate, 1 stop bit and no parity bit using your favorite terminal software, picocom on Linux or Tera Term on Windows.  You can try on Linux::
+
+      $ picocom /dev/ttyACM0
+
+You can see the MicroPython REPL prompt like below::
+
+   MicroPython v1.18-293-g339aa09b8-dirty on 2022-03-26; RA6M2_EK with RA6M2
+   Type "help()" for more information.
+   >>>
diff --git a/docs/renesas-ra/tutorial/program_in_flash.rst b/docs/renesas-ra/tutorial/program_in_flash.rst
new file mode 100644
index 000000000..ec276a612
--- /dev/null
+++ b/docs/renesas-ra/tutorial/program_in_flash.rst
@@ -0,0 +1,62 @@
+.. _renesas-ra_program_in_flash:
+
+Write a program in internal file system
+=======================================
+
+Internal file system
+--------------------
+
+The FAT file system is created and initialized in the RA MCU's internal
+flash when the MicroPython starts at the first time on the board.
+The file system is mounted as "/flash", so you can access this flash system
+and create a program file into the /flash directory.
+
+As the factory setting, following size is allocated for the file system:
+
+===============  ===================
+    Board         File System Size
+---------------  -------------------
+ EK-RA4M1           36KB ( 36864B)
+ EK-RA4W1           64KB ( 65536B)
+ EK-RA6M1          128KB (131072B)
+ EK-RA6M2          256KB (262144B)
+ RA4M1 CLICKER      36KB ( 36864B)
+===============  ===================
+
+As the factory setting, following 2 files are created in the file system:
+
+* boot.py : executed first when the system starts
+* main.py : executed after boot.py completes
+
+Write a program in the internal file system
+-------------------------------------------
+
+You can write a program in main.py which is executed automatically
+when the MicroPython starts. For example, you can write LED blinking
+program like below::
+
+    import os
+    os.getcwd()
+    f = open('main.py', 'rw+')
+    print(f.read())
+    f.write('import time\n')
+    f.write('from machine import Pin\n')
+    f.write('led1 = Pin(Pin.cpu.P106)\n')
+    f.write('while True:\n')
+    f.write('    led1.on()\n')
+    f.write('    time.sleep(1)\n')
+    f.write('    led1.off()\n')
+    f.write('    time.sleep(1)\n')
+    f.close()
+    f = open('main.py', 'r')
+    print(f.read())
+    f.close()
+
+Entering CTRL-D for software reset, the MicroPython reboots, displays
+following messages::
+
+    MPY: sync filesystems
+    MPY: soft reboot
+
+and main.py is executed and LED1 blinks per 1 second.
+If you want to stop the program, please enter CTRL-C.
diff --git a/docs/renesas-ra/tutorial/reset.rst b/docs/renesas-ra/tutorial/reset.rst
new file mode 100644
index 000000000..de5f4db91
--- /dev/null
+++ b/docs/renesas-ra/tutorial/reset.rst
@@ -0,0 +1,61 @@
+.. _renesas-ra_reset:
+
+Reset and boot mode
+===================
+
+Resetting the board
+-------------------
+
+If something goes wrong, you can reset the board in two ways. The first is
+to press CTRL-D at the MicroPython prompt, which performs a soft reset.
+You will see a message something like ::
+
+    MPY: sync filesystems
+    MPY: soft reboot
+    MicroPython v1.18-293-g339aa09b8-dirty on 2022-03-26; RA6M2_EK with RA6M2
+    Type "help()" for more information.
+    >>>
+
+If that isn't working you can perform a hard reset (turn-it-off-and-on-again)
+by pressing the RESET button. This will end your session, disconnecting
+whatever program (PuTTY, screen, etc) that you used to connect to the board.
+
+boot mode
+---------
+
+There are 3 boot modes:
+
+  * normal boot mode
+  * safe boot mode
+  * factory filesystem boot mode
+
+boot.py and main.py are executed on "normal boot mode".
+
+boot.py and main.py are *NOT* executed on "safe boot mode".
+
+The file system of internal flash is initialized and *all files are erased* on "factory filesystem boot mode".
+
+For changing boot mode, please push the RESET button with pressing USER SW1
+on the board:
+
+  * For normal boot mode, release the USER SW1 after LED1 flashes 4 times or more
+
+  * For safe boot mode, release the USER SW1 after LED1 flashes 2 times
+
+  * For factory file system boot mode, release the USER SW1 after LED1 flashes 3 times.
+
+You have created the main.py which executes LED1 blinking in the previous part.
+If you change the boot mode to safe boot mode, the MicroPython starts without
+the execution of main.py. Then you can remove the main.py by following
+command or change the boot mode to factory file system boot mode.::
+
+    import os
+    os.remove('main.py')
+
+or change the boot mode to factory file system boot mode.
+
+You can confirm that the initialized file system that there are only boot.py and main.py files.::
+
+    import os
+    os.listdir()
+
diff --git a/docs/renesas-ra/tutorial/troubleshooting.rst b/docs/renesas-ra/tutorial/troubleshooting.rst
new file mode 100644
index 000000000..8837d2349
--- /dev/null
+++ b/docs/renesas-ra/tutorial/troubleshooting.rst
@@ -0,0 +1,18 @@
+.. _renesas-ra_troubleshooting:
+
+Trouble Shooting
+===================
+
+Flash file system
+-------------------
+
+* MicroPython REPL prompt is not displayed.
+
+  - Re-program the MicroPython image file.
+
+  - Confirm serial port connection.
+    The connection must be crossed that the board TXD pin is connected with
+    USB-serial conversion's RXD signal pin.
+
+  - If the prompt is not displayed suddenly, try to do factory file
+    system boot mode as the final method.  Please note that all files are removed forever.
diff --git a/docs/renesas-ra/tutorial/using_peripheral.rst b/docs/renesas-ra/tutorial/using_peripheral.rst
new file mode 100644
index 000000000..c50181b3d
--- /dev/null
+++ b/docs/renesas-ra/tutorial/using_peripheral.rst
@@ -0,0 +1,68 @@
+.. _renesas-ra_using_peripheral:
+
+Using peripherals
+=================
+
+For quick help information, please enter::
+
+    help()
+
+You can access RA MCU's peripherals using MicroPython modules.
+To list supported modules, please enter::
+
+    help('modules')
+
+Especially `machine` module and class :ref:`machine.Pin <machine.Pin>` are very important for using
+peripherals. Note that prefix 'u' is added to the module for MicroPython,
+so you can see "umachine" in the list but you can use it like "import machine".
+
+Using "from machine import Pin", Pin name is available corresponding to
+the RA MCU's pin name which are Pin.cpu.P000 and 'P000'.
+In addition, you can use 'LED1', 'LED2', 'SW1', and 'SW2' name if the board
+has these LEDs and switches.
+
+LED blinking
+------------
+
+As simple example, you can enter following program to blink LED1.
+Please enter key 4 times after the input of last time.sleep(1). ::
+
+    import time
+    from machine import Pin
+    led1 = Pin('LED1')
+    print(led1)
+    while True:
+        led1.on()
+        time.sleep(1)
+        led1.off()
+        time.sleep(1)
+
+You can see the LED1 blinking per 1 second.
+
+If you want to stop the program, please enter CTRL-C. ::
+
+    Traceback (most recent call last):
+      File "<stdin>", line 5, in <module>
+    KeyboardInterrupt:
+
+This message is displayed, and the program stops.
+The message means the program was interrupted at line 5 "while" statement.
+
+Using print(led1), you can confirm that LED1 is assigned to Pin.cpu.P106
+on the board.::
+
+     Pin(Pin.cpu.P106, mode=Pin.OUT, pull=Pin.PULL_NONE, drive=Pin.LOW_POWER)
+
+So you can get the same result if Pin(Pin.cpu.P106) is specified
+instead of Pin('LED1'). ::
+
+    import time
+    from machine import Pin
+    led1 = Pin(Pin.cpu.P106)
+    print(led1)
+    while True:
+        led1.on()
+        time.sleep(1)
+        led1.off()
+        time.sleep(1)
+