docs/library/zephyr: Add libraries specific to the Zephyr port.
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:
parent
333e16521b
commit
6ed6990625
|
@ -176,3 +176,13 @@ The following libraries are specific to the RP2040, as used in the Raspberry Pi
|
|||
:maxdepth: 2
|
||||
|
||||
rp2.rst
|
||||
|
||||
Libraries specific to Zephyr
|
||||
----------------------------
|
||||
|
||||
The following libraries are specific to the Zephyr port.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
zephyr.rst
|
||||
|
|
|
@ -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`.
|
||||
|
|
@ -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`.
|
|
@ -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
|
|
@ -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.
|
Loading…
Reference in New Issue