Part of theheraldproject#113. Added Mesh Modem client and RabbitMQ Link

Significant changes:- - Added herald/mesh/modem_client.cpp/h and MeshModem class (shell only) - Added herald/mesh/modem_rabbitmq.cpp/h to link MeshModem to RabbitMQ - Added mesh_modem_rmq_adapter sample app to provide containerisable and locally runnable command link MeshModem to RabbitMQ link - MeshModemRabbitMQAdapter compiles successfully - Currently untested Signed off by: Adam Fowler <[email protected]>
adamfowleruk · Apr 19, 2022 · c0d46ad · c0d46ad
1 parent dab11d0
commit c0d46ad
Show file tree

Hide file tree

Showing 25 changed files with 2,097 additions and 83 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -22,5 +22,6 @@ add_subdirectory(heraldns-cli)
 add_subdirectory(herald)
 add_subdirectory(herald-tests)
 add_subdirectory(herald-programmer)
-add_subdirectory(herald-mesh-proxy)
+add_subdirectory(herald-mesh-relay)
+add_subdirectory(herald-mesh-rmq-adapter)
 add_subdirectory(doxygen)
diff --git a/README.md b/README.md
@@ -3,8 +3,8 @@
 This repository contains a Herald Bluetooth Protocol and Payload
 set of implementations for native platforms. This includes
 Windows 10 desktop and Nordic Semiconductor or other Zephyr RTOS
-capable boards. The board used for development is the
-Seeed nRF52840MK-USB-Dongle.
+capable boards. The boards used for development are Nordic Semiconductor
+nRF52 and 53 development kits and derived dongles.
 
 This particular code base is the core Herald library. It is
 used by all examples, including Wearables (just like the Herald for
@@ -15,30 +15,41 @@ This implementation was introduced in Herald v1.2.
 
 ## License and Copyright
 
-Copyright 2020-2021 Herald Project Contributors
+Copyright 2020-2022 Herald Project Contributors
 
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache2.0-yellow.svg)](https://opensource.org/licenses/Apache-2.0)
 
 See LICENSE.txt and NOTICE.txt for details.
 
-## Demonstration apps / libraries
+## Ready to use applications
 
-The following apps are available:-
+The following applications are downloadable and ready to use on 
+[Herald Hardware](https://github.com/theheraldproject/herald-hardware)
+and other compatible devices.
 
-- herald-tests - Herald core C++ API tests
-- herald-venue-beacon - Herald Zephyr RTOS based app for Venue beacons as a replacement/supplement for QR code scanning when visiting business, bars, and restaurants. [See the separate README](./herald-venue-beacon/README.md)
-- herald-wearable - Herald Zephyr RTOS based app for wearable devices. The equivalent of the herald-for-ios and herald-for-android demo apps for phones
-- heraldns and heraldns-cli and heraldns-tests - Not strictly using the Herald API, but used to test epidemiological/scientific theories that may be merged in to herald's core API in future. Command line utility to simulate social mixing analyses and virus spread.
+Embedded Smart Beacon applications (Zephyr RTOS based):-
+- [Herald Bluetooth MESH Gateway](herald-mesh-relay) - Create a Smart Building, connect devices, and build open source Smart Hospitals and Internet of Things applications
+- [Herald Bluetooth MESH Modem](herald-mesh-modem) - Connect a Herald Bluetooth MESH network to your servers, connecting your organisations applications to the Herald Bluetooth MESH network
+
+Server applications (Linux based):-
+- [Herald Bluetooth MESH RabbitMQ Adapter](herald-mesh-rmq-adapter) - Control a Herald Bluetooth MESH Modem remotely by connecting it to a reliable message broker
+
+## The Herald API for Embedded devices and C++ apps
 
 The following are libraries available for your own projects:-
 
-- herald - Core herald API (include as an external library or call herald.cmake directly to statically compile in to your app)
+- [herald](/herald) - Core herald API (include as an external library or call herald.cmake directly to statically compile in to your app). Works on all platforms, but currently targets Windows, Linux and Zephyr for the main API, and Zephyr for the NFC & Bluetooth Low Energy and Bluetooth MESH transport layers. 
+  - Adding a new platform just requires creating 4 classes for the new platform: Context, ConcreteBluetoothReceiver, ConcreteBluetoothTransmitter, SHA256
+- [herald mesh](/herald/include/herald/mesh) provides higher level Zephyr MESH API for creating Smart Hospitals style Internet of Things environments
+  - A Linux MESH Modem tty interaction adapter layer class is also provided called `herald::mesh::MeshModem`.
 
-The following are 'coming soon':-
+## Demonstration apps / libraries
+
+The following non-production sample and demo apps are also available:-
 
-- herald-mesh-proxy - Rather than a beacon that acts on its own, this mesh proxy provides the same functions of a beacon but also value add functionality from having a Bluetooth 5.0 mesh data network
-- herald-programmer - Utility to reprogram Herald based beacons / mesh proxies in the field in a more
-user friendly way than development tools (E.g. carehomes, field personnel updates, etc.)
+- herald-tests - Herald core C++ API tests
+- herald-venue-beacon - Herald Zephyr RTOS based app for Venue beacons as a replacement/supplement for QR code scanning when visiting business, bars, and restaurants. [See the separate README](./herald-venue-beacon/README.md)
+- herald-wearable - Herald Zephyr RTOS based app for wearable devices. The equivalent of the herald-for-ios and herald-for-android demo apps for phones to enable Digital Contact Tracing
 
 ## Supported / tested platforms
 
@@ -47,18 +58,20 @@ subset of use cases. If you'd like to contribute platform support feel free to p
 
 - Windows 64-bit with CLang 10.0+ for VS community edition 2017
   - We don't currently support the vsc++ compiler
+- Linux 64-bit (We use Manjaro) 
 - Zephyr RTOS / arm with arm-none-eabi-gcc 8.3+ for nRF52840, nRF52832
   - We specifically test using the [Nordic nRF Connect SDK Zephyr variant](https://developer.nordicsemi.com/nRF_Connect_SDK/doc/latest/nrf/zephyr.html) [External]
 
-Other platforms which may work but which we do not provide direct advice for:-
+## Platforms supported in other Herald projects
 
-- Other [Zephyr supported boards](https://docs.zephyrproject.org/latest/boards/index.html) [External]
-- Linux Desktops/laptops (yet)
+We have similar API and apps for other platforms. Below are some useful references:-
+
+- Other [Zephyr supported boards](https://docs.zephyrproject.org/latest/boards/index.html) [External] where these applications may work with some configuration changes
+- We also have a higher level [Mobile app flutter API](https://github.com/theheraldproject/herald-for-flutter/) which includes UI components and supports multiple mobile devices. We also have native lower-level mobile device support:-
   - Android devices see the separate [herald-for-android](https://github.com/theheraldproject/herald-for-android/) project
-- Apple OS X Desktops/laptops (yet)
   - iOS devices see the separate [herald-for-ios](https://github.com/theheraldproject/herald-for-ios) project
 
-## Implementation differences
+## Herald API implementation differences
 
 Some thin wrappers were not required in the C++ version compared
 to the Java and Swift versions as the base primitives were already
@@ -81,40 +94,40 @@ C++ files on some platforms where known utility libraries are always present. Cu
 
 - herald::datatype::uuid - high level UUID interface with just the functionality required by Herald and no more.
 - herald::datatype::base64string - encodes and decodes a Data instance as a Base64 string
+- herald::datatype::sha256 - SHA256 functionality, currently supported on Windows (OpenSSL-3), Zephyr (TineCrypt or MbedTLS) and Linux (OpenSSL-3)
 
 ## Implementation details
 
 Any trivial wrapper classes have been implemented 
 as structs.
 
-Any Interfaces from Java and Swift have been implemented as
-pure virtual base classes. The code base is being heavily
-refactored to use references only and avoid using any pointers,
+Any Interfaces from Java and Swift have not been implemented, with their
+derived classes being instead defined as templates. The code base has been heavily
+refactored in V2.0+ to use references only and avoid using any pointers,
 including smart pointers. This allows us to be able to predict and
 restrict memory use at compile time, and provide for maximum memory
 safety.
 
 This code base implements Bluetooth Low Energy (BLe)
-implementations on Zephyr/nRF Connect as standard.
+implementations on Zephyr/nRF Connect as standard. We also support USB (MESH modem),
+Bluetooth MESH (Smart Hospitals), and NFC (secure out of band provisioning of MESH devices).
 
 ## What isn't implemented
 
-Any higher level implementation details, such as Mesh gateway payloads
-and interconnect logic is within a downstream library project. That
-is to keep this set of classes simple and consistent with the iOS
-and Android equivalent Herald libraries.
+User interface code - only embedded applications and the Herald libraries are in
+this project repository. We anticipate the 'user interface' to be provided by
+mobile applications paired with wearables or beacons via the 
+[Herald Flutter API](https://github.com/theheraldproject/herald-for-flutter)
+or via cloud native web applications using the `herald-mesh-rmq-adapter` to
+interact with a Herald Bluetooth MESH network.
 
 ## What is implemented
 
-We do provide a demo Windows application in this repository, and a demo
-zephyr serial application. These act as 'Herald consumer / demo devices'
-and implement the same basic features as the Android and iOS demo apps.
-They are provided to allow us to carry out regression testing on each
-version. 
-
-These demo apps are not intended as production ready applications. They
-can be used as a reference implementation for any Herald based apps
-and devices you wish to create.
+This repository is the primary development reference API for all current and future
+Herald project software work. New API additions are implemented here first. This
+is because embedded devices are often much more constrained, and so ensuring
+functionality first works here helps ensure a simple interface and higher
+performance on other platforms.
 
 ## Specific platform limitations
 
@@ -126,25 +139,34 @@ than respecify our own (E.g. base64, random number generation, uuid).
 
 ### Zephyr OS limitations
 
-We cannot use dynamic_pointer_cast to cast a std::shared_ptr<DerivedType>
-to a std::shared_ptr<BaseType> because this uses RTTI which is not
-supported by Zephyr. We use static_pointer_cast instead, but only when we
-know the class implementation can only have one definition (i.e. the
-one for the current platform). We are moving to remove all use of
-smart pointers generally in favour of references.
-
+Note: In the v2.0 release we have removed all internal use of std::unique_ptr and std::shared_ptr in favour of templates and static sizes for things like SensorDelegates throughout the code base. This is to avoid Zephyr memory management bugs and improve (i.e. to drastically lower) memory use (SRAM) on Nordic Semiconductor and other embedded devices.
+
 We also use noexcept rather than throw exceptions for the same reason.
+This is particularly useful for embedded development, but also provides
+a robust C++ API for other platforms. 
 
-See the [Zephyr C++ limitations](https://docs.zephyrproject.org/latest/reference/kernel/other/cxx_support.html) [External] page for details.
+Note that Zephyr doesn't support RTTI in C++. See the [Zephyr C++ limitations](https://docs.zephyrproject.org/latest/reference/kernel/other/cxx_support.html) [External] page for full C++ compatibility details.
 Note that this page is out of date somewhat. The 'new' keyword, for example, is supported in Zephyr although it is very buggy.
 
-Note: In the v2.0 release we have removed all internal use of std::unique_ptr and std::shared_ptr in favour of templates and static sizes for things like SensorDelegates throughout the code base. This is to avoid Zephyr memory management bugs and improve (lower) memory use (SRAM) on Nordic Semiconductor devices.
+### Mac OS limitations
+
+Mac OS is not a primary development platform today and so some features do not work there. These are:-
+
+- No builds of the herald-tests project will succeed due to the gcov code coverage library not being present on MAC OS
+- The herald-mesh-rmq-adapter app only supports Linux (its only TCP&TLS implementation)
+
+### Windows limitations
+
+For some reason the same Zephyr app build ends up with lower SRAM usage when built on Linux rather than Windows. Other than that everything else works fine. Windows 10 and Linux Manjaro are the primary development platforms.
+
+These features do not work on Windows:-
+- The herald-mesh-rmq-adapter app only supports Linux (its only TCP&TLS implementation)
 
 ## Building with Code Coverage
 
 1. Open Visual Studio Code
 1. Perform a CMake build using CLang on Windows in Debug mode
-1. Execute this in the build folder on the command line: ```cmake .. -DCMAKE_BUILD_TYPE=Debug -DCODE_COVERAGE=ON``` to add code coverage support
+1. Execute the following in the `build` folder on the command line: ```cmake .. -DCMAKE_BUILD_TYPE=Debug -DCODE_COVERAGE=ON``` to add code coverage support
 1. Open the CMake tools tab in Visual Studio Code
 1. Expand 'herald-tests'
 1. Run the 'ccov-report' utility
diff --git a/herald-mesh-modem/.clang-format b/herald-mesh-modem/.clang-format
@@ -0,0 +1,30 @@
+# Use the Google style in this project.
+BasedOnStyle: Google
+
+# Some folks prefer to write "int& foo" while others prefer "int &foo".  The
+# Google Style Guide only asks for consistency within a project, we chose
+# "int& foo" for this project:
+DerivePointerAlignment: false
+PointerAlignment: Left
+
+IncludeBlocks: Regroup
+IncludeCategories:
+- Regex: '^\"../../herald'  # herald includes
+  Priority: 1000
+- Regex: '^\"' # all other quoted (project) includes
+  Priority: 1500
+- Regex: '^<bluetooth/' # zephyr Bluetooth
+  Priority: 2000
+- Regex: '^<drivers/*' # zephyr custom drivers
+  Priority: 3000
+- Regex: '^<dk_buttons_and_leds.h' # zephyr DK conveniences
+  Priority: 3500
+- Regex: '^<logging/*' # zephyr logging goes last of zephyr includes
+  Priority: 5000
+- Regex: '^<.*/.*' # other installed library includes
+  Priority: 4000
+- Regex: '^<[^/]*>' # C++ top level includes
+  Priority: 4500
+
+IndentCaseLabels: 'true'
+Standard: Cpp11
diff --git a/herald-mesh-modem/.vscode/c_cpp_properties.json b/herald-mesh-modem/.vscode/c_cpp_properties.json
@@ -0,0 +1,41 @@
+{
+    "configurations": [
+        {
+            "name": "Win64",
+            "includePath": [
+                "${default}",
+                "${workspaceFolder}/../herald/include"
+            ],
+            "defines": [
+                "_DEBUG",
+                "UNICODE",
+                "_UNICODE"
+            ],
+            "windowsSdkVersion": "10.0.19041.0",
+            "compilerPath": "C:/Program Files (x86)/Microsoft Visual Studio/2019/Community/VC/Tools/MSVC/14.27.29110/bin/Hostx64/x64/cl.exe",
+            "cStandard": "c17",
+            "cppStandard": "c++17",
+            "intelliSenseMode": "msvc-x64",
+            "configurationProvider": "ms-vscode.cmake-tools"
+        },
+        {
+            "name": "zephyr",
+            "includePath": [
+                "${default}",
+                "${workspaceFolder}/../herald/include",
+                "/opt/nordic/ncs/v1.9.1/zephyr/include"
+            ],
+            "defines": [
+                "_DEBUG",
+                "UNICODE",
+                "_UNICODE"
+            ],
+            "compilerPath": "/opt/nordic/ncs/v1.9.1/toolchain/bin/arm-none-eabi-gcc",
+            "cStandard": "c17",
+            "cppStandard": "c++17",
+            "intelliSenseMode": "gcc-arm",
+            "configurationProvider": "ms-vscode.cmake-tools"
+        }
+    ],
+    "version": 4
+}