8000 docs/zephyr: Add quick reference for the Zephyr port. · micropython/micropython@333e165 · GitHub
[go: up one dir, main page]
Skip to content

Commit 333e165

Browse files
Julia-Hathawaydpgeorge
Julia-Hathaway
authored and
dpgeorge
committed
docs/zephyr: Add quick reference for the Zephyr port.
Includes an introduction to using the Zephyr port on MicroPython. The quickref details examples of how to use each module the port currently supports. The tutorial provides additional details for Zephyr specific modules. Signed-off-by: Julia Hathaway <julia.hathaway@nxp.com>
1 parent 42d1a16 commit 333e165

File tree

8 files changed

+403
-0
lines changed

8 files changed

+403
-0
lines changed

‎docs/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,3 +14,4 @@ MicroPython documentation and references
1414
rp2/quickref.rst
1515
wipy/quickref.rst
1616
unix/quickref.rst
17+
zephyr/quickref.rst

‎docs/zephyr/general.rst

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
.. _zephyr_general:
2+
3+
General information about the Zephyr port
4+
=========================================
5+
6+
The Zephyr Project is a Linux Foundation hosted Collaboration Project. It’s an open
7+
source collaborative effort uniting developers and users in building a
8+
small, scalable, real-time operating system (RTOS) optimized for resource-constrained
9+
devices, across multiple architectures.
10+
11+
Multitude of boards
12+
-------------------
13+
14+
There is a multitude of modules and boards from different sources that are supported
15+
by the Zephyr OS. All boards supported by Zephyr (with standard level of features
16+
support, like UART console) should work with MicroPython (but not all were tested).
17+
The FRDM-K64f board is taken as a reference board for the port for this documentation.
18+
If you have another board, please make sure you have a datasheet, schematics and other
19+
reference materials for your board handy to look up various aspects of your board
20+
functioning.
21+
22+
For a full list of Zephyr supported boards click `here (external link) <https://docs.zephyrproject.org/latest/boards/index.html#boards>`_

‎docs/zephyr/quickref.rst

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,157 @@
1+
.. _zephyr_quickref:
2+
3+
Quick reference for the Zephyr port
4+
===================================
5+
6+
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:
7+
8+
.. toctree::
9+
:maxdepth: 1
10+
11+
general.rst
12+
tutorial/index.rst
13+
14+
Running MicroPython
15+
-------------------
16+
17+
See the corresponding section of the tutorial: :ref:`intro`.
18+
19+
Delay and timing
20+
----------------
21+
22+
Use the :mod:`time <utime>` module::
23+
24+
import time
25+
26+
time.sleep(1) # sleep for 1 second
27+
time.sleep_ms(500) # sleep for 500 milliseconds
28+
time.sleep_us(10) # sleep for 10 microseconds
29+
start = time.ticks_ms() # get millisecond counter
30+
delta = time.ticks_diff(time.ticks_ms(), start) # compute time difference
31+
32+
Pins and GPIO
33+
-------------
34+
35+
Use the :ref:`machine.Pin <machine.Pin>` class::
36+
37+
from machine import Pin
38+
39+
pin = Pin(("GPIO_1", 21), Pin.IN) # create input pin on GPIO1
40+
print(pin) # print pin port and number
41+
42+
pin.init(Pin.OUT, Pin.PULL_UP, value=1) # reinitialize pin
43+
44+
pin.value(1) # set pin to high
45+
pin.value(0) # set pin to low
46+
47+
pin.on() # set pin to high
48+
pin.off() # set pin to low
49+
50+
pin = Pin(("GPIO_1", 21), Pin.IN) # create input pin on GPIO1
51+
52+
pin = Pin(("GPIO_1", 21), Pin.OUT, value=1) # set pin high on creation
53+
54+
pin = Pin(("GPIO_1", 21), Pin.IN, Pin.PULL_UP) # enable internal pull-up resistor
55+
56+
switch = Pin(("GPIO_2", 6), Pin.IN) # create input pin for a switch
57+
switch.irq(lambda t: print("SW2 changed")) # enable an interrupt when switch state is changed
58+
59+
Hardware I2C bus
60+
----------------
61+
62+
Hardware I2C is accessed via the :ref:`machine.I2C <machine.I2C>` class::
63+
64+
from machine import I2C
65+
66+
i2c = I2C("I2C_0") # construct an i2c bus
67+
print(i2c) # print device name
68+
69+
i2c.scan() # scan the device for available I2C slaves
70+
71+
i2c.readfrom(0x1D, 4) # read 4 bytes from slave 0x1D
72+
i2c.readfrom_mem(0x1D, 0x0D, 1) # read 1 byte from slave 0x1D at slave memory 0x0D
73+
74+
i2c.writeto(0x1D, b'abcd') # write to slave with address 0x1D
75+
i2c.writeto_mem(0x1D, 0x0D, b'ab') # write to slave 0x1D at slave memory 0x0D
76+
77+
buf = bytearray(8) # create buffer of size 8
78+
i2c.writeto(0x1D, b'abcd') # write buf to slave 0x1D
79+
80+
Hardware SPI bus
81+
----------------
82+
83+
Hardware SPI is accessed via the :ref:`machine.SPI <machine.SPI>` class::
84+
85+
from machine import SPI
86+
87+
spi = SPI("SPI_0") # construct a spi bus with default configuration
88+
spi.init(baudrate=100000, polarity=0, phase=0, bits=8, firstbit=SPI.MSB) # set configuration
89+
90+
# equivalently 10000 , construct spi bus and set configuration at the same time
91+
spi = SPI("SPI_0", baudrate=100000, polarity=0, phase=0, bits=8, firstbit=SPI.MSB)
92+
print(spi) # print device name and bus configuration
93+
94+
spi.read(4) # read 4 bytes on MISO
95+
spi.read(4, write=0xF) # read 4 bytes while writing 0xF on MOSI
96+
97+
buf = bytearray(8) # create a buffer of size 8
98+
spi.readinto(buf) # read into the buffer (reads number of bytes equal to the buffer size)
99+
spi.readinto(buf, 0xF) # read into the buffer while writing 0xF on MOSI
100+
101+
spi.write(b'abcd') # write 4 bytes on MOSI
102+
103+
buf = bytearray(4) # create buffer of size 8
104+
spi.write_readinto(b'abcd', buf) # write to MOSI and read from MISO into the buffer
105+
spi.write_readinto(buf, buf) # write buf to MOSI and read back into the buf
106+
107+
Disk Access
108+
-----------
109+
110+
Use the :ref:`zephyr.DiskAccess <zephyr.DiskAccess>` class to support filesystem::
111+
112+
import os
113+
from zephyr import DiskAccess
114+
115+
block_dev = DiskAccess('SDHC') # create a block device object for an SD card
116+
os.VfsFat.mkfs(block_dev) # create FAT filesystem object using the disk storage block
117+
os.mount(block_dev, '/sd') # mount the filesystem at the SD card subdirectory
118+
119+
# with the filesystem mounted, files can be manipulated as normal
120+
with open('/sd/hello.txt','w') as f: # open a new file in the directory
121+
f.write('Hello world') # write to the file
122+
print(open('/sd/hello.txt').read()) # print contents of the file
123+
124+
Flash Area
125+
----------
126+
127+
Use the :ref:`zephyr.FlashArea <zephyr.FlashArea>` class to support filesystem::
128+
129+
import os
130+
from zephyr import FlashArea
131+
132+
block_dev = FlashArea(4, 4096) # creates a block device object in the frdm-k64f flash scratch partition
133+
os.VfsLfs2.mkfs(block_dev) # create filesystem in lfs2 format using the flash block device
134+
os.mount(block_dev, '/flash') # mount the filesystem at the flash subdirectory
135+
136+
# with the filesystem mounted, files can be manipulated as normal
137+
with open('/flash/hello.txt','w') as f: # open a new file in the directory
138+
f.write('Hello world') # write to the file
139+
print(open('/flash/hello.txt').read()) # print contents of the file
140+
141+
Sensor
142+
------
143+
144+
Use the :ref:`zsensor.Sensor <zsensor.Sensor>` class to access sensor data::
145+
146+
import zsensor
147+
from zsensor import Sensor
148+
149+
accel = Sensor("FXOX8700") # create sensor object for the accelerometer
150+
151+
accel.measure() # obtain a measurement reading from the accelerometer
152+
153+
# each of these prints the value taken by measure()
154+
accel.float(zsensor.ACCEL_X) # print measurement value for accelerometer X-axis sensor channel as float
155+
accel.millis(zsensor.ACCEL_Y) # print measurement value for accelerometer Y-axis sensor channel in millionths
156+
accel.micro(zsensor.ACCEL_Z) # print measurement value for accelerometer Z-axis sensor channel in thousandths
157+
accel.int(zsensor.ACCEL_X) # print measurement integer value only for accelerometer X-axis sensor channel

‎docs/zephyr/tutorial/index.rst

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. _zephyr_tutorial:
2+
3+
MicroPython tutorial for the Zephyr port
4+
========================================
5+
6+
This tutorial is intended to get you started with the Zephyr port.
7+
8+
.. toctree::
9+
:maxdepth: 1
10+
:numbered:
11+
12+
intro.rst
13+
repl.rst
14+
storage.rst
15+
pins.rst
16+

‎docs/zephyr/tutorial/intro.rst

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
.. _intro_zephyr:
2+
3+
Getting started with MicroPython on the Zephyr port
4+
===================================================
5+
6+
Let’s get started!
7+
8+
Requirements
9+
------------
10+
11+
To use the MicroPython Zephyr port, you will need a Zephyr supported board (for a list of acceptable
12+
boards see :ref:`zephyr_general`).
13+
14+
Powering up
15+
-----------
16+
17+
If your board has a USB connector on it then most likely it is powered
18+
through this when connected to your PC. Otherwise you will need to power
19+
it directly. Please refer to the documentation for your board for
20+
further details.
21+
22+
Getting and deploying the firmware
23+
----------------------------------
24+
25+
The first step you will need to do is either clone the `MicroPython repository <https://github.com/micropython/micropython.git>`_
26+
or download it from the `MicroPython downloads page <http://micropython.org/download>`_. If you are an end user of MicroPython,
27+
it is recommended to start with the stable firmware builds. If you would like to work on development, you may follow the daily
28+
builds on git.
29+
30+
Next, follow the Zephyr port readme document (``ports/zephyr/README.md``) to build and run the application on your board.

‎docs/zephyr/tutorial/pins.rst

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
.. _pins_zephyr:
2+
3+
GPIO Pins
4+
=========
5+
6+
Use :ref:`machine.Pin <machine.Pin>` to control I/O pins.
7+
8+
For Zephyr, pins are initialized using a tuple of port and pin number ``(\"GPIO_x\", pin#)``
9+
for the ``id`` value. For example to initialize a pin for the red LED on a FRDM-k64 board::
10+
11+
LED = Pin(("GPIO_1", 22), Pin.OUT)
12+
13+
Reference your board's datasheet or Zephyr documentation for pin numbers, see below for more examples.
14+
15+
.. list-table:: Pin Formatting
16+
:header-rows: 1
17+
18+
* - Board
19+
- Pin
20+
- Format
21+
* - frdm_k64f
22+
- Red LED = PTB22
23+
- ("GPIO_1", 22)
24+
* - 96b_carbon
25+
- LED1 = PD2
26+
- ("GPIOD", 2)
27+
* - mimxrt685_evk_cm33
28+
- Green LED = PIO0_14
29+
- ("GPIO0", 14)
30+
31+
Interrupts
32+
----------
33+
34+
The Zephyr port also supports interrupt handling for Pins using `machine.Pin.irq() <machine.Pin.irq>`.
35+
To respond to Pin change IRQs run::
36+
37+
from machine import Pin
38+
39+
SW2 = Pin(("GPIO_2", 6), Pin.IN) # create Pin object for switch 2
40+
SW3 = Pin(("GPIO_0", 4), Pin.IN) # create Pin object for switch 3
41+
42+
SW2.irq(lambda t: print("SW2 changed")) # print message when SW2 state is changed (triggers change IRQ)
43+
SW3.irq(lambda t: print("SW3 changed")) # print message when SW3 state is changed (triggers change IRQ)
44+
45+
while True: # wait
46+
pass

‎docs/zephyr/tutorial/repl.rst

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
Getting a MicroPython REPL prompt
2+
=================================
3+
4+
REPL stands for Read Evaluate Print Loop, and is the name given to the
5+
interactive MicroPython prompt that you can access on your board through
6+
Zephyr. It is recommended to use REPL to test out your code and run commands.
7+
8+
REPL over the serial port
9+
-------------------------
10+
11+
The REPL is available on a UART serial peripheral specified for the board by
12+
the ``zephyr,console`` devicetree node. The baudrate of the REPL is 115200.
13+
If your board has a USB-serial convertor on it then you should be able to access
14+
the REPL directly from your PC.
15+
16+
To access the prompt over USB-serial you will need to use a terminal emulator
17+
program. For a Linux or Mac machine, open a terminal and run::
18+
19+
screen /dev/ttyACM0 115200
20+
21+
You can also try ``picocom`` or ``minicom`` instead of screen. You may have to use
22+
``/dev/ttyACM1`` or a higher number for ``ttyACM``. Additional permissions
23+
may be necessary to access this device (eg group ``uucp`` or ``dialout``, or use sudo).
24+
For Windows, get a terminal software, such as puTTY and connect via a serial session
25+
using the proper COM port.
26+
27+
Using the REPL
28+
--------------
29+
30+
With your serial program open (PuTTY, screen, picocom, etc) you may see a
31+
blank screen with a flashing cursor. Press Enter (or reset the board) and
32+
you should be presented with the following text::
33+
34+
*** Booting Zephyr OS build v2.6.0-rc1-416-g3056c5ec30ad ***
35+
MicroPython v2.6.0-rc1-416-g3056c5ec30 on 2021-06-24; zephyr-frdm_k64f with mk64f12
36+
Type "help()" for more information.
37+
>>>
38+
39+
Now you can try running MicroPython code directly on your board.
40+
41+
Anything you type at the prompt, indicated by ``>>>``, will be executed after you press
42+
the Enter key. If there is an error with the text that you enter then an error
43+
message is printed.
44+
45+
Start by typing the following at the prompt to make sure it is working::
46+
47+
>>> print("hello world!")
48+
hello world!
49+
50+
If you already know some python you can now try some basic commands here. For
51+
example::
52+
53+
>>> 1 + 2
54+
3
55+
>>> 1 / 2
56+
0.5
57+
>>> 3 * 'Zephyr'
58+
ZephyrZephyrZephyr
59+
60+
If your board has an LED, you can blink it using the following code::
61+
62+
>>>import time
63+
>>>from machine import Pin
64+
65+
>>>LED = Pin(("GPIO_1", 21), Pin.OUT)
66+
>>>while True:
67+
... LED.value(1)
68+
... time.sleep(0.5)
69+
... LED.value(0)
70+
... time.sleep(0.5)
71+
72+
The above code uses an LED location for a FRDM-K64F board (port B, pin 21;
73+
following Zephyr conventions ports are identified by "GPIO_x", where *x*
74+
starts from 0). You will need to adjust it for another board using the board's
75+
reference materials.

0 commit comments

Comments
 (0)
0