diff options
Diffstat (limited to 'docs/renesas-ra/tutorial')
| -rw-r--r-- | docs/renesas-ra/tutorial/img/ek_ra6m2_how_to_connect.jpg | bin | 0 -> 120872 bytes | |||
| -rw-r--r-- | docs/renesas-ra/tutorial/img/ra4m1_clicker_how_to_connect.jpg | bin | 0 -> 106133 bytes | |||
| -rw-r--r-- | docs/renesas-ra/tutorial/index.rst | 16 | ||||
| -rw-r--r-- | docs/renesas-ra/tutorial/intro.rst | 67 | ||||
| -rw-r--r-- | docs/renesas-ra/tutorial/program_in_flash.rst | 62 | ||||
| -rw-r--r-- | docs/renesas-ra/tutorial/reset.rst | 61 | ||||
| -rw-r--r-- | docs/renesas-ra/tutorial/troubleshooting.rst | 18 | ||||
| -rw-r--r-- | docs/renesas-ra/tutorial/using_peripheral.rst | 68 |
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 Binary files differnew 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 Binary files differnew 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) + |
