diff options
| -rw-r--r-- | docs/index.rst | 1 | ||||
| -rw-r--r-- | docs/zephyr/general.rst | 22 | ||||
| -rw-r--r-- | docs/zephyr/quickref.rst | 157 | ||||
| -rw-r--r-- | docs/zephyr/tutorial/index.rst | 16 | ||||
| -rw-r--r-- | docs/zephyr/tutorial/intro.rst | 30 | ||||
| -rw-r--r-- | docs/zephyr/tutorial/pins.rst | 46 | ||||
| -rw-r--r-- | docs/zephyr/tutorial/repl.rst | 75 | ||||
| -rw-r--r-- | docs/zephyr/tutorial/storage.rst | 56 |
8 files changed, 403 insertions, 0 deletions
diff --git a/docs/index.rst b/docs/index.rst index 58552daf5..a97bff1c8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,3 +14,4 @@ MicroPython documentation and references rp2/quickref.rst wipy/quickref.rst unix/quickref.rst + zephyr/quickref.rst diff --git a/docs/zephyr/general.rst b/docs/zephyr/general.rst new file mode 100644 index 000000000..362f03ada --- /dev/null +++ b/docs/zephyr/general.rst @@ -0,0 +1,22 @@ +.. _zephyr_general: + +General information about the Zephyr port +========================================= + +The Zephyr Project is a Linux Foundation hosted Collaboration Project. It’s an open +source collaborative effort uniting developers and users in building a +small, scalable, real-time operating system (RTOS) optimized for resource-constrained +devices, across multiple architectures. + +Multitude of boards +------------------- + +There is a multitude of modules and boards from different sources that are supported +by the Zephyr OS. All boards supported by Zephyr (with standard level of features +support, like UART console) should work with MicroPython (but not all were tested). +The FRDM-K64f board is taken as a reference board for the port for this documentation. +If you have another board, please make sure you have a datasheet, schematics and other +reference materials for your board handy to look up various aspects of your board +functioning. + +For a full list of Zephyr supported boards click `here (external link) <https://docs.zephyrproject.org/latest/boards/index.html#boards>`_ diff --git a/docs/zephyr/quickref.rst b/docs/zephyr/quickref.rst new file mode 100644 index 000000000..783621316 --- /dev/null +++ b/docs/zephyr/quickref.rst @@ -0,0 +1,157 @@ +.. _zephyr_quickref: + +Quick reference for the Zephyr port +=================================== + +Below is a quick reference for the Zephyr port. If it is your first time working with this port please consider reading the following sections first: + +.. toctree:: + :maxdepth: 1 + + general.rst + tutorial/index.rst + +Running MicroPython +------------------- + +See the corresponding section of the tutorial: :ref:`intro`. + +Delay and timing +---------------- + +Use the :mod:`time <utime>` module:: + + import time + + time.sleep(1) # sleep for 1 second + time.sleep_ms(500) # sleep for 500 milliseconds + time.sleep_us(10) # sleep for 10 microseconds + start = time.ticks_ms() # get millisecond counter + delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference + +Pins and GPIO +------------- + +Use the :ref:`machine.Pin <machine.Pin>` class:: + + from machine import Pin + + pin = Pin(("GPIO_1", 21), Pin.IN) # create input pin on GPIO1 + print(pin) # print pin port and number + + pin.init(Pin.OUT, Pin.PULL_UP, value=1) # reinitialize pin + + pin.value(1) # set pin to high + pin.value(0) # set pin to low + + pin.on() # set pin to high + pin.off() # set pin to low + + pin = Pin(("GPIO_1", 21), Pin.IN) # create input pin on GPIO1 + + pin = Pin(("GPIO_1", 21), Pin.OUT, value=1) # set pin high on creation + + pin = Pin(("GPIO_1", 21), Pin.IN, Pin.PULL_UP) # enable internal pull-up resistor + + switch = Pin(("GPIO_2", 6), Pin.IN) # create input pin for a switch + switch.irq(lambda t: print("SW2 changed")) # enable an interrupt when switch state is changed + +Hardware I2C bus +---------------- + +Hardware I2C is accessed via the :ref:`machine.I2C <machine.I2C>` class:: + + from machine import I2C + + i2c = I2C("I2C_0") # construct an i2c bus + print(i2c) # print device name + + i2c.scan() # scan the device for available I2C slaves + + i2c.readfrom(0x1D, 4) # read 4 bytes from slave 0x1D + i2c.readfrom_mem(0x1D, 0x0D, 1) # read 1 byte from slave 0x1D at slave memory 0x0D + + i2c.writeto(0x1D, b'abcd') # write to slave with address 0x1D + i2c.writeto_mem(0x1D, 0x0D, b'ab') # write to slave 0x1D at slave memory 0x0D + + buf = bytearray(8) # create buffer of size 8 + i2c.writeto(0x1D, b'abcd') # write buf to slave 0x1D + +Hardware SPI bus +---------------- + +Hardware SPI is accessed via the :ref:`machine.SPI <machine.SPI>` class:: + + from machine import SPI + + spi = SPI("SPI_0") # construct a spi bus with default configuration + spi.init(baudrate=100000, polarity=0, phase=0, bits=8, firstbit=SPI.MSB) # set configuration + + # equivalently, construct spi bus and set configuration at the same time + spi = SPI("SPI_0", baudrate=100000, polarity=0, phase=0, bits=8, firstbit=SPI.MSB) + print(spi) # print device name and bus configuration + + spi.read(4) # read 4 bytes on MISO + spi.read(4, write=0xF) # read 4 bytes while writing 0xF on MOSI + + buf = bytearray(8) # create a buffer of size 8 + spi.readinto(buf) # read into the buffer (reads number of bytes equal to the buffer size) + spi.readinto(buf, 0xF) # read into the buffer while writing 0xF on MOSI + + spi.write(b'abcd') # write 4 bytes on MOSI + + buf = bytearray(4) # create buffer of size 8 + spi.write_readinto(b'abcd', buf) # write to MOSI and read from MISO into the buffer + spi.write_readinto(buf, buf) # write buf to MOSI and read back into the buf + +Disk Access +----------- + +Use the :ref:`zephyr.DiskAccess <zephyr.DiskAccess>` class to support filesystem:: + + import os + from zephyr import DiskAccess + + block_dev = DiskAccess('SDHC') # create a block device object for an SD card + os.VfsFat.mkfs(block_dev) # create FAT filesystem object using the disk storage block + os.mount(block_dev, '/sd') # mount the filesystem at the SD card subdirectory + + # with the filesystem mounted, files can be manipulated as normal + with open('/sd/hello.txt','w') as f: # open a new file in the directory + f.write('Hello world') # write to the file + print(open('/sd/hello.txt').read()) # print contents of the file + +Flash Area +---------- + +Use the :ref:`zephyr.FlashArea <zephyr.FlashArea>` class to support filesystem:: + + import os + from zephyr import FlashArea + + block_dev = FlashArea(4, 4096) # creates a block device object in the frdm-k64f flash scratch partition + os.VfsLfs2.mkfs(block_dev) # create filesystem in lfs2 format using the flash block device + os.mount(block_dev, '/flash') # mount the filesystem at the flash subdirectory + + # with the filesystem mounted, files can be manipulated as normal + with open('/flash/hello.txt','w') as f: # open a new file in the directory + f.write('Hello world') # write to the file + print(open('/flash/hello.txt').read()) # print contents of the file + +Sensor +------ + +Use the :ref:`zsensor.Sensor <zsensor.Sensor>` class to access sensor data:: + + import zsensor + from zsensor import Sensor + + accel = Sensor("FXOX8700") # create sensor object for the accelerometer + + accel.measure() # obtain a measurement reading from the accelerometer + + # each of these prints the value taken by measure() + accel.float(zsensor.ACCEL_X) # print measurement value for accelerometer X-axis sensor channel as float + accel.millis(zsensor.ACCEL_Y) # print measurement value for accelerometer Y-axis sensor channel in millionths + accel.micro(zsensor.ACCEL_Z) # print measurement value for accelerometer Z-axis sensor channel in thousandths + accel.int(zsensor.ACCEL_X) # print measurement integer value only for accelerometer X-axis sensor channel diff --git a/docs/zephyr/tutorial/index.rst b/docs/zephyr/tutorial/index.rst new file mode 100644 index 000000000..218156b3b --- /dev/null +++ b/docs/zephyr/tutorial/index.rst @@ -0,0 +1,16 @@ +.. _zephyr_tutorial: + +MicroPython tutorial for the Zephyr port +======================================== + +This tutorial is intended to get you started with the Zephyr port. + +.. toctree:: + :maxdepth: 1 + :numbered: + + intro.rst + repl.rst + storage.rst + pins.rst + diff --git a/docs/zephyr/tutorial/intro.rst b/docs/zephyr/tutorial/intro.rst new file mode 100644 index 000000000..ffdbea8b3 --- /dev/null +++ b/docs/zephyr/tutorial/intro.rst @@ -0,0 +1,30 @@ +.. _intro_zephyr: + +Getting started with MicroPython on the Zephyr port +=================================================== + +Let’s get started! + +Requirements +------------ + +To use the MicroPython Zephyr port, you will need a Zephyr supported board (for a list of acceptable +boards see :ref:`zephyr_general`). + +Powering up +----------- + +If your board has a USB connector on it then most likely it is powered +through this when connected to your PC. Otherwise you will need to power +it directly. Please refer to the documentation for your board for +further details. + +Getting and deploying the firmware +---------------------------------- + +The first step you will need to do is either clone the `MicroPython repository <https://github.com/micropython/micropython.git>`_ +or download it from the `MicroPython downloads page <http://micropython.org/download>`_. If you are an end user of MicroPython, +it is recommended to start with the stable firmware builds. If you would like to work on development, you may follow the daily +builds on git. + +Next, follow the Zephyr port readme document (``ports/zephyr/README.md``) to build and run the application on your board. diff --git a/docs/zephyr/tutorial/pins.rst b/docs/zephyr/tutorial/pins.rst new file mode 100644 index 000000000..8e1d6602a --- /dev/null +++ b/docs/zephyr/tutorial/pins.rst @@ -0,0 +1,46 @@ +.. _pins_zephyr: + +GPIO Pins +========= + +Use :ref:`machine.Pin <machine.Pin>` to control I/O pins. + +For Zephyr, pins are initialized using a tuple of port and pin number ``(\"GPIO_x\", pin#)`` +for the ``id`` value. For example to initialize a pin for the red LED on a FRDM-k64 board:: + + LED = Pin(("GPIO_1", 22), Pin.OUT) + +Reference your board's datasheet or Zephyr documentation for pin numbers, see below for more examples. + +.. list-table:: Pin Formatting + :header-rows: 1 + + * - Board + - Pin + - Format + * - frdm_k64f + - Red LED = PTB22 + - ("GPIO_1", 22) + * - 96b_carbon + - LED1 = PD2 + - ("GPIOD", 2) + * - mimxrt685_evk_cm33 + - Green LED = PIO0_14 + - ("GPIO0", 14) + +Interrupts +---------- + +The Zephyr port also supports interrupt handling for Pins using `machine.Pin.irq() <machine.Pin.irq>`. +To respond to Pin change IRQs run:: + + from machine import Pin + + SW2 = Pin(("GPIO_2", 6), Pin.IN) # create Pin object for switch 2 + SW3 = Pin(("GPIO_0", 4), Pin.IN) # create Pin object for switch 3 + + SW2.irq(lambda t: print("SW2 changed")) # print message when SW2 state is changed (triggers change IRQ) + SW3.irq(lambda t: print("SW3 changed")) # print message when SW3 state is changed (triggers change IRQ) + + while True: # wait + pass diff --git a/docs/zephyr/tutorial/repl.rst b/docs/zephyr/tutorial/repl.rst new file mode 100644 index 000000000..a7e8955d0 --- /dev/null +++ b/docs/zephyr/tutorial/repl.rst @@ -0,0 +1,75 @@ +Getting a MicroPython REPL prompt +================================= + +REPL stands for Read Evaluate Print Loop, and is the name given to the +interactive MicroPython prompt that you can access on your board through +Zephyr. It is recommended to use REPL to test out your code and run commands. + +REPL over the serial port +------------------------- + +The REPL is available on a UART serial peripheral specified for the board by +the ``zephyr,console`` devicetree node. The baudrate of the REPL is 115200. +If your board has a USB-serial convertor on it then you should be able to access +the REPL directly from your PC. + +To access the prompt over USB-serial you will need to use a terminal emulator +program. For a Linux or Mac machine, open a terminal and run:: + + screen /dev/ttyACM0 115200 + +You can also try ``picocom`` or ``minicom`` instead of screen. You may have to use +``/dev/ttyACM1`` or a higher number for ``ttyACM``. Additional permissions +may be necessary to access this device (eg group ``uucp`` or ``dialout``, or use sudo). +For Windows, get a terminal software, such as puTTY and connect via a serial session +using the proper COM port. + +Using the REPL +-------------- + +With your serial program open (PuTTY, screen, picocom, etc) you may see a +blank screen with a flashing cursor. Press Enter (or reset the board) and +you should be presented with the following text:: + + *** Booting Zephyr OS build v2.6.0-rc1-416-g3056c5ec30ad *** + MicroPython v2.6.0-rc1-416-g3056c5ec30 on 2021-06-24; zephyr-frdm_k64f with mk64f12 + Type "help()" for more information. + >>> + +Now you can try running MicroPython code directly on your board. + +Anything you type at the prompt, indicated by ``>>>``, will be executed after you press +the Enter key. If there is an error with the text that you enter then an error +message is printed. + +Start by typing the following at the prompt to make sure it is working:: + + >>> print("hello world!") + hello world! + +If you already know some python you can now try some basic commands here. For +example:: + + >>> 1 + 2 + 3 + >>> 1 / 2 + 0.5 + >>> 3 * 'Zephyr' + ZephyrZephyrZephyr + +If your board has an LED, you can blink it using the following code:: + + >>>import time + >>>from machine import Pin + + >>>LED = Pin(("GPIO_1", 21), Pin.OUT) + >>>while True: + ... LED.value(1) + ... time.sleep(0.5) + ... LED.value(0) + ... time.sleep(0.5) + +The above code uses an LED location for a FRDM-K64F board (port B, pin 21; +following Zephyr conventions ports are identified by "GPIO_x", where *x* +starts from 0). You will need to adjust it for another board using the board's +reference materials. diff --git a/docs/zephyr/tutorial/storage.rst b/docs/zephyr/tutorial/storage.rst new file mode 100644 index 000000000..f57a08fc4 --- /dev/null +++ b/docs/zephyr/tutorial/storage.rst @@ -0,0 +1,56 @@ +.. _storage_zephyr: + +Filesystems and Storage +======================= + +Storage modules support virtual filesystem with FAT and littlefs formats, backed by either +Zephyr DiskAccess or FlashArea (flash map) APIs depending on which the board supports. + +See `uos Filesystem Mounting <https://docs.micropython.org/en/latest/library/uos.html?highlight=os#filesystem-mounting>`_. + +Disk Access +----------- + +The :ref:`zephyr.DiskAccess <zephyr.DiskAccess>` class can be used to access storage devices, such as SD cards. +This class uses `Zephyr Disk Access API <https://docs.zephyrproject.org/latest/reference/storage/disk/access.html>`_ and +implements the `uos.AbstractBlockDev` protocol. + +For use with SD card controllers, SD cards must be present at boot & not removed; they will +be auto detected and initialized by filesystem at boot. Use the disk driver interface and a +file system to access SD cards via disk access (see below). + +Example usage of FatFS with an SD card on the mimxrt1050_evk board:: + + import os + from zephyr import DiskAccess + bdev = zephyr.DiskAccess('SDHC') # create block device object using DiskAccess + os.VfsFat.mkfs(bdev) # create FAT filesystem object using the disk storage block + os.mount(bdev, '/sd') # mount the filesystem at the SD card subdirectory + with open('/sd/hello.txt','w') as f: # open a new file in the directory + f.write('Hello world') # write to the file + print(open('/sd/hello.txt').read()) # print contents of the file + + +Flash Area +---------- + +The :ref:`zephyr.FlashArea <zephyr.FlashArea>` class can be used to implement a low-level storage system or +customize filesystem configurations. To store persistent data on the device, using a higher-level filesystem +API is recommended (see below). + +This class uses `Zephyr Flash map API <https://docs.zephyrproject.org/latest/reference/storage/flash_map/flash_map.html#>`_ and +implements the `uos.AbstractBlockDev` protocol. + +Example usage with the internal flash on the reel_board or the rv32m1_vega_ri5cy board:: + + import os + from zephyr import FlashArea + bdev = FlashArea(FlashArea.STORAGE, 4096) # create block device object using FlashArea + os.VfsLfs2.mkfs(bdev) # create Little filesystem object using the flash area block + os.mount(bdev, '/flash') # mount the filesystem at the flash storage subdirectory + with open('/flash/hello.txt','w') as f: # open a new file in the directory + f.write('Hello world') # write to the file + print(open('/flash/hello.txt').read()) # print contents of the file + +For boards such as the frdm_k64f in which the MicroPython application spills into the default flash storage +partition, use the scratch partition by replacing ``FlashArea.STORAGE`` with the integer value 4. |