Merge pull request #3 from u-blox/development

First pull request of Cellular Applications for XPLR-IoT-1 development board - VERSION 0.9

.vscode/c_cpp_properties.json

@@ -0,0 +1,24 @@
+{
+    "configurations": [
+        {
+            "name": "Applications",
+            "includePath": [
+                "${default}",
+                "${workspaceFolder}/applications/tasks",
+                "${workspaceFolder}/applications/common",
+                "${workspaceFolder}/ubxlib/**",
+                "${workspaceFolder}/../env/ncs/zephyr/**"
+            ],
+            "defines": [
+                "_DEBUG",
+                "UNICODE",
+                "_UNICODE"
+            ],
+            "compilerPath": "${workspaceFolder}/../env/gcc-arm-none-eabi-10-2020-q4-major/bin/arm-none-eabi-gcc.exe",
+            "cStandard": "c17",
+            "cppStandard": "c++14",
+            "intelliSenseMode": "windows-gcc-arm"
+        }
+    ],
+    "version": 4
+}

applications/README.md

@@ -0,0 +1,38 @@
+# Applications
+
+This page describes the various application this repository has available and how they generally operate.
+
+<br />
+
+## LED indicator
+---
+The XPLR-IoT-1 development platform has a RGB LED indicator on the front of the box. This application framework allows the application to set the LEDs independently, with various flashing and blinking modes. 
+
+### Application startup LED indicator
+The Boot, Registration, MQTT activity and cell scanning activity has the following LED statuses:
+
+- Turn on: Solid RED 
+- Option choice (Display/Delete log file): Solid Blue
+- XPLR initialization: Flashing red
+- Network Registration: Flashing Blue
+- Connecting to MQTT: Flashing Green
+- Operating: Green
+- Shutdown: Solid Red (Button #1)
+- Off: No LED (Safely turn off)
+
+### Activity LED indicator
+
+- Published MQTT message: Blip Green
+- Cell Scan: Blue / Blip Blue
+
+
+<br />
+
+# Application List
+
+(Currently this repository has only one application).
+
+* [Cellular Tracker](cellular_tracker/).
+  Publishes cellular signal strength parameters and location. Can be controlled to publish Cell Query results (+COPS=?)
+
+* [...]()

examples/filesystem/CMakeLists.txt → applications/cellular_tracker/CMakeLists.txt

@@ -15,5 +15,4 @@
 cmake_minimum_required(VERSION 3.13.1)
 set(EXT_FS 1)
 include(../common.cmake)
-project(filesystem)
-
+project(application)

applications/cellular_tracker/README.md

@@ -0,0 +1,50 @@
+# Cellular Tracking Application
+The Cellular tracking application purpose is to periodically monitor the signal quality of the cellular environment, its location and scan the visible base stations if the `Button #2` is pressed.
+
+All collected information is stored in the device filesystem via the application log but also shared into the cloud via the SARA-R5 MQTT embedded client to an MQTT Broker.
+
+Once turned ON, by default the application monitors the cellular signal quality. Once there is a GNSS fix, the location is also published to the cloud. If the `Button #2` is pressed, a base station scan is initialized.
+
+If the `Button #1` is pressed the application shuts down and the log file is saved and closed. If you do not press `Button #1` and simply turn off the XPLR-IoT-1 device then the log file will not save the entire log.
+
+## Building the application
+Use the do build script with the -e argument: `do -e cellular_tracker build`
+
+## Configuring the application
+Using the [config.h](config/config.h) file in the [config](config/) folder you will find the cellular URAT and APN settings. 
+
+For the MQTT connection, there is a #define of the MQTT credentials which to use for this application. Please see the [mqttCredentials.c](src/mqtt_credentials.c) file for examples of MQTT broker settings.
+
+# Application remote commands
+
+The application can be remotely controlled through various topics which are subscribed to by the application tasks. The listed topics and their commands are here:
+
+## <IMEI\>AppControl
+
+### SET_DWELL_TIME <milliseconds\>
+Sets the period between the main loop performing the location and signal quality measurements. Default is 5 seconds.
+
+### SET_LOG_LEVEL <log level\>
+Sets the logging level of the application. Default is '2' for INFO log level.
+
+    0: TRACE
+    1: DEBUG
+    2: INFO
+    3: WARN
+    4: ERROR
+    5: FATAL
+
+It could be possible to increase the logging of an application remotely by changing the logging value from '2' to '1'.
+
+## <IMEI\>CellScanControl
+
+### START_CELL_SCAN
+Starts a cell scan process, just as if you had pressed Button #2
+
+# NOTES
+## Thingstream SIMS
+Thingstream SIMs can be used with two APNS; TSUDP or TSIOT.
+
+TSUDP is ONLY for MQTT-Anywhere service (using MQTT-SN), and does not allow any other internet traffic. This means when using TSUDP the NTP date/time request is not performed. This 'TSUDP' APN is listed as a 'restricted' APN in the [tasks/registrationTask.h](../tasks/registrationTask.h) file.
+
+TSIOT can be used for normal internet services and as such should be used when using other MQTT brokers, or even other MQTT-SN gateways.

applications/cellular_tracker/config/README.md

@@ -0,0 +1,21 @@
+# Application Configuration
+## General settings
+The [config.h](config.h) file contains the general settings for the cellular module's connection to the network. The APN shall be configured accordingly for the SIM card used. Thingstream SIMs should use `TSIOT` for internet based MQTT brokers, and `TSUDP` for Thingstream MQTT-Anywhere service.
+
+Other items are for the MNO PROFILE (+UMNOPROF) and Radio Access Technology (+URAT)
+
+Finally, the MQTT broker needs to be selected from the list in the [mqtt_credentials.c](../src/mqtt_credentials.c) file.
+
+## MQTT Credentials
+Users might need to modify the [mqtt_credentials.c](../src/mqtt_credentials.c) file providing details of the MQTT broker to be used, and set the chosen configuration in the [config.h](config.h) file.
+
+The application will automatically save the selected mqtt configuration to the file system for later use.
+You can now delete/remove the specific credentials from the [mqtt_credentials.c](../src/mqtt_credentials.c) file. This is so that a private configuration for the MQTT credentials can be kept private.
+Using the `MQTT_FILE_SYSTEM` definition will cause the application to load the mqtt credentials from the file system.
+
+ 1. Edit/Add to the `mqtt_credentials.c` file which describes the MQTT broken name or IP address and the username/password.
+ 2. Select this MQTT configuration using the #define in `config.h`
+ 3. Compile and flash. When the application runs it will save this configuration information to the file system.
+ 4. If required, delete the private credential information in `mqtt_credentials.c` and then use `#define` `MQTT_FILE_SYSTEM`.
+    1. Compile again and re-flash into the XPLR-IoT-1 device.
+    2. The previously saved configuration will be loaded from the file system.

applications/cellular_tracker/config/config.h

@@ -0,0 +1,108 @@
+/*
+ * Copyright 2022 u-blox
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ *
+ * Configuration for the Cellular Tracking Application
+ * Contains:
+ *      MQTT credentials (in another #include)
+ *
+ *      Cellular APN
+ *      Cellular MNO Profile, URAT
+ *
+ */
+
+/* This is the configuration file for the MQTT credentials
+ If this include file is included its data will be saved as
+ a 'configuration file' to be used later.
+
+ Compile with the mqtt_credentials.h included, and it will be
+ automatically saved to the file system to be used again.
+ You can then delete/remove/comment out this #include so
+ that it is not saved to the repository :)
+ */
+
+#ifndef _CONFIG_H_
+#define _CONFIG_H_
+
+/* ----------------------------------------------------------------
+ * Application Version number - this includes the common/tasks too
+ * -------------------------------------------------------------- */
+#define APP_NAME    "Cellular Tracker"
+#define APP_VERSION "v0.9"
+
+/* ----------------------------------------------------------------
+ * DEBUG LEVEL SETTING - This can be changed remotely using
+ *                       "SET_LOG_LEVEL" command via the
+ *                        APP_CONTROL MQTT topic
+ * -------------------------------------------------------------- */
+#define LOGGING_LEVEL eINFO            // taken from logLevels_t
+
+/* ----------------------------------------------------------------
+ * APN SELECTION
+ *
+ * THINGSTREAM SIMS:-
+ *  -   Must use 'TSUDP' for Thingstream MQTT-Anywhere.
+ *  -   USE 'TSIOT' for 'normal' internet use.
+ *
+ * RESTRICTED APNS:-
+ *  -   In the tasks/registrationTask.c file there is a list of APNs
+ *      which are marked as 'restricted'. This means normal internet
+ *      queries are not available, like the NTP service on TSUDP APN.
+ *      Edit this list for other APNs which are restricted/limited.
+ * -------------------------------------------------------------- */
+#define APN "TSIOT"
+
+/* ----------------------------------------------------------------
+ * MQTT CREDENTIALS SELECTION
+ *
+ * Please select, using ONE #define below, which mqtt configuration
+ * to use for this application.
+ *
+ * Each are described in the src/mqtt_credentials.c file
+ * ----------------------------------------------------------------*/
+// *** Thingstream MQTT Services
+//#define MQTT_THINGSTREAM_ANYWHERE
+//#define MQTT_THINGSTREAM_FLEX
+//#define MQTT_THINGSTREAM_NOW_NoTLS_Auth
+//#define MQTT_THINGSTREAM_NOW_TLS_Auth
+
+// *** Mosquitto MQTT Test Service
+//#define MQTT_MOSQUITTO_NoTLS_NoAuth
+//#define MQTT_MOSQUITTO_NoTLS_Auth
+//#define MQTT_MOSQUITTO_TLS_Cert
+#define MQTT_MOSQUITTO_TLS_Auth
+
+/*  ----------------------------------------------------------------
+ * RADIO ACCESS TECHNOLOGY SELECTION
+ *
+ * Please use the same RAT enum from the UBXLIB uCellNetRat_t list.
+ *  ----------------------------------------------------------------*/
+#define URAT U_CELL_NET_RAT_CATM1
+
+/* ----------------------------------------------------------------
+ * MNO PROFILE SELECTION
+ *
+ * Please use the MNO Profile number for the cellular module being
+ * used. See the AT command manual appendix for list
+ *
+ * Standard Profiles:
+ *    100 = European
+ *    90  = Global
+ * ----------------------------------------------------------------*/
+#define MNO_PROFILE 100
+
+#endif

examples/nfc/prj.conf → applications/cellular_tracker/prj.conf

@@ -10,11 +10,12 @@
 # distributed under the License is distributed on an "AS IS" BASIS,
 # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 
-CONFIG_NFC_T2T_NRFXLIB=y
-
-CONFIG_NFC_NDEF=y
-CONFIG_NFC_NDEF_MSG=y
-CONFIG_NFC_NDEF_RECORD=y
-CONFIG_NFC_NDEF_URI_REC=y
-CONFIG_NFC_NDEF_URI_MSG=y
+# Need to enable stack free functions
+CONFIG_INIT_STACKS=y
+CONFIG_THREAD_STACK_INFO=y
+CONFIG_THREAD_NAME=y
+CONFIG_SPI=y
 
+# There are two theads per app task (task+queue).
+# So here we need to make sure there are enough threads.
+CONFIG_COMPILER_OPT="-DU_CFG_OS_MAX_THREADS=30"

applications/cellular_tracker/src/.gitignore

@@ -0,0 +1 @@
+/configFile.h

applications/cellular_tracker/src/main.c

@@ -0,0 +1,92 @@
+/*
+ * Copyright 2022 u-blox
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/*
+ *
+ * Cellular tracking application based on the XPLR-IoT-1 device
+ * Connects to an MQTT broker and publishes:
+ *      o cellular rsrp/rsrq measurements
+ *      o cellular CellID
+ *      o GNSS Location
+ *
+ */
+
+#include "common.h"
+
+#include "appInit.h"
+#include "taskControl.h"
+
+#include "mqttTask.h"
+#include "signalQualityTask.h"
+#include "locationTask.h"
+#include "cellScanTask.h"
+
+// Application name and version number is in the config.h file
+
+/* ----------------------------------------------------------------
+ * Remote control callbacks for the main application
+ * Add your application topic message callbacks here
+ * -------------------------------------------------------------- */
+#define APP_CONTROL_TOPIC "AppControl"
+static callbackCommand_t callbacks[] = {
+    {"SET_DWELL_TIME", setAppDwellTime},
+    {"SET_LOG_LEVEL", setAppLogLevel}
+};
+
+/// @brief The application function(s) which are run every appDwellTime
+/// @return A flag to indicate the application should continue (true)
+bool appFunction(void)
+{
+    queueMeasureNow(NULL);
+    queueLocationNow(NULL); 
+
+    return true;
+}
+
+void buttonTwo(void)
+{
+    queueNetworkScan(NULL);
+}
+
+/* ----------------------------------------------------------------
+ * Main startup function for the framework
+ * -------------------------------------------------------------- */
+void main(void)
+{
+    if (!startupFramework())
+        return;
+
+    // The Network registration task is used to connect to the cellular network
+    // This will monitor the +CxREG URCs
+    runTask(NETWORK_REG_TASK);
+
+    // The MQTT task connects and reconnects to the MQTT broker selected in the 
+    // config.h file. This needs to run for MQTT messages to be published and
+    // for remote control messages to be handled
+    runTask(MQTT_TASK);
+
+    // Subscribe to the main AppControl topic for remote control the main application (this)
+    subscribeToTopicAsync(APP_CONTROL_TOPIC, U_MQTT_QOS_AT_MOST_ONCE, callbacks, NUM_ELEMENTS(callbacks));
+
+    // Set button two to point to the queueCellScan function
+    setButtonTwoFunction(buttonTwo);
+
+    // Start the application loop with our app function
+    runApplicationLoop(appFunction);
+
+    // all done, close down and finalise    
+    finalise(SHUTDOWN);
+}