Add sketch name, description; enhance versioning

src/Catena.h

@@ -90,12 +90,23 @@ class Catena : public CATENA_H_SUPER_
 	///
 	/// \brief the constructor sets the version, if one is supplied.
 	///
-	/// \param[in] appVersion, if supplied is an McciCatena::Version_t
+	/// \param[in] appVersion, if supplied, is an McciCatena::Version_t
 	///	object which specifies the version of the application.
 	///
-        Catena(Version_t appVersion = Version_t(0))
+	/// \param[in] pFileName, if specified, should be \c __FILE__,
+	///	the name of the input .ino file.  The directory portion
+	///	will be stripped.
+	///
+	/// \param[in] pSketchDescription, if specified, is a one-line description
+	///	of the sketch.
+	///
+        Catena(Version_t appVersion = Version_t(0), const char *pFileName = nullptr, const char *pSketchDescription = nullptr)
 		{
 		this->setAppVersion(appVersion);
+		if (pFileName != nullptr)
+			this->setSketchName(Catena::getBaseFileName(pFileName));
+		if (pSketchDescription != nullptr)
+			this->setSketchDescription(pSketchDescription);
 		}
 
 	// neither copyable nor movable
@@ -251,6 +262,8 @@ class Catena : public CATENA_H_SUPER_
 private:
 	/// \brief local routine to isolate the flash / download setup.
 	bool setup_flash(void);
+	/// \brief local routine to display the sign-on banner
+	bool setup_banner(void);
 	};
 
 } // namespace McciCatena

src/CatenaBase.h

@@ -72,7 +72,7 @@ Copyright notice:
 /// \sa CATENA_ARDUINO_PLATFORM_VERSION_COMPARE_LT()
 ///
 #define CATENA_ARDUINO_PLATFORM_VERSION \
-        CATENA_ARDUINO_PLATFORM_VERSION_CALC(0, 23, 0, 1) /* v0.23.0-pre1 */
+        CATENA_ARDUINO_PLATFORM_VERSION_CALC(0, 23, 0, 2) /* v0.23.0-pre2 */
 
 /// \brief extract major number from a version code
 #define CATENA_ARDUINO_PLATFORM_VERSION_GET_MAJOR(v)    \
@@ -157,6 +157,9 @@ class Version_t
                 return (uint32_t(major) << 24) | (uint32_t(minor) << 16) | (uint32_t(patch << 8)) | prerelease;
                 }
 
+        /// \brief the size of a text version (without leading 'v', with trailing null)
+        static constexpr size_t kVersionBufferSize = sizeof("255.255.255-pre255");
+
         /// \brief construct a \c Version_t object from parts
         constexpr Version_t(uint8_t major, uint8_t minor, uint8_t patch, uint8_t prerelease = 0)
                 : m_version(makeVersion(major, minor, patch, prerelease)) {}
@@ -204,17 +207,21 @@ class Version_t
                 return uint8_t(this->m_version >> 8);
                 }
 
-        /// \breif return the Semantic Version pre-release from a \c Version_t value.
+        /// \brief return the Semantic Version pre-release from a \c Version_t value.
         constexpr uint8_t getPrerelease() const
                 {
                 return uint8_t(this->m_version >> 0);
                 }
 
+        /// \brief test whether a version is a pre-release
         constexpr bool isPrerelease() const
                 {
                 return this->getPrerelease() != 0;
                 }
 
+        /// \brief build a version string in a buffer
+        size_t toBuffer(char *pBuffer, size_t nBuffer) const;
+
 private:
         uint32_t m_version;     ///< the encoded version number
         };
@@ -1374,6 +1381,26 @@ class CatenaBase
                 return this->m_appVersion;
                 }
 
+        ///
+        /// \brief return the sketch filename
+        ///
+        /// \return name of sketch, or \c nullptr if not set.
+        ///
+        const char *getSketchName() const
+                {
+                return this->m_pSketchName;
+                }
+
+        ///
+        /// \brief return the sketch description
+        ///
+        /// \return description of sketch, or \c nullptr if not set.
+        ///
+        const char *getSketchDescription() const
+                {
+                return this->m_pSketchDescription;
+                }
+
         ///
         /// \brief delay n millis while polling
         ///
@@ -1387,11 +1414,27 @@ class CatenaBase
 
 protected:
         /// \brief set the application version
-        void setAppVersion(Version_t v)
+        inline void setAppVersion(Version_t v)
                 {
                 this->m_appVersion = v;
                 }
 
+        /// \brief set the sketch name
+        ///
+        /// \note this caches a reference to \param pName.
+        inline void setSketchName(const char *pName)
+                {
+                this->m_pSketchName = pName;
+                }
+
+        /// \brief set the sketch description
+        ///
+        /// \note this caches a reference to \param pDesc.
+        inline void setSketchDescription(const char *pDesc)
+                {
+                this->m_pSketchDescription = pDesc;
+                }
+
         /// \brief register the well-known system commands
         virtual void registerCommands(void);
 
@@ -1451,6 +1494,9 @@ class CatenaBase
         uint32_t                m_OperatingFlags;       ///< the operating flags
         const CATENA_PLATFORM * m_pPlatform;            ///< the platform pointer
         Version_t               m_appVersion {0};       ///< the application version
+        const char *            m_pSketchName {nullptr};        ///< the file name of the sketch
+        const char *            m_pSketchDescription {nullptr}; ///< the application description
+
 
         // internal methods
 

src/lib/CatenaBase_registerCommands.cpp

@@ -325,18 +325,24 @@ printVersion(
 	bool fSemantic = false
 	)
 	{
-	const char cSemantic = fSemantic ? '-' : '.';
+	const Version_t v(packedVersion);
 
-	pThis->printf("%s-Version: %d.%d.%d%c",
+	pThis->printf("%s: %d.%d.%d",
 		pLabel,
-		(packedVersion >> 24) & 0xFF,
-		(packedVersion >> 16) & 0xFF,
-		(packedVersion >> 8) & 0xFF,
-		(packedVersion & 0xFF) ? cSemantic : '\n'
+		v.getMajor(),
+		v.getMinor(),
+		v.getPatch()
 		);
 
-	if (packedVersion & 0xFF)
-		pThis->printf("%d\n", packedVersion & 0xFF);
+	if (v.isPrerelease())
+		{
+		if (fSemantic)
+			pThis->printf("-pre%d", v.getPrerelease());
+		else
+			pThis->printf(".%d", v.getPrerelease());
+		}
+
+	pThis->printf("\n");
 	}
 
 /* Older versions of MCCI ADK don't have a version. Accomodate that. */
@@ -362,17 +368,25 @@ doVersion(
 		}
 
 	pThis->printf("Board: %s\n", pCatena->CatenaName());
-	printVersion(pThis, "Platform", CATENA_ARDUINO_PLATFORM_VERSION, true);
-	printVersion(pThis, "Arduino-LoRaWAN", ARDUINO_LORAWAN_VERSION, true);
-	printVersion(pThis, "Arduino-LMIC", ARDUINO_LMIC_VERSION);
-	printVersion(pThis, "MCCIADK", mcciadk_version);
+
+	// print sketch name & version if defined.
+	do	{
+		auto const pSketchName = pCatena->getSketchName();
+		if (pSketchName != nullptr)
+			printVersion(pThis, pSketchName, pCatena->getAppVersion().getUint32(), true);
+		} while (0);
 
 	/* include the MCCI Arduino version, if known */
 	if (pCatena->kMcciArduinoVersion != 0)
 		printVersion(pThis, "MCCI-Arduino-BSP", pCatena->kMcciArduinoVersion,
 			pCatena->kMcciArduinoVersionIsSemantic
 			);
 
+	printVersion(pThis, "Catena-Arduino-Platform", CATENA_ARDUINO_PLATFORM_VERSION, true);
+	printVersion(pThis, "Arduino-LoRaWAN", ARDUINO_LORAWAN_VERSION, true);
+	printVersion(pThis, "Arduino-LMIC", ARDUINO_LMIC_VERSION, true);
+	printVersion(pThis, "MCCIADK", mcciadk_version);
+
 	return cCommandStream::CommandStatus::kSuccess;
 	}
 

src/lib/Catena_setup.cpp

@@ -180,6 +180,7 @@ Catena::setup(
         }
 
     Serial.begin(115200);
+    this->setup_banner();
 
 #if CATENA_PLATFORM_HAS_DOWNLOAD
     /* add our application-specific commands */
@@ -210,6 +211,39 @@ Catena::setup(
 
 #undef FUNCTION
 
+bool Catena::setup_banner(void)
+    {
+    auto const putDashes = [this](unsigned n=79) -> void
+        {
+        for (unsigned i = 0; i < n; ++i)
+            this->SafePrintf("-");
+        this->SafePrintf("\n");
+        };
+
+    char sVersion[Version_t::kVersionBufferSize];
+    this->getAppVersion().toBuffer(sVersion, sizeof(sVersion));
+
+    auto const pSketchName = this->getSketchName();
+    auto const pSketchDescription = this->getSketchDescription();
+
+    putDashes(0);   // newline
+    putDashes();
+
+    this->SafePrintf("This is %s V%s.\n", pSketchName ? pSketchName : "<unknown sketch>", sVersion);
+    if (pSketchDescription != nullptr)
+        this->SafePrintf("%s\n", pSketchDescription);
+
+        this->SafePrintf("Board: %s  SYSCLK: %u MHz  USB: %sabled\n",
+                            this->CatenaName(),
+                            unsigned(this->GetSystemClockRate() / (1000 * 1000)),
+                            this->get_consoleIsUsb() ? "en" : "dis"
+                        );
+        this->SafePrintf("Enter 'help' for a list of commands.\n");
+
+    putDashes();
+    putDashes(0);    // newline
+    }
+
 bool Catena::setup_flash(void)
     {
     this->set_flashFound(false);

src/lib/Version_t_toBuffer.cpp

@@ -0,0 +1,80 @@
+/*
+
+Module:	Version_t_toBuffer.cpp
+
+Function:
+    McciCatena::Version_t::toBuffer()
+
+Copyright and License:
+    This file copyright (C) 2021 by
+
+        MCCI Corporation
+        3520 Krums Corners Road
+        Ithaca, NY  14850
+
+    See accompanying LICENSE file for copyright and license information.
+
+Author:
+    Terry Moore, MCCI Corporation	December 2021
+
+*/
+
+#include <CatenaBase.h>
+
+size_t
+McciCatena::Version_t::toBuffer(char *pBuffer, size_t nBuffer) const
+    {
+    if (pBuffer == nullptr || nBuffer == 0)
+        return 0;
+
+    if (nBuffer < kVersionBufferSize)
+        {
+        pBuffer[0] = '\0';
+        return 0;
+        }
+
+    // local function to put an 8-bit field
+    size_t i = 0;
+    auto const putbyte = [pBuffer, nBuffer, &i](char c) -> void
+        {
+        if (i < nBuffer)
+            pBuffer[i] = c;
+        ++i;
+        };
+    auto const putfield = [&putbyte](uint8_t v) -> void
+        {
+        auto temp = v;
+        if (v >= 100)
+            {
+            putbyte('0' + temp / 100);
+            temp %= 100;
+            }
+        if (v >= 10)
+            {
+            putbyte('0' + temp / 10);
+            temp %= 10;
+            }
+        putbyte('0' + temp);
+        };
+
+    putfield(this->getMajor());
+    putbyte('.');
+    putfield(this->getMinor());
+    putbyte('.');
+    putfield(this->getPatch());
+    if (this->isPrerelease())
+        {
+        putbyte('-');
+        putbyte('p');
+        putbyte('r');
+        putbyte('e');
+        putfield(this->getPrerelease());
+        }
+    putbyte('\0');
+
+    // if we might have overflowed the buffer, set the terminator.
+    if (i > nBuffer - 1)
+        pBuffer[nBuffer-1] = '\0';
+
+    return i;
+    }