0.3.0

- Added the feature that an app can be hidden; the `hide` commands toggles.
- The voidapp no longer is hardwired hidden; it uses the new hidden feature.
- Corrected `swflags` to `swflag`.
- Fixed prefix error in `aoapps_swflag.cpp`.
- Fixed documentation error for `aoapps_init()`.

Author: Maarten Pennings

library.properties

@@ -1,5 +1,5 @@
 name=OSP ReusableApps aoapps
-version=0.2.10
+version=0.3.0
 author=ams-OSRAM
 maintainer=ams-OSRAM
 sentence=A library with reusable "apps" for OSP chains.

readme.md

@@ -42,6 +42,9 @@ void apps_register() {
 void setup() {
   ...
 
+  // Init the Library
+  aoapps_init();
+  
   // Register all apps
   apps_register();
 
@@ -155,7 +158,7 @@ The headers contain little documentation; for that see the module source files.
 
 ### aoapps
 
-- `aoapps_init()` not really needed, but added for forward compatibility.
+- `aoapps_init()` to initialize the library (the apps manager).
 - `AOAPPS_VERSION`  identifies the version of the library.
 
 
@@ -169,8 +172,9 @@ An important aspect of the app manager is app registration.
   its start, step an stop functions, an optional command handler, and some flags).
 - `aoapps_mngr_start_t`, `aoapps_mngr_step_t`, `aoapps_mngr_stop_t` types for
   to start, step and stop function.
-- `AOAPPS_MNGR_FLAGS_WITHTOPO`, `AOAPPS_MNGR_FLAGS_WITHREPAIR` and 
-  `AOAPPS_MNGR_FLAGS_NEXTONERR` registration flags.
+- `AOAPPS_MNGR_FLAGS_HIDDEN`, `AOAPPS_MNGR_FLAGS_WITHTOPO`, 
+  `AOAPPS_MNGR_FLAGS_WITHREPAIR` and `AOAPPS_MNGR_FLAGS_NEXTONERR` 
+  registration flags.
 - `AOAPPS_MNGR_REGISTRATION_SLOTS` maximum number of apps that can 
   be registered.
 
@@ -269,6 +273,13 @@ the app manager will, when that app returns an error, do as before (stop
 heart beat, switch on red LED, show error on OLED), but after a time-out start
 the next app.
 
+The list of registered apps can become long. For a specific demo, apps
+can be hidden, so that the demonstration can focus on specific apps. 
+When an app is hidden, it is skipped in the `switchnext()` cycle, which is 
+typically executed when pressing the A button. The voidapp registers itself 
+as hidden, for other apps hide them via the command `apps hide <app>`, 
+e.g. in `boot.cmd`.
+
 Some apps have configuration parameters that can be observed and changed via
 a command. The command handler can also be passed during app registration, 
 see the next chapter.
@@ -281,7 +292,8 @@ This module also implements a command `apps` (to be registered with
 
 - show a list of all registered apps
 - switch to a different app
-- configure an app
+- configure an app as hidden
+- configure an app via its handler
 
 If an individual app has something to configure, its shall pass its 
 configuration handler (just another command handler) during its registration 
@@ -335,7 +347,7 @@ the `boot.cmd` which is executed at startup, for example:
 
 The app manager has one app always registered, the "voidapp". This app
 does nothing. It does not start with topo init, its start, step and stop 
-are empty, and it does not deploy repair actions.
+are empty, and it does not deploy repair actions, but it is hidden by default.
 
 This app is useful when the user wants to take over control via the
 Serial over USB command interface. If the user gives the command
@@ -349,6 +361,13 @@ of the OSP chain, without app telegrams interfering.
 
 ## Version history _aoapps_
 
+- **2025 March 3, 0.3.0**
+  - Added the feature that an app can be hidden; the `hide` commands toggles.
+  - The voidapp no longer is hardwired hidden; it uses the new hidden feature.
+  - Corrected `swflags` to `swflag`.
+  - Fixed prefix error in `aoapps_swflag.cpp`.
+  - Fixed documentation error for `aoapps_init()`.
+
 - **2024 November 29, 0.2.10**
   - Fixed typos (including I/O-expander).
 

src/aoapps.h

@@ -23,7 +23,7 @@
 
 
 // Identifies lib version
-#define AOAPPS_VERSION "0.2.10"
+#define AOAPPS_VERSION "0.3.0"
 
 
 // Include the (headers of the) modules of this app

src/aoapps_mngr.cpp

@@ -27,8 +27,8 @@
 
 
 // === voidapp ===============================================================
-// The void app, doing nothing, allowing unhindered USB commands
-// It is always registered (in init), but not part of switchnext()
+// The voidapp, doing nothing, allowing unhindered USB commands
+// It is always registered (in init), but hidden, ie not part of switchnext()
 
 
 static aoresult_t aoapps_mngr_voidapp_start() { 
@@ -48,7 +48,7 @@ static void aoapps_mngr_voidapp_stop () {
 
 void aoapps_mngr_voidapp_register() {
   aoapps_mngr_register("voidapp", "USB command", "--", "--", 
-    0, /* no dither, no repair */
+    AOAPPS_MNGR_FLAGS_HIDDEN, 
     aoapps_mngr_voidapp_start, aoapps_mngr_voidapp_step, aoapps_mngr_voidapp_stop, 
     0, 0 /* no config command */ );
 }
@@ -362,8 +362,8 @@ void aoapps_mngr_stop() {
             0 <= appix < aoapps_mngr_app_count()
     @note   It is an error when the current app is "stop" (must be "run").
     @note   See `aoapps_mngr_start()` for start/stop/current/appix terminology.
-    @note   aoapps_mngr_switch(0) will select the voidapp; the function
-            aoapps_mngr_switchnext() skips the voidapp.
+    @note   `aoapps_mngr_switch(0)` will select the voidapp like any other hidden 
+	        app; the function `aoapps_mngr_switchnext()` skips them.
     @note   See `aoapps_mngr_switchnext()`.
 */            
 void aoapps_mngr_switch(int appix) {
@@ -374,13 +374,18 @@ void aoapps_mngr_switch(int appix) {
 
 /*!
     @brief  Stops the current app and starts the next one.
-    @note   The next one in the sense of appix (registration order).
-    @note   Wraps around to appix 1 (so skips voidapp).
+    @note   The "next one" is in the sense of registration order.
+    @note   Wraps around, and skips apps that have their hidden flag set.
+    @note   If all apps are hidden does nothing (stays at app).
     @note   It is an error when the current app is "stop" (must be "run").
     @note   See `aoapps_mngr_start()` for start/stop/current/appix terminology.
 */            
 void aoapps_mngr_switchnext() {
-  aoapps_mngr_switch( aoapps_mngr_appix % (aoapps_mngr_count-1) + 1);
+  int appix= aoapps_mngr_appix;
+  do {
+    appix= (appix+1) % aoapps_mngr_count;
+  } while( (aoapps_mngr_apps[appix].flags & AOAPPS_MNGR_FLAGS_HIDDEN) &&  (appix!=aoapps_mngr_appix) );
+  if( appix!=aoapps_mngr_appix ) aoapps_mngr_switch(appix);
 }
 
 
@@ -476,7 +481,7 @@ static aoresult_t aoapps_mngr_stepwithtopo() {
         if( aoapps_mngr_error!=aoresult_ok ) aoapps_mngr_state= AOAPPS_MNGR_STATE_ERROR;
         return aoresult_ok; // loop topo build
       }
-      Serial.printf("%s: starting on %d RGBs\n", aoapps_mngr_apps[aoapps_mngr_appix].name, aomw_topo_numtriplets() );
+      // Serial.printf("%s: starting on %d RGBs\n", aoapps_mngr_apps[aoapps_mngr_appix].name, aomw_topo_numtriplets() );
       aoapps_mngr_error= aoapps_mngr_apps[aoapps_mngr_appix].start(); // call start of app
       if( aoapps_mngr_error!=aoresult_ok ) aoapps_mngr_state= AOAPPS_MNGR_STATE_ERROR;
       aoapps_mngr_state= AOAPPS_MNGR_STATE_APPANIM;
@@ -555,12 +560,13 @@ static void aoapps_mngr_cmd_listone(int appix) {
   if( appix!=cur ) mode= "stop";
   else if( run ) mode= "run"; 
   else mode= "idle";
-  char flags[4]="tre";
-  if( aoapps_mngr_apps[appix].flags & AOAPPS_MNGR_FLAGS_WITHTOPO   ) flags[0]='T';
-  if( aoapps_mngr_apps[appix].flags & AOAPPS_MNGR_FLAGS_WITHREPAIR ) flags[1]='R';
-  if( aoapps_mngr_apps[appix].flags & AOAPPS_MNGR_FLAGS_NEXTONERR  ) flags[2]='E';
+  char flags[]="htre";
+  if( aoapps_mngr_apps[appix].flags & AOAPPS_MNGR_FLAGS_HIDDEN     ) flags[0]='H';
+  if( aoapps_mngr_apps[appix].flags & AOAPPS_MNGR_FLAGS_WITHTOPO   ) flags[1]='T';
+  if( aoapps_mngr_apps[appix].flags & AOAPPS_MNGR_FLAGS_WITHREPAIR ) flags[2]='R';
+  if( aoapps_mngr_apps[appix].flags & AOAPPS_MNGR_FLAGS_NEXTONERR  ) flags[3]='E';
   const char* oled= aoapps_mngr_app_oled(appix);
-  Serial.printf("%d %-10s %-4s %-5s %s\n",appix,name,mode,flags,oled);
+  Serial.printf("%1d %-10s %-4s %-5s %s\n",appix,name,mode,flags,oled);
 }
 
 
@@ -569,7 +575,7 @@ static void aoapps_mngr_cmd_listall(int verbose) {
   if( verbose ) Serial.printf("# %-10s %-4s %5s %s\n","name","mode","flags","display name");
   for( int appix=0; appix<aoapps_mngr_app_count(); appix++ ) 
     aoapps_mngr_cmd_listone(appix);
-  if( verbose ) Serial.printf("\nflags: T=withtopo R=withrepair, E=nextonerr\n");
+  if( verbose ) Serial.printf("\nflags: H=hidden T=withtopo R=withrepair, E=nextonerr\n");
 }
 
 
@@ -582,7 +588,7 @@ static void aoapps_mngr_cmd( int argc, char * argv[] ) {
     if( argc!=2 ) { Serial.printf("ERROR: too many args\n" ); return; }
     aoapps_mngr_cmd_listall(argv[0][0]!='@');
     return;
-  } else if( aocmd_cint_isprefix("switch",argv[1]) ) {
+  } else if( aocmd_cint_isprefix("switch",argv[1]) || aocmd_cint_isprefix("hide",argv[1])) {
     if( argc!=3 ) { Serial.printf("ERROR: <app> missing\n" ); return; }
     // <app> is number?
     int appix;
@@ -601,8 +607,15 @@ static void aoapps_mngr_cmd( int argc, char * argv[] ) {
       }
     }
     if( appix==-1 ) { Serial.printf("ERROR: no app with name starting with '%s'\n",argv[2] ); return; }
-    aoapps_mngr_switch(appix);
-    if( argv[0][0]!='@' ) aoapps_mngr_cmd_listone(appix);
+    if( aocmd_cint_isprefix("switch",argv[1]) ) {
+      aoapps_mngr_switch(appix);
+      if( argv[0][0]!='@' ) aoapps_mngr_cmd_listone(appix);
+    } else if( aocmd_cint_isprefix("hide",argv[1]) ) {      
+      aoapps_mngr_apps[appix].flags ^= AOAPPS_MNGR_FLAGS_HIDDEN; // toggle hidden flag
+      if( argv[0][0]!='@' ) aoapps_mngr_cmd_listone(appix);
+    } else {
+      AORESULT_ASSERT(false); // can not happen
+    }
     return;
   } else if( aocmd_cint_isprefix("config",argv[1]) ) {
     aoapps_mngr_cmd_config(argc,argv);
@@ -621,6 +634,8 @@ static const char aoapps_mngr_cmd_longhelp[] =
   "- stops current app and starts <app>\n"
   "- <app> is either a name or an id (see list)\n"
   "- <app> 0 is the 'voidapp' (doing nothing): no interference with commands\n"
+  "SYNTAX: apps hide <app>\n"
+  "- toggles hide-flag of <app>; a hidden app is skipped in 'switchnext' list\n"
   "SYNTAX: apps config [...]\n"
   "- without arguments, shows which apps offer configuration\n"
   "- with app name shows help for configuration of that app\n"
@@ -630,6 +645,8 @@ static const char aoapps_mngr_cmd_longhelp[] =
 ;
 
 
+
+
 /*!
     @brief  Registers the "apps" command with the command interpreter.
     @return Number of remaining registration slots (or -1 if registration failed).

src/aoapps_mngr.h

@@ -39,10 +39,11 @@ typedef void       (*aoapps_mngr_cmd_t)( int argc, char * argv[] );
 
 // Extra features can be enabled in the app manager
 #define AOAPPS_MNGR_FLAGS_NONE        0x00
-#define AOAPPS_MNGR_FLAGS_WITHTOPO    0x01
-#define AOAPPS_MNGR_FLAGS_WITHREPAIR  0x02
-#define AOAPPS_MNGR_FLAGS_NEXTONERR   0x04
-#define AOAPPS_MNGR_FLAGS_ALL         (AOAPPS_MNGR_FLAGS_WITHTOPO | AOAPPS_MNGR_FLAGS_WITHREPAIR | AOAPPS_MNGR_FLAGS_NEXTONERR ) 
+#define AOAPPS_MNGR_FLAGS_HIDDEN      0x01
+#define AOAPPS_MNGR_FLAGS_WITHTOPO    0x02
+#define AOAPPS_MNGR_FLAGS_WITHREPAIR  0x04
+#define AOAPPS_MNGR_FLAGS_NEXTONERR   0x08
+#define AOAPPS_MNGR_FLAGS_ALL         (AOAPPS_MNGR_FLAGS_HIDDEN | AOAPPS_MNGR_FLAGS_WITHTOPO | AOAPPS_MNGR_FLAGS_WITHREPAIR | AOAPPS_MNGR_FLAGS_NEXTONERR ) 
 
 // To register an app pass its (identifier and oled) name, help text for the two buttons, feature flags, pointers to its three handlers, command handler and command help. Asserts when no more free slots.
 void aoapps_mngr_register(const char * name, const char * oled, const char * xlbl, const char * ylbl, int flags, aoapps_mngr_start_t start, aoapps_mngr_step_t step, aoapps_mngr_stop_t stop, aoapps_mngr_cmd_t cmd, const char * help);  

src/aoapps_swflag.cpp

@@ -55,8 +55,8 @@ GOAL
 
 
 // We have a list of flag painters (indices)
-#define AOMW_SWFLAGS_ANIM_NUMFLAGS 4 // dictated by number of buttons in IOX
-static int aomw_swflags_anim_pix[AOMW_SWFLAGS_ANIM_NUMFLAGS] = { 
+#define AOAPPS_SWFLAG_ANIM_NUMFLAGS 4 // dictated by number of buttons in IOX
+static int aomw_swflag_anim_pix[AOAPPS_SWFLAG_ANIM_NUMFLAGS] = { 
   AOMW_FLAG_PIX_DUTCH, AOMW_FLAG_PIX_MALI, AOMW_FLAG_PIX_EUROPE, AOMW_FLAG_PIX_ITALY 
 };
 
@@ -88,15 +88,15 @@ static aoresult_t aoapps_swflag_anim() {
     // IOX absent: switch flags every AOAPPS_SWFLAG_ANIM_MS
     if( millis()-aoapps_swflag_anim_lastms > AOAPPS_SWFLAG_ANIM_MS ) {
       aoapps_swflag_anim_lastms= millis();
-      flagix= (aoapps_swflag_anim_flagix+1) % AOMW_SWFLAGS_ANIM_NUMFLAGS;
+      flagix= (aoapps_swflag_anim_flagix+1) % AOAPPS_SWFLAG_ANIM_NUMFLAGS;
     }
   }
 
   // Different flag selected? Paint it
   if( aoapps_swflag_anim_flagix!=flagix ) {
     aoapps_swflag_anim_flagix = flagix;
     // Paint the flag 
-    result= aomw_flag_painter(aomw_swflags_anim_pix[aoapps_swflag_anim_flagix])();
+    result= aomw_flag_painter(aomw_swflag_anim_pix[aoapps_swflag_anim_flagix])();
     if( result!=aoresult_ok ) return result;
     // Highlight the associated indicator LED
     if( aoapps_swflag_anim_ioxpresent ) {
@@ -130,7 +130,7 @@ static aoresult_t aoapps_swflag_buttons_check() {
     aomw_topo_dim_set(dim); // function clips (no need to do that here)
     // Serial.printf("dim %d\n", aomw_topo_dim_get());
     // Repaint the flag 
-    aoresult_t result= aomw_flag_painter(aomw_swflags_anim_pix[aoapps_swflag_anim_flagix])();
+    aoresult_t result= aomw_flag_painter(aomw_swflag_anim_pix[aoapps_swflag_anim_flagix])();
     if( result!=aoresult_ok ) return result;
   }
   return aoresult_ok;
@@ -154,37 +154,37 @@ static int aoapps_swflag_cmd_find( const char * flag ) {
 
 // Show on Serial which are the four flags
 static void aoapps_swflag_cmd_show( ) {
-  for( int flagix=0; flagix<AOMW_SWFLAGS_ANIM_NUMFLAGS; flagix++ ) {
-    Serial.printf("SW%d %s\n", flagix, aomw_flag_name(aomw_swflags_anim_pix[flagix]) );
+  for( int flagix=0; flagix<AOAPPS_SWFLAG_ANIM_NUMFLAGS; flagix++ ) {
+    Serial.printf("SW%d %s\n", flagix, aomw_flag_name(aomw_swflag_anim_pix[flagix]) );
   }
 }
 
 
-// The handler for the "apps config swflags" command
+// The handler for the "apps config swflag" command
 static void aoapps_swflag_cmd_main( int argc, char * argv[] ) {
   AORESULT_ASSERT( argc>3 );
   if( aocmd_cint_isprefix("list",argv[3]) ) {
-    if( argc!=4 ) { Serial.printf("ERROR: 'swflags' has too many args\n" ); return; }
+    if( argc!=4 ) { Serial.printf("ERROR: 'swflag' has too many args\n" ); return; }
     for( int pix=0; pix<aomw_flag_count(); pix++ ) {
       Serial.printf(" %s\n", aomw_flag_name(pix) );
     }
     return;
   } else if( aocmd_cint_isprefix("get",argv[3]) ) {
-    if( argc!=4 ) { Serial.printf("ERROR: 'swflags' has too many args\n" ); return; }
+    if( argc!=4 ) { Serial.printf("ERROR: 'swflag' has too many args\n" ); return; }
     aoapps_swflag_cmd_show();
     return;
   } else if( aocmd_cint_isprefix("set",argv[3]) ) {
-    if( argc!=8 ) { Serial.printf("ERROR: 'swflags' expects <flag1> <flag2> <flag3> <flag4>\n" ); return; }
-    AORESULT_ASSERT( AOMW_SWFLAGS_ANIM_NUMFLAGS==4 );
+    if( argc!=8 ) { Serial.printf("ERROR: 'swflag' expects <flag1> <flag2> <flag3> <flag4>\n" ); return; }
+    AORESULT_ASSERT( AOAPPS_SWFLAG_ANIM_NUMFLAGS==4 );
     // check if all entered flags exist, if so, copy them over
     for( int flagix=0; flagix<4; flagix++ ) 
-      if( aoapps_swflag_cmd_find(argv[4+flagix])==-1 ) { Serial.printf("ERROR: 'swflags' expects flag name, not '%s'\n", argv[4+flagix] ); return; }
+      if( aoapps_swflag_cmd_find(argv[4+flagix])==-1 ) { Serial.printf("ERROR: 'swflag' expects flag name, not '%s'\n", argv[4+flagix] ); return; }
     for( int flagix=0; flagix<4; flagix++ ) 
-      aomw_swflags_anim_pix[flagix]= aoapps_swflag_cmd_find(argv[4+flagix]);
+      aomw_swflag_anim_pix[flagix]= aoapps_swflag_cmd_find(argv[4+flagix]);
     if( argv[0][0]!='@' ) aoapps_swflag_cmd_show();
     return;
   } else {
-    Serial.printf("ERROR: 'swflags' has unknown argument (%s)\n",argv[3] ); return;
+    Serial.printf("ERROR: 'swflag' has unknown argument (%s)\n",argv[3] ); return;
   }
 }
 
@@ -222,17 +222,17 @@ static aoresult_t aoapps_swflag_start() {
   aoapps_swflag_anim_ioxpresent= result==aoresult_ok;
   // Init IOX
   if( aoapps_swflag_anim_ioxpresent ) {
-    Serial.printf("swflags: using I/O-expander %02x on SAID %03x \n",AOMW_IOX_DADDR7,addr);
+    Serial.printf("swflag: using I/O-expander %02x on SAID %03x \n",AOMW_IOX_DADDR7,addr);
     result= aomw_iox_init( addr ); 
     if( result!=aoresult_ok ) return result;
   } else {
-    Serial.printf("swflags: no I/O-expander found, cycling flags\n");
+    Serial.printf("swflag: no I/O-expander found, cycling flags\n");
   }
 
   // Select first flag
   aoapps_swflag_anim_flagix= 0;
   // Paint the selected flag 
-  result= aomw_flag_painter(aomw_swflags_anim_pix[aoapps_swflag_anim_flagix])(); 
+  result= aomw_flag_painter(aomw_swflag_anim_pix[aoapps_swflag_anim_flagix])(); 
   if( result!=aoresult_ok ) return result;
   // Highlight the associated indicator LED
   if( aoapps_swflag_anim_ioxpresent ) {