Fix 270: add sigfox support for provisioning

README.md

@@ -59,6 +59,8 @@ _Apologies_: This document is a work in progress, and is published in this inter
 		- [Sending an uplink message](#sending-an-uplink-message)
 		- [Registering to receive downlink messages](#registering-to-receive-downlink-messages)
 		- [LoRaWAN Class Structure](#lorawan-class-structure)
+	- [Sigfox Support](#sigfox-support)
+		- [Sigfox Class Structure](#sigfox-class-structure)
 	- [FRAM Storage Management](#fram-storage-management)
 		- [FRAM Storage Formats](#fram-storage-formats)
 			- [Object Storage Structure](#object-storage-structure)
@@ -86,6 +88,9 @@ _Apologies_: This document is a work in progress, and is published in this inter
 	- [FRAM commands](#fram-commands)
 	- [LoRaWAN commands](#lorawan-commands)
 		- [LoRaWAN Parameters](#lorawan-parameters)
+	- [Sigfox commands](#sigfox-commands)
+		- [Sigfox Parameters](#sigfox-parameters)
+		- [Sigfox Regions](#sigfox-regions)
 - [Adding your own commands](#adding-your-own-commands)
 - [Example sketches](#example-sketches)
 	- [`catena_hello`](#catena_hello)
@@ -909,6 +914,51 @@ In order to allow code to be portable across networks and regions, we've done a
 
 As the diagram shows, Catena::LoRaWAN objects are primarily `Arduino_LoRaWAN` derivatives, but they also can be viewed as `McciCatena::cPollableObject` instances, and therefore can participate in [polling](#polling-framework).
 
+### Sigfox Support
+
+The Catena Arduino Platform includes C++ wrappers for Sigfox support, based on the MCCI version of the [MCCI_Sigfox_Image](https://github.com/mcci-catena/MCCI_Sigfox_Image) library. It includes command processing from the `Serial` console for run-time (not compile-time) provisioning, and uses the non-volatile storage provided by the Catena FRAM to store connection parameters and uplink/downlink counts.
+
+The `Catena::Sigfox` class is derived from the `MCCI_Sigfox` class defined by `<MCCI_Sigfox.h>`.
+
+To use Sigfox in a sketch, do the following.
+
+1. Instantiate the global Catena object, with the name `gCatena`.
+
+    ```c++
+    #include <Catena.h>
+
+    using namespace McciCatena; // to save typing
+
+    Catena gCatena;  // instantiate the Catena platform object.
+    ```
+
+2. Instantiate the global Sigfox object, with the name `gSigfox`:
+
+    ```c++
+    Catena::Sigfox gSigfox;  // the Sigfox function.
+    ```
+
+3. In your setup function, initialize gCatena, gSigfox, and register gSigfox as a pollable object (see [Polling Framework](#polling-framework)).
+
+    ```c++
+    void setup() {
+      // other things
+
+      // set up Catena platform.
+      gCatena.begin();
+
+      // set up Sigfox
+      gSigfox.begin(&gCatena);
+      gCatena.registerObject(&gSigfox);
+
+      // other things
+    }
+    ```
+
+#### Sigfox Class Structure
+
+Catena::Sigfox objects are primarily `MCCI_Sigfox` derivatives, but they also can be viewed as `McciCatena::cPollableObject` instances, and therefore can participate in [polling](#polling-framework).
+
 ### FRAM Storage Management
 
 Many MCCI Catena models include FRAM storage for keeping data across power cycles without worrying about the limited write-tolerance of EEPROM or flash. (FRAM, or ferro-electric RAM, is essentially non-volatile memory that can be freely written. Flash EPROM and EEPROM can be written, but tend to have non-local error properties and limited write durability. They are good for storing code, but troublesome for storing counters, because a location must be updated each time a counter is written.)
@@ -1317,6 +1367,42 @@ These parameters are generally not loaded into the LMIC immediately. They are pr
 `lorawan configure fcntdown` _[ value ]_ | either | the current downlink frame count, `FCntDown` in the LoRaWAN spec.
 `lorawan configure join` _[ value ]_ | either | if zero, the provisioning data will _not_ be loaded into the LMIC at startup. Older versions of the [`arduino-lorawan`](https://github.com/mcci-catena/arduino-lorawan) might still allow transmits to cause the device to start trying to join, but it will use invalid credentials.
 
+### Sigfox commands
+
+The following commands are added by the Catena Sigfox module.
+
+| Command | Description |
+|-------------|----------------------------------|
+| `sigfox configure` | Display all Sigfox parameters.
+| `sigfox configure` _`param` [ `value` ]_  | Display or set a Sigfox parameter.
+
+#### Sigfox Parameters
+
+These parameters are generally not loaded into the Sigfox library immediately. They are primarily used at boot time and at join time.
+
+| Command     | Description |
+|-------------|----------------------------------|
+`sigfox configure` | Display all the parameters.
+`sigfox configure devid` _[ value ]_  | Set the devID for this device to _value_, a 32-bit EUI given in big-endian (natural) form.
+`sigfox configure pac` _[ value ]_  |Set the PAC for this device to _value_, a 64-bit EUI given in big-endian (natural) form.
+`sigfox configure key` _[ value ]_  |Set the secured/encrypted key for this device to _value_, a 128-bit value given in big-endian (natural) form.
+`sigfox configure region` _[ value ]_ | Set the region for this device to _value_, a 8-bit value denotes the specific region (ref: [Sigfox Regions](#sigfox-regions)).
+`sigfox configure encryption` _[ value ]_ |Set whether the payload to be encrypted or not using the bool _value_ (0 or 1).
+
+#### Sigfox Regions
+
+These are values of specific regions to be provided to configure the region. For example, to communicate in US915, use the command as `sigfox configure region 2`.
+
+The regions other than in the list below are not supported by Sigfox library currently.
+
+| Value     | Regions |
+|-------------|----------------------------------|
+1 | EU868, MEA868
+2 | US915, SA915
+3 | JP923
+4 | AU915, SA920, AP920
+5 | KR920
+
 ## Adding your own commands
 
 Here's a step-by-step procedure. There's a fully worked example, [`catena_usercommand`](#catenausercommand).
@@ -1431,9 +1517,13 @@ This sketch demonstrates the use of the Catena FSM class to implement the `Turns
 
 ## Release History
 
+- HEAD includes the following changes
+
+  - fix [#270](https://github.com/mcci-catena/Catena-Arduino-Platform/issues/270): add sigfox support and commands to configure using Serial terminal. (Version 0.20.1.10.)
+
 - v0.20.1 includes the following changes.
 
-  - fix [#275](ttps://github.com/mcci-catena/Catena-Arduino-Platform/issues/275): add `cTotalizer::setDebounce()`, allowing the debounce time to be adjusted from 50ms. This can also be done in the constructor. (Version 0.20.0.30.)
+  - fix [#275](https://github.com/mcci-catena/Catena-Arduino-Platform/issues/275): add `cTotalizer::setDebounce()`, allowing the debounce time to be adjusted from 50ms. This can also be done in the constructor. (Version 0.20.0.30.)
   - fix [#279](https://github.com/mcci-catena/Catena-Arduino-Platform/issues/279): system could sleep forever if the beginning and end of a time range straddled the end of a month. Also fix [#280](https://github.com/mcci-catena/Catena-Arduino-Platform/issues/280), adding ability to set the time (version 0.20.0.20).
   - fix [#273](https://github.com/mcci-catena/Catena-Arduino-Platform/issues/273): in very low light conditions, with 24-bit measurements, Si1133 can generate negative light readings. Detect such values and force to zero (version 0.20.0.10).
 

src/Catena455x.h

@@ -65,6 +65,9 @@ class Catena455x : public CatenaStm32L0
 	// LoRaWAN binding
 	class LoRaWAN /* forward */;
 
+	// Sigfox binding
+	class Sigfox /* forward */;
+
 	enum ANALOG_PINS
 		{
 		APIN_VBAT_SENSE = A3,
@@ -108,6 +111,27 @@ class Catena455x::LoRaWAN : public CatenaStm32L0::LoRaWAN
 
 protected:
 
+private:
+	};
+
+/*
+|| The Sigfox class for the Catena 455x.
+*/
+class Catena455x::Sigfox : public CatenaStm32L0::Sigfox
+	{
+public:
+	using Super = CatenaStm32L0::Sigfox;
+
+	/*
+	|| the constructor. We don't do anything at this level, the
+	|| Super constructor does most of the work.
+	*/
+	Sigfox() {};
+
+	bool begin(Catena455x *pParent);
+
+protected:
+
 private:
 	};
 

src/Catena461x.h

@@ -69,6 +69,9 @@ class Catena461x : public CatenaStm32L0
 	// LoRaWAN binding
 	class LoRaWAN /* forward */;
 
+	// Sigfox binding
+	class Sigfox /* forward */;
+
 	enum ANALOG_PINS
 		{
 		APIN_VBAT_SENSE = A3,
@@ -122,6 +125,27 @@ class Catena461x::LoRaWAN : public CatenaStm32L0::LoRaWAN
 
 protected:
 
+private:
+	};
+
+/*
+|| The Sigfox class for the Catena 461x.
+*/
+class Catena461x::Sigfox : public CatenaStm32L0::Sigfox
+	{
+public:
+	using Super = CatenaStm32L0::Sigfox;
+
+	/*
+	|| the constructor. We don't do anything at this level, the
+	|| Super constructor does most of the work.
+	*/
+	Sigfox() {};
+
+	bool begin(Catena461x *pParent);
+
+protected:
+
 private:
 	};
 

src/Catena463x.h

@@ -44,6 +44,9 @@ class Catena463x : public CatenaStm32L0
 	// LoRaWAN binding
 	class LoRaWAN /* forward */;
 
+	// Sigfox binding
+	class Sigfox /* forward */;
+
 	enum ANALOG_PINS
 		{
 		APIN_VBAT_SENSE = A1,
@@ -97,6 +100,27 @@ class Catena463x::LoRaWAN : public CatenaStm32L0::LoRaWAN
 
 protected:
 
+private:
+	};
+
+/*
+|| The Sigfox class for the Catena 463x.
+*/
+class Catena463x::Sigfox : public CatenaStm32L0::Sigfox
+	{
+public:
+	using Super = CatenaStm32L0::Sigfox;
+
+	/*
+	|| the constructor. We don't do anything at this level, the
+	|| Super constructor does most of the work.
+	*/
+	Sigfox() {};
+
+	bool begin(Catena463x *pParent);
+
+protected:
+
 private:
 	};
 

src/Catena480x.h

@@ -67,6 +67,9 @@ class Catena480x : public CatenaStm32L0
 	// LoRaWAN binding
 	class LoRaWAN /* forward */;
 
+	// Sigfox binding
+	class Sigfox /* forward */;
+
 	enum ANALOG_PINS
 		{
 		APIN_VBAT_SENSE = A0,	/* for 4802 it is referred as VIN */
@@ -120,6 +123,27 @@ class Catena480x::LoRaWAN : public CatenaStm32L0::LoRaWAN
 
 protected:
 
+private:
+	};
+
+/*
+|| The Sigfox class for the Catena 480x.
+*/
+class Catena480x::Sigfox : public CatenaStm32L0::Sigfox
+	{
+public:
+	using Super = CatenaStm32L0::Sigfox;
+
+	/*
+	|| the constructor. We don't do anything at this level, the
+	|| Super constructor does most of the work.
+	*/
+	Sigfox() {};
+
+	bool begin(Catena480x *pParent);
+
+protected:
+
 private:
 	};
 

src/CatenaBase.h

@@ -47,6 +47,10 @@ Copyright notice:
 
 #include <Arduino_LoRaWAN.h>
 
+#ifdef ARDUINO_ARCH_STM32
+#include <Catena_Sigfox_wapper.h>
+#endif
+
 #if ! (defined(ARDUINO_LORAWAN_VERSION_COMPARE_LT) && \
         ! ARDUINO_LORAWAN_VERSION_COMPARE_LT(ARDUINO_LORAWAN_VERSION, ARDUINO_LORAWAN_VERSION_CALC(0,9,0,2)))
 # error Arduino_LoRaWAN library is out of date. Check ARDUINO_LORAWAN_VERSION.
@@ -320,6 +324,11 @@ class CatenaBase
 
         bool addLoRaWanCommands(void);
 
+#ifdef ARDUINO_ARCH_STM32
+        bool GetSigfoxConfiguringInfo(MCCI_Catena_Sigfox::SigfoxConfiguringInfo *);
+        bool addSigfoxCommands(void);
+#endif
+
         // calibrate the system clock, if possible
         virtual uint32_t CalibrateSystemClock(void)
                 {

src/CatenaStm32L0.h

@@ -40,6 +40,9 @@ static_assert(
         "ARDUINO_LORAWAN_VERSION must be at least 0.9.0-1"
         );
 
+#ifdef ARDUINO_ARCH_STM32
+#include <Catena_Sigfox_wapper.h>
+
 namespace McciCatena {
 
 class CatenaStm32L0 : public CatenaStm32
@@ -53,6 +56,9 @@ class CatenaStm32L0 : public CatenaStm32
         // forward reference
         class LoRaWAN;
 
+	// Sigfox binding
+	class Sigfox /* forward */;
+
         // start the Stm32L0 level
         virtual bool begin(void) override;
 
@@ -174,6 +180,37 @@ class CatenaStm32L0::LoRaWAN : public Arduino_LoRaWAN_network,
         CatenaStm32L0           *m_pCatena;
         };
 
+class CatenaStm32L0::Sigfox : public MCCI_Catena_Sigfox,
+                               public McciCatena::cPollableObject
+        {
+public:
+        using Super = MCCI_Catena_Sigfox;
+
+        /*
+        || the constructor.
+        */
+        Sigfox() {};
+
+        /*
+        || the begin function loads data from the local
+        || platform's stable storage and initializes
+        || the connection.
+        */
+        virtual bool begin(CatenaStm32L0 *pCatena);
+
+        virtual void poll() { this->Super::loop(); };
+
+protected:
+        /*
+        || we have to provide these for the lower level
+        */
+        virtual bool GetSigfoxConfiguringInfo(
+                        MCCI_Catena_Sigfox::SigfoxConfiguringInfo *
+                        ) override;
+private:
+        CatenaStm32L0           *m_pCatena;
+        };
+
 // this function is called from a trampoline C function that
 // needs to invoke analog reads for checking USB presence.
 bool CatenaStm32L0_ReadAnalog(
@@ -185,5 +222,7 @@ bool CatenaStm32L0_ReadAnalog(
 
 } // namespace McciCatena
 
+#endif // ARDUINO_ARCH_STM32
+
 /**** end of CatenaStm32L0.h ****/
 #endif /* _CATENASTM32L0_H_ */

src/Catena_FramStorage.h

@@ -49,6 +49,11 @@ class cFramStorage
                 kBme680Cal = 16,
                 kAppConf = 17,
                 kLmicSessionState = 18,
+                kDevID = 19,
+                kPAC = 20,
+                kKey = 21,
+                kRegion = 22,
+                kEncryption = 23,
                 // when you add something, also update McciCatena::cFramStorage::vItemDefs[]!
                 kMAX
                 };