Update note-c and prepare for 1.6.4

README.md

@@ -118,7 +118,9 @@ with:
 - [Sensor tutorial](examples/Example6_SensorTutorial/Example6_SensorTutorial.ino)
 - [Power control](examples/Example7_PowerControl/Example7_PowerControl.ino)
 
-Before running an example, you will need to set the Product Identifier, either in code or on your connected Notecard. Steps on how to do this can be found at [https://dev.blues.io/tools-and-sdks/samples/product-uid](https://dev.blues.io/tools-and-sdks/samples/product-uid).
+Before running an example, you will need to set the Product Identifier, either
+in code or on your connected Notecard. Steps on how to do this can be found at
+[https://dev.blues.io/tools-and-sdks/samples/product-uid](https://dev.blues.io/tools-and-sdks/samples/product-uid).
 
 
 ## Contributing
@@ -256,6 +258,36 @@ in the `tests` array in the `main` function. The entry will occupy it's own line
 at the end of the array, and syntax should be as follows,
 `{test_name, "test_name"},`.
 
+## Generating a Release
+
+### Update Files
+
+When generating a release of the `note-arduino` library, you will need to update
+the version in two places.
+
+- `NoteDefines.h`
+
+    The `note-arduino` library provides preprocessor defines to allow for
+    programmatic access to the version number. The following preprocessor
+    defines should be updated with the version you wish to publish:
+
+    - `NOTE_ARDUINO_VERSION_MAJOR`
+    - `NOTE_ARDUINO_VERSION_MINOR`
+    - `NOTE_ARDUINO_VERSION_PATCH`
+
+- `library.properties`
+
+    Update the `version` key to reflect the version you wish to publish. The
+    version string should follow the form "\<major\>.\<minor\>.\<patch\>" (e.g.
+    `1.6.4`). This value will be used by the Arduino Library Manager.
+
+### GitHub Release
+
+Publishing a release on GitHub will trigger the Arduino Library Manager. The
+Arduino Library Manager will then look to the `library.properties` file, and
+generate a release based on the `version` value it finds there. It should be
+noted, the version on GitHub is not evaluated by the Arduino Library Manager.
+
 ## More Information
 
 For additional Notecard SDKs and Libraries, see:

library.properties

@@ -1,5 +1,5 @@
 name=Blues Wireless Notecard
-version=1.6.3
+version=1.6.4
 author=Blues
 maintainer=Blues <[email protected]>
 sentence=An easy to use Notecard Library for Arduino.

src/NoteDefines.h

@@ -4,7 +4,7 @@
 // Define the version of the `note-arduino` library
 #define NOTE_ARDUINO_VERSION_MAJOR 1
 #define NOTE_ARDUINO_VERSION_MINOR 6
-#define NOTE_ARDUINO_VERSION_PATCH 3
+#define NOTE_ARDUINO_VERSION_PATCH 4
 
 #define NOTE_ARDUINO_VERSION NOTE_C_STRINGIZE(NOTE_ARDUINO_VERSION_MAJOR) "." NOTE_C_STRINGIZE(NOTE_ARDUINO_VERSION_MINOR) "." NOTE_C_STRINGIZE(NOTE_ARDUINO_VERSION_PATCH)
 

src/note-c/.gitignore

@@ -8,3 +8,6 @@ __pycache__/
 *.code-workspace
 *.orig
 settings.json
+
+# Development Artifacts
+cppcheck_output.txt

src/note-c/CMakeLists.txt

@@ -1,4 +1,5 @@
-cmake_minimum_required(VERSION 3.13)
+cmake_minimum_required(VERSION 3.20)
+cmake_policy(SET CMP0095 NEW)
 
 if ("${CMAKE_BINARY_DIR}" STREQUAL "${CMAKE_SOURCE_DIR}")
     message(FATAL_ERROR "In-source builds are not allowed.
@@ -14,13 +15,14 @@ if(NOT EXISTS ${PROJECT_BINARY_DIR}/.gitignore)
     file(WRITE ${PROJECT_BINARY_DIR}/.gitignore "*")
 endif()
 
-option(NOTE_C_BUILD_TESTS "Build tests." OFF)
+option(NOTE_C_BUILD_DOCS "Build docs." OFF)
+option(NOTE_C_BUILD_TESTS "Build tests." ON)
 option(NOTE_C_COVERAGE "Compile for test NOTE_C_COVERAGE reporting." OFF)
+option(NOTE_C_LOW_MEM "Build the library tailored for low memory usage." OFF)
 option(NOTE_C_MEM_CHECK "Run tests with Valgrind." OFF)
-option(NOTE_C_BUILD_DOCS "Build docs." OFF)
 option(NOTE_C_NO_LIBC "Build the library without linking against libc, generating errors for any undefined symbols." OFF)
-option(NOTE_C_LOW_MEM "Build the library tailored for low memory usage." OFF)
-option(NOTE_C_TEST_SINGLE_PRECISION "Use single precision for JSON floating point numbers." OFF)
+option(NOTE_C_SHOW_MALLOC "Build the library with flags required to log memory usage." OFF)
+option(NOTE_C_SINGLE_PRECISION "Use single precision for JSON floating point numbers." OFF)
 
 set(NOTE_C_SRC_DIR ${CMAKE_CURRENT_SOURCE_DIR})
 add_library(note_c SHARED)
@@ -52,11 +54,28 @@ target_compile_options(
         -Werror
         -Og
         -ggdb
+    PUBLIC
+        -m32
+        -mfpmath=sse
+        -msse2
 )
 target_include_directories(
     note_c
     PUBLIC ${NOTE_C_SRC_DIR}
 )
+target_link_directories(
+    note_c
+    PUBLIC
+        /lib32
+        /usr/lib32
+        /usr/lib/gcc/x86_64-linux-gnu/12/32
+)
+target_link_options(
+    note_c
+    PUBLIC
+        -m32
+        -Wl,-melf_i386
+)
 
 if(NOTE_C_LOW_MEM)
     target_compile_definitions(
@@ -85,11 +104,19 @@ if(NOTE_C_NO_LIBC)
     )
 endif()
 
-if(NOTE_C_TEST_SINGLE_PRECISION)
+if(NOTE_C_SHOW_MALLOC)
+    target_compile_definitions(
+        note_c
+        PUBLIC
+            NOTE_C_SHOW_MALLOC
+    )
+endif()
+
+if(NOTE_C_SINGLE_PRECISION)
     target_compile_definitions(
         note_c
         PUBLIC
-            NOTE_C_TEST_SINGLE_PRECISION
+            NOTE_C_SINGLE_PRECISION
     )
 endif()
 

src/note-c/CONTRIBUTING.md

@@ -3,8 +3,6 @@
 We love pull requests from everyone. By participating in this project, you
 agree to abide by the Blues Inc [code of conduct].
 
-[code of conduct]: https://blues.github.io/opensource/code-of-conduct
-
 Here are some ways *you* can contribute:
 
 * by using alpha, beta, and prerelease versions
@@ -33,6 +31,12 @@ clean up inconsistent whitespace )
 
 [gist]: https://gist.github.com/
 
+## Library Development
+
+Review our [contribution guidelines](./CONTRIBUTING.md) and [developer
+documentation](./test/README.md) for setting up your environment and
+configuring your toolchain.
+
 ## Cleaning up issues
 
 * Issues that have no response from the submitter will be closed after 30 days.
@@ -59,6 +63,7 @@ clean up inconsistent whitespace )
 https://help.github.com/articles/creating-and-deleting-branches-within-your-repository/
 [pr]: https://help.github.com/articles/creating-a-pull-request-from-a-fork/
 
-Inspired by
+Inspired by:
 https://github.com/thoughtbot/factory_bot/blob/master/CONTRIBUTING.md
 
+[code of conduct]: https://blues.github.io/opensource/code-of-conduct

src/note-c/Dockerfile

@@ -21,6 +21,9 @@ ARG USER
 
 # Local Argument(s)
 
+# Local Environment Variable(s)
+ENV LC_ALL="C.UTF-8"
+
 # Create Non-Root User
 RUN ["dash", "-c", "\
     addgroup \
@@ -38,6 +41,11 @@ RUN ["dash", "-c", "\
      \"${USER}\" \
 "]
 
+# Add 32-bit binaries to the index.
+RUN ["dash", "-c", "\
+    dpkg --add-architecture i386 \
+"]
+
 # Install whatever dependencies we can via apt-get.
 RUN ["dash", "-c", "\
     apt-get update --quiet \
@@ -46,14 +54,18 @@ RUN ["dash", "-c", "\
      ca-certificates \
      curl \
      g++ \
+     g++-multilib \
      gcc \
+     gcc-multilib \
      gdb \
      git \
      lcov \
+     libc6-dbg:i386 \
      make \
      nano \
      python3-pip \
      python3-sphinx \
+     cppcheck \
      valgrind \
  && pip install --break-system-packages \
      breathe \
@@ -83,13 +95,3 @@ RUN ["dash", "-c", "\
  && tar xf cmake-3.25.1-linux-x86_64.tar.gz --strip-components=1 -C /usr \
  && rm cmake-3.25.1-linux-x86_64.tar.gz \
 "]
-
-# Download and install Catch2 v3.2.1.
-RUN ["dash", "-c", "\
-    curl -LO https://github.com/catchorg/Catch2/archive/refs/tags/v3.2.1.tar.gz \
- && tar xf v3.2.1.tar.gz \
- && cd Catch2-3.2.1 \
- && cmake -DCATCH_INSTALL_DOCS=0 -B build/ \
- && cmake --build build/ --target install \
- && rm -rf Catch2-3.2.1  v3.2.1.tar.gz \
-"]

src/note-c/README.md

@@ -1,4 +1,4 @@
-[![Coverage Status](https://coveralls.io/repos/github/blues/note-c/badge.svg?branch=master)](https://coveralls.io/github/blues/note-c?branch=master)
+[![Coverage Status][coverage badge]][coverage details]
 
 # note-c
 
@@ -12,22 +12,116 @@ Notes to [Notehub.io][notehub].
 This library is used by the [note-arduino library][note-arduino], which includes
 it as a git subtree.
 
-## Documentation
+## API Documentation
 
-The documentation for this library can be found [here](https://blues.github.io/note-c/index.html).
+The API documentation for this library can be found [here][note-c API docs].
 
-## CMake
+## Logging Control
 
-The CMake build system is primarily here for testing note-c on a development
-machine. You can use it to generate a static or shared note-c library, but
-embedded users will typically just compile all the .c source files into their
-firmware image. For more on testing, see test/README.md.
+`note-c` provides a comprehensive and flexible logging functionality.
 
-### Options
+To activate logging, you must provide a callback for logging via
+`hookDebugOutput()`. The callback takes the following form:
 
-- BUILD_TESTS: Build the tests. See the tests directory. Default: ON.
-- BUILD_SHARED_LIBS: Build the note-c library as shared instead of static. This
-reduces the total size of the compiled tests. Default: ON.
+```c
+typedef size_t (*debugOutputFn) (const char *text);
+```
+
+The callback is responsible for taking a character array (C-style string) and
+returning the number of bytes processed (written out) as confirmation. The
+exact implementation will be up to the user who provided the function pointer,
+but its presence will active logging in the library.
+
+### Library Logging
+
+#### Log Levels
+
+`note-c` provides for four (4) levels of logging. Here they are listed from
+most severe to most verbose:
+
+0. `NOTE_C_LOG_LEVEL_ERROR`
+1. `NOTE_C_LOG_LEVEL_WARN`
+2. `NOTE_C_LOG_LEVEL_INFO`
+3. `NOTE_C_LOG_LEVEL_DEBUG`
+
+By default, `note-c` logs at `NOTE_C_LOG_LEVEL_INFO`.
+
+#### Default Logging Behavior
+
+To modify the default behavior, you may specify the desired log level at compile
+time, as follows:
+
+```sh
+-DNOTE_C_LOG_LEVEL=0
+```
+
+_**NOTE:** In the example above, you will notice we used zero (`0`), instead of
+`NOTE_C_LOG_LEVEL_ERROR`. This is because the warning constants are internal to
+the library, and not available in the context of the command line._
+
+Here, we have decided to show only the most severe (i.e. `[ERROR]`) logs.
+Alternatively, you may set the level to any of the values listed above.
+
+#### Dynamic Logging Behavior
+
+In the previous section, we discussed setting the base (or default) logging
+behavior for the library. However, you may also set the log level dynamically,
+during runtime, by using the `NoteSetLogLevel()` API.
+
+```c
+NoteSetLogLevel(NOTE_C_LOG_LEVEL_WARN);
+```
+
+### Notecard Sync Logging (`[SYNC]`)
+
+Tangential to the standard logging behavior, `note-c` also provides a helper
+function to invoke/extract synchronization logs from the Notecard.
+
+- `NoteDebugSyncStatus()`
+
+Instead of toggling features inside the library, this helper functions sends a
+request to the Notecard to inquire about its synchronization status and logs
+those details.
+
+The function is designed to be called in a loop and throttled by a parameter.
+See [the documentation page][NoteDebugSyncStatus] for more information.
+
+## Versioning
+
+The `note-c` versioning scheme is a variant of [Semantic
+Versioning](https://semver.org/).
+
+Below is a high-level overview of the major/minor/patch versions:
+
+- Major Version: Signals incompatible API changes.
+- Minor Version: Signals added functionality in a backward compatible manner.
+- Patch Version: Signals backward compatible bug fixes.
+
+Beyond the SemVer foundation, Blues has imposed additional requirements for a
+version to be considered valid:
+
+- Major/minor/patch versions SHALL NOT be zero.
+- For anything other than major version, version numbers MUST NOT contain
+EITHER leading zeroes OR trailing zeroes (e.g. version `1.10.2` is invalid).
+
+> Example version progression:
+>
+> `1.8.1`, `1.9.1`, `1.9.2`, `1.11.1`, `1.11.2`, `1.11.3`, `1.12.1`, `2.1.1`
+
+These additional constraints have been observed to help disambiguate versions
+and reduce support burden.
+
+### Version Artifacts
+
+The version can be referenced/tested programmatically via the following
+preprocessor defined integers found in `note.h`:
+
+- `NOTE_C_VERSION_MAJOR`
+- `NOTE_C_VERSION_MINOR`
+- `NOTE_C_VERSION_PATCH`
+
+The version may also be logged via the preprocessor defined string literal,
+`NOTE_C_VERSION`.
 
 ## Contributing
 
@@ -57,8 +151,12 @@ Copyright (c) 2019 Blues Inc. Released under the MIT license. See
 [LICENSE](LICENSE) for details.
 
 [blues]: https://blues.com
+[code of conduct]: https://blues.github.io/opensource/code-of-conduct
+[coverage badge]: https://coveralls.io/repos/github/blues/note-c/badge.svg?branch=master
+[coverage details]: https://coveralls.io/github/blues/note-c?branch=master
+[NoteDebugSyncStatus]: https://blues.github.io/note-c/api_reference.html#c.NoteDebugSyncStatus
 [notehub]: https://notehub.io
 [note-arduino]: https://github.com/blues/note-arduino
+[note-c API docs]: https://blues.github.io/note-c/index.html
 [note-go]: https://github.com/blues/note-go
 [note-python]: https://github.com/blues/note-python
-[code of conduct]: https://blues.github.io/opensource/code-of-conduct

src/note-c/n_atof.c

@@ -256,7 +256,7 @@ char **endPtr;              /* If non-NULL, store terminating character's
         case 5:
             p10 = 1.0e32;
             break;
-#ifndef NOTE_C_LOW_MEM
+#ifndef NOTE_C_SINGLE_PRECISION
         case 6:
             p10 = 1.0e64;
             break;