mirror of
https://github.com/apache/nuttx.git
synced 2026-05-28 03:45:50 +08:00
Documentation: update nxscope doc
update various nxscope doc Signed-off-by: raiden00pl <raiden00@railab.me>
This commit is contained in:
raiden00pl
Xiang Xiao
@@ -2,4 +2,84 @@
|
||||
``nxscope`` NxScope library example
|
||||
===================================
|
||||
|
||||
TODO
|
||||
The ``nxscope`` example demonstrates the basic usage of the NxScope
|
||||
library for real-time data streaming.
|
||||
|
||||
See :doc:`/applications/logging/nxscope/index` for more details about
|
||||
the NxScope library and host-side tools.
|
||||
|
||||
This application initializes a set of example channels and starts a thread
|
||||
that generates various waveforms (sine waves, counters, etc.) to be streamed
|
||||
to a host client.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
To use this example, enable ``CONFIG_EXAMPLES_NXSCOPE=y``. The available
|
||||
configuration options depend on the interface selected in the ``nxscope``
|
||||
configuration.
|
||||
|
||||
Common Options
|
||||
--------------
|
||||
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_STREAMBUF_LEN``: NxScope stream buffer size.
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_RXBUF_LEN``: NxScope RX buffer size.
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_MAIN_INTERVAL``: Main loop interval in microseconds.
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_FORCE_ENABLE``: Automatically enable all channels
|
||||
and start streaming on startup.
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_CHARLOG``: Demonstrate sending text messages over
|
||||
a dedicated channel (channel 19).
|
||||
|
||||
Serial Interface Options
|
||||
------------------------
|
||||
|
||||
These options are available when ``CONFIG_LOGGING_NXSCOPE_INTF_SERIAL=y``:
|
||||
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_SERIAL_PATH``: Device path (e.g. ``/dev/ttyUSB0``).
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_SERIAL_BAUD``: Baud rate for the serial interface.
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_CDCACM``: Enable USB CDC/ACM serial transport
|
||||
support.
|
||||
|
||||
UDP Interface Options
|
||||
---------------------
|
||||
|
||||
These options are available when ``CONFIG_LOGGING_NXSCOPE_INTF_UDP=y``:
|
||||
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_UDP_PORT``: Local UDP port for the NxScope
|
||||
interface.
|
||||
|
||||
Timer Options
|
||||
-------------
|
||||
|
||||
These options are available when ``CONFIG_EXAMPLES_NXSCOPE_TIMER=y``:
|
||||
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_TIMER_PATH``: Device path for the hardware timer.
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_TIMER_INTERVAL``: Timer interval in microseconds.
|
||||
- ``CONFIG_EXAMPLES_NXSCOPE_TIMER_SIGNO``: Signal number for timer
|
||||
notifications.
|
||||
|
||||
Command-Line Arguments
|
||||
======================
|
||||
|
||||
The example accepts the following command-line arguments:
|
||||
|
||||
- ``-i <stream_interval_us>``: Data sampling thread interval in microseconds.
|
||||
Overrides the default value (``CONFIG_EXAMPLES_NXSCOPE_TIMER_INTERVAL``
|
||||
if timer is used, otherwise 100us).
|
||||
- ``-m <main_interval_us>``: Main loop interval in microseconds.
|
||||
Overrides the default value (``CONFIG_EXAMPLES_NXSCOPE_MAIN_INTERVAL``).
|
||||
|
||||
Supported Channels
|
||||
==================
|
||||
|
||||
The example initializes 32 channels to demonstrate different data types and
|
||||
capabilities:
|
||||
|
||||
- **Channels 0-7**: Standard integer types (uint8 to int64).
|
||||
- **Channels 8-9**: Floating point types (float and double).
|
||||
- **Channels 10-15**: Fixed-point types (b8, b16, b32).
|
||||
- **Channel 16**: Vector of floats (3-phase sine waveform).
|
||||
- **Channel 17**: Vector of floats with metadata.
|
||||
- **Channel 18**: No-data channel with metadata.
|
||||
- **Channel 19**: Character channel for text logs (if enabled).
|
||||
- **Channel 20**: Critical channel (if enabled).
|
||||
|
||||
@@ -1,43 +1,220 @@
|
||||
===========================
|
||||
``nxscope`` NxScope Library
|
||||
===========================
|
||||
===============
|
||||
NxScope Library
|
||||
===============
|
||||
|
||||
This library provides real-time data logging functionality for NuttX.
|
||||
NxScope provides real-time data logging by buffering samples into up to 255
|
||||
virtual channels (vector, point, or text data) and streaming them through
|
||||
custom protocols and interfaces. It supports remote control via commands,
|
||||
timestamping, sample rate dividers, and critical non-buffered channels.
|
||||
|
||||
The principle of action is to accumulate data gathered in virtual channels
|
||||
and periodically send buffered data through a dedicated interface packed
|
||||
with a custom protocol.
|
||||
Use Cases
|
||||
=========
|
||||
|
||||
Supported features:
|
||||
- Real-time sensor data streaming and visualization.
|
||||
- Control system telemetry (PID tuning, state monitoring).
|
||||
- High-frequency signal capture (ADC).
|
||||
- Remote debugging and live variable tracking.
|
||||
|
||||
- up to 255 channels possible
|
||||
- support for standard data types and user-specific data (``enum nxscope_sample_dtype_e``)
|
||||
- support for vector data or point data
|
||||
- support for character-based channels (text messages)
|
||||
- support for channel metadata - can be used to enumerate samples or timestamp
|
||||
- stream buffer overflow detection (``NXSCOPE_STREAM_FLAGS_OVERFLOW``)
|
||||
- remote control with commands (``enum nxscope_hdr_id_e``)
|
||||
- protocol and interface implementation can be different for control commands and stream data
|
||||
- (optional) support for user-specific commands (``NXSCOPE_HDRID_USER`` and ``struct nxscope_callbacks_s``)
|
||||
- (optional) support for samples divider (``CONFIG_LOGGING_NXSCOPE_DIVIDER``)
|
||||
- (optional) support for ACK frames (``CONFIG_LOGGING_NXSCOPE_ACKFRAMES``)
|
||||
- (optional) support for user-defined types (``CONFIG_LOGGING_NXSCOPE_USERTYPES``)
|
||||
- (optional) support for non-buffered critical channels (``CONFIG_LOGGING_NXSCOPE_CRICHANNELS``)
|
||||
Configuration
|
||||
=============
|
||||
|
||||
A custom interface and a custom protocol can be implemented with
|
||||
``struct nxscope_intf_s`` and ``struct nxscope_proto_s`` structures.
|
||||
- ``CONFIG_LOGGING_NXSCOPE_INTF_SERIAL`` – Serial port interface
|
||||
- ``CONFIG_LOGGING_NXSCOPE_INTF_UDP`` – UDP interface (over Ethernet)
|
||||
- ``CONFIG_LOGGING_NXSCOPE_INTF_DUMMY`` – Dummy interface (for debug)
|
||||
- ``CONFIG_LOGGING_NXSCOPE_PROTO_SER`` – Default serial protocol (CRC-16)
|
||||
- ``CONFIG_LOGGING_NXSCOPE_DIVIDER`` – Sample rate divider support
|
||||
- ``CONFIG_LOGGING_NXSCOPE_ACKFRAMES`` – ACK frames for set requests
|
||||
- ``CONFIG_LOGGING_NXSCOPE_USERTYPES`` – Support for user-defined frames
|
||||
- ``CONFIG_LOGGING_NXSCOPE_CRICHANNELS`` – Support for non-buffered channels
|
||||
|
||||
Supported interfaces:
|
||||
Implementation
|
||||
==============
|
||||
|
||||
1. a serial port: ``logging/nxscope/nxscope_iser.c``
|
||||
2. a dummy interface for debug purposes: ``logging/nxscope/nxscope_idummy.c``
|
||||
- Serial interface: ``apps/logging/nxscope/nxscope_iser.c``
|
||||
- UDP interface: ``apps/logging/nxscope/nxscope_iudp.c``
|
||||
- Dummy interface: ``apps/logging/nxscope/nxscope_idummy.c``
|
||||
- Default serial protocol: ``apps/logging/nxscope/nxscope_pser.c``
|
||||
|
||||
A default serial protocol is implemented in ``apps/logging/nxscope/nxscope_pser.c``
|
||||
It just packs NxScope data into simple frames with a CRC-16 checksum.
|
||||
Serial Protocol
|
||||
---------------
|
||||
|
||||
External tools
|
||||
--------------
|
||||
The default serial protocol (``nxscope_pser.c``) uses a simple frame format
|
||||
with a header, data payload, and a CRC-16 footer.
|
||||
|
||||
- `Nxslib <https://github.com/railab/nxslib>`_ - a Python (3.10+) client library for NxScope devices,
|
||||
- `Nxscli <https://github.com/railab/nxscli>`_ - a Python (3.10+) command-line interface for NxScope,
|
||||
supporting data capture and visualization
|
||||
Frame Format
|
||||
~~~~~~~~~~~~
|
||||
|
||||
+----------+-----------+-----------+------------+-------------+
|
||||
| SOF (1B) | Len (2B) | ID (1B) | Data (nB) | CRC-16 (2B) |
|
||||
+==========+===========+===========+============+=============+
|
||||
| ``0x55`` | u16 (LE) | u8 | ... | u16 (BE) |
|
||||
+----------+-----------+-----------+------------+-------------+
|
||||
|
||||
- **SOF**: Start of Frame, always ``0x55``.
|
||||
- **Len**: Total frame length (including header and footer) in little-endian.
|
||||
- **ID**: Frame type identifier (see ``enum nxscope_hdr_id_e``).
|
||||
- **Data**: Variable length data payload.
|
||||
- **CRC-16**: CRC-16-XMODEM (polynomial ``0x1021``) of the header and data.
|
||||
|
||||
Frame Types
|
||||
~~~~~~~~~~~
|
||||
|
||||
The following frame types are defined in ``enum nxscope_hdr_id_e``:
|
||||
|
||||
+----------------------------+----+--------------------------------------------+
|
||||
| Type | ID | Description |
|
||||
+============================+====+============================================+
|
||||
| ``NXSCOPE_HDRID_STREAM`` | 1 | Real-time stream data |
|
||||
+----------------------------+----+--------------------------------------------+
|
||||
| ``NXSCOPE_HDRID_CMNINFO`` | 2 | Get common info (chmax, flags, padding) |
|
||||
+----------------------------+----+--------------------------------------------+
|
||||
| ``NXSCOPE_HDRID_CHINFO`` | 3 | Get channel info (name, type, etc.) |
|
||||
+----------------------------+----+--------------------------------------------+
|
||||
| ``NXSCOPE_HDRID_ACK`` | 4 | ACK/NACK response for set requests |
|
||||
+----------------------------+----+--------------------------------------------+
|
||||
| ``NXSCOPE_HDRID_START`` | 5 | Start or stop the data stream |
|
||||
+----------------------------+----+--------------------------------------------+
|
||||
| ``NXSCOPE_HDRID_ENABLE`` | 6 | Enable or disable specific channels |
|
||||
+----------------------------+----+--------------------------------------------+
|
||||
| ``NXSCOPE_HDRID_DIV`` | 7 | Set samples divider for channels |
|
||||
+----------------------------+----+--------------------------------------------+
|
||||
| ``NXSCOPE_HDRID_USER`` | 8 | User defined frames |
|
||||
+----------------------------+----+--------------------------------------------+
|
||||
|
||||
Examples
|
||||
========
|
||||
|
||||
The following applications in NuttX demonstrate the use of the NxScope library:
|
||||
|
||||
1. :doc:`../../examples/nxscope/index` - Basic streaming example.
|
||||
|
||||
2. :doc:`../../industry/foc/index` - Real-time FOC (Field Oriented Control)
|
||||
telemetry.
|
||||
|
||||
3. :doc:`../../system/adcscope/index` - ADC data visualization.
|
||||
|
||||
4. :doc:`../../system/sensorscope/index` - Sensor data streaming.
|
||||
|
||||
Supported Boards
|
||||
================
|
||||
|
||||
Several board configurations in NuttX use the NxScope library:
|
||||
|
||||
- **nrf52832-dk:nxscope_rtt**: Uses Segger RTT as the transport interface.
|
||||
This allows for high-speed data streaming without using a physical UART
|
||||
or USB cable (requires a J-Link debugger).
|
||||
|
||||
- **nrf52832-dk:nxscope_uart**: Uses a physical UART interface with a high
|
||||
baud rate (1Mbps) for data streaming.
|
||||
|
||||
- **stm32f4discovery:nxscope_cdcacm**: Uses USB CDC/ACM for the transport
|
||||
interface, providing a standard serial connection over USB.
|
||||
|
||||
- **qemu-intel64:jumbo**: Uses the UDP interface for high-speed data streaming
|
||||
over an emulated Ethernet connection.
|
||||
|
||||
- **thingy53:sensors_cpuapp**: Uses USB CDC/ACM with the :doc:`sensorscope
|
||||
<../../system/sensorscope/index>` application to stream data from
|
||||
on-board sensors.
|
||||
|
||||
- **sim:nxscope**: A configuration for the NuttX simulator that allows for
|
||||
easy testing and development of NxScope-related features on a host PC.
|
||||
|
||||
External Tools
|
||||
==============
|
||||
|
||||
- `Nxslib <https://github.com/railab/nxslib>`_ - Python client library.
|
||||
|
||||
- `Nxscli <https://github.com/railab/nxscli>`_ - Core command-line interface.
|
||||
|
||||
- `Nxscli-mpl <https://github.com/railab/nxscli-mpl>`_ - Matplotlib extension
|
||||
for nxscli.
|
||||
|
||||
- `Nxscli-pqg <https://github.com/railab/nxscli-pqg>`_ - PyQtGraph extension
|
||||
for nxscli.
|
||||
|
||||
Nxscli Quick Start
|
||||
------------------
|
||||
|
||||
The `Nxscli <https://github.com/railab/nxscli>`_ is a Python tool used to
|
||||
interface with NxScope-enabled devices. It uses a plugin-based architecture
|
||||
to capture, store, and visualize data.
|
||||
|
||||
.. note::
|
||||
This is a quick command reference only. For a detailed description of all
|
||||
supported features, plugins, and configuration options, please visit the
|
||||
official repositories.
|
||||
|
||||
.. note::
|
||||
A graphical user interface (GUI) for ``nxscli`` is currently under
|
||||
development and will be available soon.
|
||||
|
||||
1. **Installation**:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Core tool
|
||||
pip install nxscli
|
||||
|
||||
# Matplotlib extension (optional)
|
||||
pip install nxscli-mpl
|
||||
|
||||
# PyQtGraph extension (optional)
|
||||
pip install nxscli-pqg
|
||||
|
||||
2. **Interface selection**:
|
||||
|
||||
Select the interface to connect to your device:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Serial port
|
||||
nxscli serial <serial-port> ...
|
||||
|
||||
# Segger RTT
|
||||
nxscli rtt <rtt-target> <rtt-buffer-index> <rtt-buffer-size>...
|
||||
|
||||
# UDP (Ethernet)
|
||||
nxscli udp <target-ip> <target-port> ...
|
||||
|
||||
# Simulated/Dummy interface
|
||||
nxscli dummy ...
|
||||
|
||||
3. **Device information**:
|
||||
|
||||
To display information about the connected NxScope device and its
|
||||
available channels:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Serial interface
|
||||
nxscli serial /dev/ttyACM0 pdevinfo
|
||||
|
||||
4. **Data capture**:
|
||||
|
||||
Configure channels and capture samples:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Print samples from channels 0 and 1 via serial
|
||||
nxscli serial /dev/ttyACM0 chan 0,1 pprinter
|
||||
|
||||
5. **Visualization**:
|
||||
|
||||
NxScope supports live visualization using Matplotlib or PyQtGraph:
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
# Live plot from serial using Matplotlib
|
||||
nxscli serial /dev/ttyACM0 chan 0,1 m_live
|
||||
|
||||
# Live plot from serial using PyQtGraph
|
||||
nxscli serial /dev/ttyACM0 chan 0,1 q_live
|
||||
|
||||
6. **Data streaming**:
|
||||
|
||||
To stream data over UDP (e.g., to PlotJuggler):
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
nxscli serial /dev/ttyACM0 chan 0,1 pudp 0
|
||||
|
||||
@@ -0,0 +1,21 @@
|
||||
====================================
|
||||
``adcscope`` NxScope ADC data stream
|
||||
====================================
|
||||
|
||||
Streams ADC data from an ADC driver via ``NxScope``.
|
||||
|
||||
See :doc:`/applications/logging/nxscope/index` for more details about
|
||||
the NxScope library and host-side tools.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
Enable ``CONFIG_SYSTEM_ADCSCOPE`` and configure the following:
|
||||
|
||||
- ``CONFIG_SYSTEM_ADCSCOPE_ADC_PATH``: ADC device path (e.g. ``/dev/adc0``).
|
||||
- ``CONFIG_SYSTEM_ADCSCOPE_SERIAL_PATH``: Serial device path (e.g. ``/dev/ttyUSB0``).
|
||||
- ``CONFIG_SYSTEM_ADCSCOPE_FETCH_INTERVAL``: ADC data fetch interval in microseconds.
|
||||
- ``CONFIG_SYSTEM_ADCSCOPE_MAIN_INTERVAL``: Main loop interval in microseconds.
|
||||
- ``CONFIG_SYSTEM_ADCSCOPE_STREAMBUF_LEN``: NxScope stream buffer size.
|
||||
- ``CONFIG_SYSTEM_ADCSCOPE_CDCACM``: Use CDC/ACM serial transport.
|
||||
- ``CONFIG_SYSTEM_ADCSCOPE_SWTRIG``: Use software trigger for ADC (``ANIOC_TRIGGER``).
|
||||
@@ -0,0 +1,18 @@
|
||||
==========================================
|
||||
``sensorscope`` NxScope sensor data stream
|
||||
==========================================
|
||||
|
||||
Streams data from the sensor framework via ``NxScope``.
|
||||
|
||||
See :doc:`/applications/logging/nxscope/index` for more details about
|
||||
the NxScope library and host-side tools.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
Enable ``CONFIG_SYSTEM_SENSORSCOPE`` and configure the following:
|
||||
|
||||
- ``CONFIG_SYSTEM_SENSORSCOPE_SERIAL_PATH``: Device path (e.g. ``/dev/ttyUSB0``).
|
||||
- ``CONFIG_SYSTEM_SENSORSCOPE_FETCH_INTERVAL``: Sensor data fetch interval in microseconds.
|
||||
- ``CONFIG_SYSTEM_SENSORSCOPE_STREAMBUF_LEN``: NxScope stream buffer size.
|
||||
- ``CONFIG_SYSTEM_SENSORSCOPE_CDCACM``: Use CDC/ACM serial transport.
|
||||
@@ -2345,3 +2345,10 @@ Connect the HX711 to the STM32F4 board using the following pins:
|
||||
-4
|
||||
|
||||
For more details, refer to the official `HX711 NuttX documentation <https://nuttx.apache.org/docs/latest/components/drivers/character/analog/adc/hx711/index.html>`_.
|
||||
|
||||
nxscope_cdcacm
|
||||
--------------
|
||||
|
||||
Configuration demonstrating NxScope stream over CDC-ACM interface.
|
||||
See :doc:`/applications/examples/nxscope/index` and
|
||||
:doc:`/applications/logging/nxscope/index` for more details.
|
||||
|
||||
@@ -1984,6 +1984,19 @@ Requirement: ``cansequence`` tool from ``linux-can/can-utils``
|
||||
can0 002 [1] 11
|
||||
can0 002 [1] 12
|
||||
|
||||
|
||||
nxscope
|
||||
-------
|
||||
|
||||
Configuration demonstrating NxScope stream over simulated UART interface.
|
||||
|
||||
The simulated UART must be created on host before running NuttX::
|
||||
|
||||
socat PTY,link=/dev/ttySIM0 PTY,link=/dev/ttyNX0
|
||||
|
||||
See :doc:`/applications/examples/nxscope/index` and
|
||||
:doc:`/applications/logging/nxscope/index` for more details.
|
||||
|
||||
ROMFS System-Init
|
||||
=================
|
||||
|
||||
|
||||
Reference in New Issue
Block a user