diff --git a/docs/library/index.rst b/docs/library/index.rst index 2536e8dc9..5fd4a8f77 100644 --- a/docs/library/index.rst +++ b/docs/library/index.rst @@ -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 diff --git a/docs/library/zephyr.DiskAccess.rst b/docs/library/zephyr.DiskAccess.rst new file mode 100644 index 000000000..d19d81a96 --- /dev/null +++ b/docs/library/zephyr.DiskAccess.rst @@ -0,0 +1,38 @@ +.. currentmodule:: zephyr +.. _zephyr.DiskAccess: + +class DiskAccess -- access to disk storage +========================================== + +Uses `Zephyr Disk Access API `_. + +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 ` defined by + :class:`uos.AbstractBlockDev`. + diff --git a/docs/library/zephyr.FlashArea.rst b/docs/library/zephyr.FlashArea.rst new file mode 100644 index 000000000..306347d44 --- /dev/null +++ b/docs/library/zephyr.FlashArea.rst @@ -0,0 +1,40 @@ +.. currentmodule:: zephyr +.. _zephyr.FlashArea: + +class FlashArea -- access to built-in flash storage +=================================================== + +Uses `Zephyr flash map API `_. + +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 ` defined by + :class:`uos.AbstractBlockDev`. diff --git a/docs/library/zephyr.rst b/docs/library/zephyr.rst new file mode 100644 index 000000000..da3d14a09 --- /dev/null +++ b/docs/library/zephyr.rst @@ -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 + `_. + +.. 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 `_. + +Classes +------- + +.. toctree:: + :maxdepth: 1 + + zephyr.DiskAccess.rst + zephyr.FlashArea.rst + +Additional Modules +------------------ + +.. toctree:: + :maxdepth: 1 + + zephyr.zsensor.rst diff --git a/docs/library/zephyr.zsensor.rst b/docs/library/zephyr.zsensor.rst new file mode 100644 index 000000000..4eadc926d --- /dev/null +++ b/docs/library/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 +`_. + +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.