Quectel l86 m33

.github/workflows/check.yml

@@ -41,7 +41,7 @@ jobs:
           echo "::add-matcher::nuttx/.github/nxstyle.json"
           python3 -m venv .venv
           source .venv/bin/activate
-          pip install codespell cmake-format black isort flake8
+          pip install codespell cmake-format black isort flake8 cvt2utf
           cd nuttx
           commits="${{ github.event.pull_request.base.sha }}..HEAD"
           git log --oneline $commits

AUTHORS

@@ -23,6 +23,7 @@ David Sidrane
 Dong Heng
 Duo Zhang
 Felipe Moura Oliveira
+Filipe do Ó Cavalcanti
 Flavio Paiva Junqueira
 Fotis Panagiotopoulos
 Giorgio Groß
@@ -79,6 +80,7 @@ Pierre-Noel Bouteville
 Pierre-Olivier Vauboin (PO Vauboin)
 Richard Cochran
 Robert A. Feretich (Bob Feretich)
+Rodrigo Sim
 Sakari Matias Kapanen (Sakari Kapanen)
 Sara da Cunha Monteiro de Souza (Sara Monteiro)
 Sebastian Ene

Documentation/components/drivers/special/sensors.rst

@@ -33,3 +33,4 @@ general interface.
     sensors/sht4x.rst
     sensors/lsm6dso32.rst
     sensors/lis2mdl.rst
+    sensors/l86xxx.rst

Documentation/components/drivers/special/sensors/l86xxx.rst

@@ -0,0 +1,177 @@
+=======
+L86-XXX
+=======
+
+.. tags:: experimental
+
+This driver provides support for the L86-XXX family of GNSS modules by
+Quectel via the :doc:`uorb </components/drivers/special/sensors/sensors_uorb>` interface. 
+Functionality for this driver was tested using the Quectel L86-M33.
+
+.. warning::
+   This driver only contains preliminary support for a handful of proprietary
+   'PMTK' commands There is no support for the entire suite of commands yet.
+   This driver also does not use the standard uORD GNSS upper half driver and
+   should eventually be modified such that it does. CONSIDER THIS DRIVER EXPERIMENTAL.
+
+Application Programming Interface
+=================================
+
+To register the device for use, you will need to enable the standard upper half
+serial drivers (``CONFIG_STANDARD_SERIAL``), since the L86-XXX driver requires
+the path to the UART interface the module is connected to. You will also need to 
+ensure that the baud rate of the UART interface is set to 9600, which is the default 
+baud rate of the L86-XXX series of GNSS modules. 
+
+The driver supports changing the default baud rate and update rate of the GNSS module.
+As a result, you will also need to enable serial TERMIOS support (``CONFIG_SERIAL_TERMIOS``).
+The baud rate and update rate of the GNSS module can be configured using the ``L86_XXX_BAUD`` and ``L86_XXX_FIX_INT`` options respectively.
+Note that a faster update rate will require a higher baud rate to support it and the supported baud rates for the L86-XXX series of GNSS modules are: 
+* 4800
+* 9600
+* 14400
+* 19200
+* 38400
+* 57600
+* 115200
+The baud rate and update rates of the module are changed at registration time.
+
+.. code-block:: c
+
+   #if defined(CONFIG_SENSORS_L86_XXX)
+      #include <nuttx/sensors/l86xxx.h>
+
+      /* Register L86-M33 on USART3 */
+
+      ret = l86xxx_register("/dev/l86m33", "/dev/ttyS2", 0);
+      if (ret < 0) {
+         syslog(LOG_ERR, "Failed to register L86-M33: %d\n", ret);
+      }
+   #endif
+
+Once the driver is registered, it starts a thread that continuously reads raw output from the specified UART device and
+parses the output according to `NMEA <https://en.wikipedia.org/wiki/NMEA_0183>`_ standards using the 
+`minmea <https://github.com/kosma/minmea>`_ library included in NuttX. The driver populates the ``sensor_gnss`` struct 
+and pushes it to the appropriate event once all NMEA messages in its sequence have been read.
+
+
+**uORB commands**
+-----------------
+The driver implements the ``orb_activate``, ``orb_set_interval`` and, ``orb_ioctl`` operations to interact with the device.
+The latter is used to send proprietary 'PMTK' commands which are documented further below.
+
+**Activate**
+
+There are 4 modes that the L86-XXX GNSS modules can be in. Those are "Full On Mode", "Standby Mode", "Backup Mode", "Periodic Mode" and, "AlwaysLocateTM Mode".
+Calling ``orb_activate`` with ``enable`` set to false will enter the module into "Standby Mode". 
+In "Standby Mode", the module doesn't output any NMEA messages but the internal core and I/O power domain are still active.
+
+The module can be re-enabled by calling ``orb_activate`` with ``enable`` set to true, which will hot start the module OR by
+sending any 'PMTK' command.
+
+**Set interval**
+
+The L86-XXX GNSS modules support interval rates from 1Hz to 10Hz (100ms - 10000ms). When using ``orb_set_interval``, be aware that
+increasing the interval of the module may also require and increase in baud rate. An example of how this is performed can be found in
+source code of this driver in the register function.
+
+Any interval rate outside of the supported range will result in a failed call to this function.
+
+**Control**
+
+The ``orb_ioctl`` interface allows one to send proprietary 'PMTK' commands to the L86-XXX GNSS module. It effectively works
+as a wrapper for the command framework outlined by Quectel. The return value of calls to ``orb_ioctl`` follow this pattern:
+
+* -EINVAL - Invalid packet
+* -ENOSYS - Unsupported packet type
+* -EIO - Valid packet, but action failed
+* 0       - Valid packet, action succeeded
+* Other   - Command failed during writing
+
+The supported commands are their arguments are listed below.
+
+``SNIOC_HOT_START``
+-------------------
+Used to "Hot start" the GNSS module. Normally hot start means the GNSS module was powered down for less
+than 3 hours (RTC must be alive) and its ephemeris is still valid. As there is no need for downloading 
+ephemeris, it is the fastest startup method.
+
+.. code-block:: c
+
+   orb_ioctl(sensor, SNIOC_HOT_START);
+
+``SNIOC_WARM_START``
+--------------------
+Used to "Warm start" the GNSS module. Warm start means the GNSS module has approximate information of time,
+position and coarse data on satellite positions, but it needs to download ephemeris until it can get a fix.
+
+.. code-block:: c
+
+   orb_ioctl(sensor, SNIOC_WARM_START);
+
+``SNIOC_COLD_START``
+--------------------
+Used to "Cold start" the GNSS module. Using this message will force the GNSS module to be restarted without
+any prior location information, including time, position, almanacs and ephemeris data.
+
+.. code-block:: c
+
+   orb_ioctl(sensor, SNIOC_COLD_START);
+
+``SNIOC_FULL_COLD_START``
+-------------------------
+Used to "Full cold start" the GNSS module. This is effectively the same as a cold restart, but additionally
+clears system and user configurations. In other words, this resets the GNSS module to its factory settings.
+When full-cold started, the GNSS module has no information on its last location.
+
+.. code-block:: c
+
+   orb_ioctl(sensor, SNIOC_FULL_COLD_START);
+
+``SNIOC_SET_INTERVAL``
+----------------------
+Used to modify the position fix interval of the GNSS module. The argument is an integer between 100 and 10000, default value is 1000.
+
+.. code-block:: c
+
+   orb_ioctl(sensor, SNIOC_SET_INTERVAL, 1000);
+
+``SNIOC_SET_BAUD``
+------------------
+.. note::
+
+   This feature requires termios support to be enabled(``CONFIG_SERIAL_TERMIOS``)
+
+Used to modify the baud rate of the GNSS module. The argument is an integer representing a supported baud rate, default value is 9600.
+Upon sending this command, the baud rate of the UART interface used to communicate with the module is also modified.
+Supported baud rates for the L86-XXX series of GNSS modules are:
+
+* 4800
+* 9600
+* 14400
+* 19200
+* 38400
+* 57600
+* 115200
+
+.. code-block:: c
+
+   orb_ioctl(sensor, SNIOC_SET_BAUD, 9600);
+
+``SNIOC_SET_OPERATIONAL_MODE``
+------------------------------
+Used to set the navigation mode of the GNSS module. The argument is an ``L86XXX_OPERATIONAL_MODE`` enum:
+
+* NORMAL - For general purpose
+* FITNESS - For instances in which low-speed movements (<5 m/s>) will affect calculations
+* AVIATION - For high-dynamic purposes that the large-acceleration movement will have more effect on the position calculation
+* BALLOON - For high-altitude balloon purposes that vertical movement will have more effect on the position calculation
+* STANDBY - Used to enter standby mode for power saving
+
+Default mode is NORMAL
+
+.. code-block:: c
+
+   orb_ioctl(sensor, SNIOC_SET_OPERATIONAL_MODE, NORMAL);
+
+

Documentation/components/libs/libc/index.rst

@@ -153,4 +153,5 @@ Implementation Details
    :maxdepth: 1
    :caption: Contents:
 
+   stream.rst
    zoneinfo.rst

Documentation/components/libs/libc/stream.rst

@@ -0,0 +1,181 @@
+lib_bsprintf
+============
+
+This function is mainly used to output the contents of the input
+structure. Supports standard formats for printf and scanf. For detailed
+parameters, see: 1. https://en.cppreference.com/w/c/io/fprintf 2.
+https://en.cppreference.com/w/c/io/fscanf
+
+-  **special**:
+
+   1. Float use %hf, “%f” or “%lf” is double, “%Lf” is long double.
+   2. The char array is specified with %.xs. for example: “char t[30]”
+      is specified with “%.30s”, char a [20] - " %.20s "
+   3. “%u” is unsigned int.
+   4. “%d” is int.
+   5. When using %f to format a double data type, the double is
+      truncated to 6 decimal places by default.
+   6. It is recommended that the “char[]” array be placed at the end of
+      the structure to prevent parameter configuration errors such as
+      “%.20s” from causing problems in parsing the entire buffer.
+
+-  **demo**
+
+   1. **struct**:
+
+   ::
+
+      begin_packed_struct
+      struct test
+      {
+        uint8_t a;
+        uint16_t b;
+        uint32_t c;
+        int8_t d;
+        int16_t e;
+        int32_t f;
+        float g;
+        double h;
+        char i[32];
+        uint64_t j;
+        int64_t k;
+        char l;
+        unsigned char m;
+        short int n;
+        unsigned short int o;
+        int p;
+        unsigned int q;
+        long r;
+        unsigned long s;
+        long long t;
+        unsigned long long u;
+        size_t v;
+        long double w;
+      }end_packed_struct;
+
+   1. **format string**:
+
+   ::
+
+      const char* sg = "           uint8_t:[%hhu]\n" \
+                       "          uint16_t:[%hu]\n" \
+                       "          uint32_t:[%u]\n" \
+                       "            int8_t:[%hhd]\n" \
+                       "           int16_t:[%hd]\n" \
+                       "           int32_t:[%d]\n" \
+                       "             float:[%hf]\n" \
+                       "            double:[%f]\n" \
+                       "            char[]:[%.32s]\n" \
+                       "          uint64_t:[%lu]\n" \
+                       "           int64_t:[%ld]\n" \
+                       "              char:[%hhd]\n" \
+                       "     unsigned char:[%hhu]\n" \
+                       "         short int:[%hd]\n" \
+                       "unsigned short int:[%hu]\n" \
+                       "               int:[%d]\n" \
+                       "      unsigned int:[%u]\n" \
+                       "              long:[%ld]\n" \
+                       "     unsigned long:[%lu]\n" \
+                       "         long long:[%lld]\n" \
+                       "unsigned long long:[%llu]\n" \
+                       "            size_t:[%uz]\n" \
+                       "       long double:[%Lf]\n";
+
+   1. **use**:
+
+   -  output to terminal:
+
+   ::
+
+      #ifdef CONFIG_FILE_STREAM
+       struct lib_stdoutstream_s stdoutstream;
+
+       lib_stdoutstream(&stdoutstream, stdout);
+
+       flockfile(stdout);
+       lib_bsprintf(&stdoutstream.common, sv, &test_v);
+       lib_bsprintf(&stdoutstream.common, sg, &test_g);
+       funlockfile(stdout);
+      #else
+       struct lib_rawoutstream_s rawoutstream;
+       struct lib_bufferedoutstream_s outstream;
+
+       lib_rawoutstream(&rawoutstream, STDOUT_FILENO);
+       lib_bufferedoutstream(&outstream, &rawoutstream.common);
+
+       lib_bsprintf(&outstream.common, sv, &test_v);
+       lib_bsprintf(&outstream.common, sg, &test_g);
+
+       lib_stream_flush(&outstream.common);
+      #endif
+
+lib_bscanf
+==========
+
+This function adds a formatted standard scanf string to the
+structure(lib_bscanf). 1. https://zh.cppreference.com/w/c/io/fscanf
+
+-  **special**:
+
+   1. Please use %lf for double precision, “%hf” or “%f” for float, long
+      double (“%Lf”) is not supported.
+   2. Please use %hhd or %hhu for a single char or unsigned char.
+   3. Use %hd or %hu for short int or unsigned short int.
+   4. When using %s or %c, please specify the length of the char array,
+      such as %32s, %32c.
+   5. %s will check the string for spaces. When there are spaces in the
+      string, it will be truncated. If you want to use string with
+      spaces, please use %{length}c, but make sure that the length of
+      the string can fill the array, otherwise an error will occur.
+   6. %[] collection and %n are not supported.
+
+-  **demo**
+
+   1. **struct**: Same as above
+   2. **format string**:
+
+   ::
+
+      #define TOSTR(str)   #str
+      #define TONNAME(name) TOSTR(name)
+
+      #define v_uint8_t    97
+      #define v_uint16_t   19299
+      #define v_uint32_t   22155
+
+      ......
+
+      #define v_l_double   -9299.9299929912122464755474
+
+      char bflag[] = "%hhu%hu%u%hhd%hd%d%f%lf%32s%llu%lld%hhd%hhu%hd%hu%d%u%ld%lu%lld%llu%zu%ld";
+
+      char binput[] = TONNAME(v_uint8_t) \
+                     " " TONNAME(v_uint16_t) \
+                     " " TONNAME(v_uint32_t) \
+                     " " TONNAME(v_int8_t) \
+                     " " TONNAME(v_int16_t) \
+                     " " TONNAME(v_int32_t) \
+                     " " TONNAME(v_float) \
+                     " " TONNAME(v_double) \
+                     " " TONNAME(v_char_arr) \
+                     " " TONNAME(v_uint64_t) \
+                     " " TONNAME(v_int64_t) \
+                     " " TONNAME(v_char) \
+                     " " TONNAME(v_u_char) \
+                     " " TONNAME(v_s_int) \
+                     " " TONNAME(v_u_s_int) \
+                     " " TONNAME(v_int) \
+                     " " TONNAME(v_u_int) \
+                     " " TONNAME(v_long) \
+                     " " TONNAME(v_u_long) \
+                     " " TONNAME(v_l_l) \
+                     " " TONNAME(v_u_l_l) \
+                     " " TONNAME(v_size_t) \
+                     " " TONNAME(v_l_double);
+
+   3. **use**:
+
+   ::
+
+      struct test vg;
+      ret = lib_bscanf(binput, bflag, &vg);