mirrors/micropython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs/library/zephyr: Add libraries specific to the Zephyr port.

Browse Source 
Includes documentation for Zephyr specific modules (zephyr and zsensor),
classes (DiskAccess and FlashArea), and functions.

Signed-off-by: Julia Hathaway <julia.hathaway@nxp.com>
This commit is contained in:
Julia Hathaway 2021-08-02 17:08:00 -05:00 committed by Damien George
parent 333e16521b
commit 6ed6990625
5 changed files with 271 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/library/index.rst
View File

@ -176,3 +176,13 @@ The following libraries are specific to the RP2040, as used in the Raspberry Pi
:maxdepth: 2 :maxdepth: 2
rp2.rst rp2.rst
Libraries specific to Zephyr
----------------------------
The following libraries are specific to the Zephyr port.
.. toctree::
:maxdepth: 2
zephyr.rst

38
docs/library/zephyr.DiskAccess.rst Normal file
View File

@ -0,0 +1,38 @@
.. currentmodule:: zephyr
.. _zephyr.DiskAccess:
class DiskAccess -- access to disk storage
==========================================
Uses `Zephyr Disk Access API <https://docs.zephyrproject.org/latest/reference/storage/disk/access.html>`_.
This class allows access to storage devices on the board, such as support for SD card controllers and
interfacing with SD cards via SPI. Disk devices are automatically detected and initialized on boot using
Zephyr devicetree data.
The Zephyr disk access class enables the transfer of data between a disk device and an accessible memory buffer given a disk name,
buffer, starting disk block, and number of sectors to read. MicroPython reads as many blocks as necessary to fill the buffer, so
the number of sectors to read is found by dividing the buffer length by block size of the disk.
Constructors
------------
.. class:: DiskAccess(disk_name)
Gets an object for accessing disk memory of the specific disk.
For accessing an SD card on the mimxrt1050_evk, ``disk_name`` would be ``SDHC``. See board documentation and
devicetree for usable disk names for your board (ex. RT boards use style USDHC#).
Methods
-------
.. method:: DiskAccess.readblocks(block_num, buf)
DiskAccess.readblocks(block_num, buf, offset)
.. method:: DiskAccess.writeblocks(block_num, buf)
DiskAccess.writeblocks(block_num, buf, offset)
.. method:: DiskAccess.ioctl(cmd, arg)
These methods implement the simple and extended
:ref:`block protocol <block-device-interface>` defined by
:class:`uos.AbstractBlockDev`.

40
docs/library/zephyr.FlashArea.rst Normal file
View File

@ -0,0 +1,40 @@
.. currentmodule:: zephyr
.. _zephyr.FlashArea:
class FlashArea -- access to built-in flash storage
===================================================
Uses `Zephyr flash map API <https://docs.zephyrproject.org/latest/reference/storage/flash_map/flash_map.html#flash-map>`_.
This class allows access to device flash partition data.
Flash area structs consist of a globally unique ID number, the name of the flash device the partition is in,
the start offset (expressed in relation to the flash memory beginning address per partition),
and the size of the partition that the device represents. For fixed flash partitions, data from the device
tree is used; however, fixed flash partitioning is not enforced in MicroPython because MCUBoot is not enabled.
Constructors
------------
.. class:: FlashArea(id, block_size)
Gets an object for accessing flash memory at partition specified by ``id`` and with block size of ``block_size``.
``id`` values are integers correlating to fixed flash partitions defined in the devicetree.
A commonly used partition is the designated flash storage area defined as ``FlashArea.STORAGE`` if
``FLASH_AREA_LABEL_EXISTS(storage)`` returns true at boot.
Zephyr devicetree fixed flash partitions are ``boot_partition``, ``slot0_partition``, ``slot1_partition``, and
``scratch_partition``. Because MCUBoot is not enabled by default for MicroPython, these fixed partitions can be accessed by
ID integer values 1, 2, 3, and 4, respectively.
Methods
-------
.. method:: FlashArea.readblocks(block_num, buf)
FlashArea.readblocks(block_num, buf, offset)
.. method:: FlashArea.writeblocks(block_num, buf)
FlashArea.writeblocks(block_num, buf, offset)
.. method:: FlashArea.ioctl(cmd, arg)
These methods implement the simple and extended
:ref:`block protocol <block-device-interface>` defined by
:class:`uos.AbstractBlockDev`.

60
docs/library/zephyr.rst Normal file
View File

@ -0,0 +1,60 @@
.. currentmodule:: zephyr
:mod:`zephyr` --- functionality specific to the Zephyr port
===========================================================
.. module:: zephyr
:synopsis: functionality specific to Zephyr
The ``zephyr`` module contains functions and classes specific to the Zephyr port.
Functions
---------
.. function:: is_preempt_thread()
Returns true if the current thread is a preemptible thread.
Zephyr preemptible threads are those with non-negative priority values (low priority levels), which therefore,
can be supplanted as soon as a higher or equal priority thread becomes ready.
.. function:: current_tid()
Returns the thread id of the current thread, which is used to reference the thread.
.. function:: thread_analyze()
Runs the Zephyr debug thread analyzer on the current thread and prints stack size statistics in the format:
"``thread_name``-20s: STACK: unused ``available_stack_space`` usage ``stack_space_used``
/ ``stack_size`` (``percent_stack_space_used`` %); CPU: ``cpu_utilization`` %"
* *CPU utilization is only printed if runtime statistics are configured via the ``CONFIG_THREAD_RUNTIME_STATS`` kconfig*
This function can only be accessed if ``CONFIG_THREAD_ANALYZER`` is configured for the port in ``zephyr/prj.conf``.
For more infomation, see documentation for Zephyr `thread analyzer
<https://docs.zephyrproject.org/latest/guides/debug_tools/thread-analyzer.html#thread-analyzer>`_.
.. function:: shell_exec(cmd_in)
Executes the given command on an UART backend. This function can only be accessed if ``CONFIG_SHELL_BACKEND_SERIAL``
is configured for the port in ``zephyr/prj.conf``.
A list of possible commands can be found in the documentation for Zephyr `shell commands <https://docs.zephyrproject.org/latest/reference/shell/index.html?highlight=shell_execute_cmd#commands>`_.
Classes
-------
.. toctree::
:maxdepth: 1
zephyr.DiskAccess.rst
zephyr.FlashArea.rst
Additional Modules
------------------
.. toctree::
:maxdepth: 1
zephyr.zsensor.rst

123
docs/library/zephyr.zsensor.rst Normal file
View File

@ -0,0 +1,123 @@
.. currentmodule:: zsensor
:mod:`zsensor` --- Zephyr sensor bindings
=========================================
.. module:: zsensor
:synopsis: zephyr sensor bindings
The ``zsensor`` module contains a class for using sensors with Zephyr.
.. _zsensor.Sensor:
class Sensor --- sensor control for the Zephyr port
---------------------------------------------------
Use this class to access data from sensors on your board.
See Zephyr documentation for sensor usage here: `Sensors
<https://docs.zephyrproject.org/latest/reference/peripherals/sensor.html?highlight=sensor#sensors>`_.
Sensors are defined in the Zephyr devicetree for each board. The quantities that a given sensor can
measure are called a sensor channels. Sensors can have multiple channels to represent different axes
of one property or different properties a sensor can measure. See `Channels`_ below for defined sensor
channels.
Constructor
~~~~~~~~~~~
.. class:: Sensor(device_name)
Device names are defined in the devicetree for your board.
For example, the device name for the accelerometer in the FRDM-k64f board is "FXOS8700".
Methods
~~~~~~~
.. method:: Sensor.measure()
Obtains a measurement sample from the sensor device using Zephyr sensor_sample_fetch and
stores it in an internal driver buffer as a useful value, a pair of (integer part of value,
fractional part of value in 1-millionths).
Returns none if successful or OSError value if failure.
.. method:: Sensor.get_float(sensor_channel)
Returns the value of the sensor measurement sample as a float.
.. method:: Sensor.get_micros(sensor_channel)
Returns the value of the sensor measurement sample in millionths.
(Ex. value of ``(1, 500000)`` returns as ``1500000``)
.. method:: Sensor.get_millis(sensor_channel)
Returns the value of sensor measurement sample in thousandths.
(Ex. value of ``(1, 500000)`` returns as ``1500``)
.. method:: Sensor.get_int(sensor_channel)
Returns only the integer value of the measurement sample.
(Ex. value of ``(1, 500000)`` returns as ``1``)
Channels
~~~~~~~~
.. data:: ACCEL_X
Acceleration on the X axis, in m/s^2.
.. data:: ACCEL_Y
Acceleration on the Y axis, in m/s^2.
.. data:: ACCEL_Z
Acceleration on the Z axis, in m/s^2.
.. data:: GYRO_X
Angular velocity around the X axis, in radians/s.
.. data:: GYRO_Y
Angular velocity around the Y axis, in radians/s.
.. data:: GYRO_Z
Angular velocity around the Z axis, in radians/s.
.. data:: MAGN_X
Magnetic field on the X axis, in Gauss.
.. data:: MAGN_Y
Magnetic field on the Y axis, in Gauss.
.. data:: MAGN_Z
Magnetic field on the Z axis, in Gauss.
.. data:: DIE_TEMP
Device die temperature in degrees Celsius.
.. data:: PRESS
Pressure in kilopascal.
.. data:: PROX
Proximity. Dimensionless. A value of 1 indicates that an object is close.
.. data:: HUMIDITY
Humidity, in percent.
.. data:: LIGHT
Illuminance in visible spectrum, in lux.
.. data:: ALTITUDE
Altitude, in meters.