introduce SCPI_HelpQ

add SCPI_HelpQ callback , optional .description strings and provide conditional initializer macros dependent on config settings for USE_COMMAND_TAGS and USE_COMMAND_DESCRIPTIONS.
j123b567 · MisterHW · Feb 1, 2022 · Feb 2, 2022 · Feb 3, 2022 · Feb 7, 2022
commit bc4f1d5069655e9166f09d84030f538a2c114cdb
diff --git a/examples/common/scpi-def.c b/examples/common/scpi-def.c
@@ -353,7 +353,22 @@ static scpi_result_t My_CoreTstQ(scpi_t * context) {
     return SCPI_RES_OK;
 }
 
+#if USE_COMMAND_DESCRIPTIONS
+#define SCPI_CMD_DESC(S) .description=(S),
+#else
+#define SCPI_CMD_DESC(S)
+#endif
+
+#if USE_COMMAND_TAGS
+#define SCPI_CMD_TAG(T) .tag=(T),
+#else
+#define SCPI_CMD_TAG(T)
+#endif
+
 const scpi_command_t scpi_commands[] = {
+    /* Optional help commmand */
+    {.pattern = "HELP?", .callback = SCPI_HelpQ, SCPI_CMD_DESC("\t - list supported commands")},
+
     /* IEEE Mandated Commands (SCPI std V1999.0 4.1.1) */
     { .pattern = "*CLS", .callback = SCPI_CoreCls,},
     { .pattern = "*ESE", .callback = SCPI_CoreEse,},

diff --git a/examples/common/scpi-def.cpp b/examples/common/scpi-def.cpp
@@ -353,60 +353,75 @@ static scpi_result_t My_CoreTstQ(scpi_t * context) {
     return SCPI_RES_OK;
 }
 
+#if USE_COMMAND_DESCRIPTIONS
+#define SCPI_CMD_DESC(S) (S),
+#else
+#define SCPI_CMD_DESC(S)
+#endif
+
+#if USE_COMMAND_TAGS
+#define SCPI_CMD_TAG(T) (T),
+#else
+#define SCPI_CMD_TAG(T)
+#endif
+
 const scpi_command_t scpi_commands[] = {
+    /* Optional help command */
+    {"HELP?", SCPI_HelpQ, SCPI_CMD_DESC("\t - list supported commands") SCPI_CMD_TAG(0)},
+
     /* IEEE Mandated Commands (SCPI std V1999.0 4.1.1) */
-    {"*CLS", SCPI_CoreCls, 0},
-    {"*ESE", SCPI_CoreEse, 0},
-    {"*ESE?", SCPI_CoreEseQ, 0},
-    {"*ESR?", SCPI_CoreEsrQ, 0},
-    {"*IDN?", SCPI_CoreIdnQ, 0},
-    {"*OPC", SCPI_CoreOpc, 0},
-    {"*OPC?", SCPI_CoreOpcQ, 0},
-    {"*RST", SCPI_CoreRst, 0},
-    {"*SRE", SCPI_CoreSre, 0},
-    {"*SRE?", SCPI_CoreSreQ, 0},
-    {"*STB?", SCPI_CoreStbQ, 0},
-    {"*TST?", My_CoreTstQ, 0},
-    {"*WAI", SCPI_CoreWai, 0},
+    {"*CLS", SCPI_CoreCls, SCPI_CMD_TAG(0)},
+    {"*ESE", SCPI_CoreEse, SCPI_CMD_TAG(0)},
+    {"*ESE?", SCPI_CoreEseQ, SCPI_CMD_TAG(0)},
+    {"*ESR?", SCPI_CoreEsrQ, SCPI_CMD_TAG(0)},
+    {"*IDN?", SCPI_CoreIdnQ, SCPI_CMD_TAG(0)},
+    {"*OPC", SCPI_CoreOpc, SCPI_CMD_TAG(0)},
+    {"*OPC?", SCPI_CoreOpcQ, SCPI_CMD_TAG(0)},
+    {"*RST", SCPI_CoreRst, SCPI_CMD_TAG(0)},
+    {"*SRE", SCPI_CoreSre, SCPI_CMD_TAG(0)},
+    {"*SRE?", SCPI_CoreSreQ, SCPI_CMD_TAG(0)},
+    {"*STB?", SCPI_CoreStbQ, SCPI_CMD_TAG(0)},
+    {"*TST?", My_CoreTstQ, SCPI_CMD_TAG(0)},
+    {"*WAI", SCPI_CoreWai, SCPI_CMD_TAG(0)},
 
     /* Required SCPI commands (SCPI std V1999.0 4.2.1) */
-    {"SYSTem:ERRor[:NEXT]?", SCPI_SystemErrorNextQ, 0},
-    {"SYSTem:ERRor:COUNt?", SCPI_SystemErrorCountQ, 0},
-    {"SYSTem:VERSion?", SCPI_SystemVersionQ, 0},
+    {"SYSTem:ERRor[:NEXT]?", SCPI_SystemErrorNextQ, SCPI_CMD_TAG(0)},
+    {"SYSTem:ERRor:COUNt?", SCPI_SystemErrorCountQ, SCPI_CMD_TAG(0)},
+    {"SYSTem:VERSion?", SCPI_SystemVersionQ, SCPI_CMD_TAG(0)},
 
-    //{"STATus:OPERation?", scpi_stub_callback, 0},
-    //{"STATus:OPERation:EVENt?", scpi_stub_callback, 0},
-    //{"STATus:OPERation:CONDition?", scpi_stub_callback, 0},
-    //{"STATus:OPERation:ENABle", scpi_stub_callback, 0},
-    //{"STATus:OPERation:ENABle?", scpi_stub_callback, 0},
+    //{"STATus:OPERation?", scpi_stub_callback, SCPI_CMD_TAG(0)},
+    //{"STATus:OPERation:EVENt?", scpi_stub_callback, SCPI_CMD_TAG(0)},
+    //{"STATus:OPERation:CONDition?", scpi_stub_callback, SCPI_CMD_TAG(0)},
+    //{"STATus:OPERation:ENABle", scpi_stub_callback, SCPI_CMD_TAG(0)},
+    //{"STATus:OPERation:ENABle?", scpi_stub_callback, SCPI_CMD_TAG(0)},
 
-    {"STATus:QUEStionable[:EVENt]?", SCPI_StatusQuestionableEventQ, 0},
-    //{"STATus:QUEStionable:CONDition?", scpi_stub_callback, 0},
-    {"STATus:QUEStionable:ENABle", SCPI_StatusQuestionableEnable, 0},
-    {"STATus:QUEStionable:ENABle?", SCPI_StatusQuestionableEnableQ, 0},
+    {"STATus:QUEStionable[:EVENt]?", SCPI_StatusQuestionableEventQ, SCPI_CMD_TAG(0)},
+    //{"STATus:QUEStionable:CONDition?", scpi_stub_callback, SCPI_CMD_TAG(0)},
+    {"STATus:QUEStionable:ENABle", SCPI_StatusQuestionableEnable, SCPI_CMD_TAG(0)},
+    {"STATus:QUEStionable:ENABle?", SCPI_StatusQuestionableEnableQ, SCPI_CMD_TAG(0)},
 
-    {"STATus:PRESet", SCPI_StatusPreset, 0},
+    {"STATus:PRESet", SCPI_StatusPreset, SCPI_CMD_TAG(0)},
 
     /* DMM */
-    {"MEASure:VOLTage:DC?", DMM_MeasureVoltageDcQ, 0},
-    {"CONFigure:VOLTage:DC", DMM_ConfigureVoltageDc, 0},
-    {"MEASure:VOLTage:DC:RATio?", SCPI_StubQ, 0},
-    {"MEASure:VOLTage:AC?", DMM_MeasureVoltageAcQ, 0},
-    {"MEASure:CURRent:DC?", SCPI_StubQ, 0},
-    {"MEASure:CURRent:AC?", SCPI_StubQ, 0},
-    {"MEASure:RESistance?", SCPI_StubQ, 0},
-    {"MEASure:FRESistance?", SCPI_StubQ, 0},
-    {"MEASure:FREQuency?", SCPI_StubQ, 0},
-    {"MEASure:PERiod?", SCPI_StubQ, 0},
-
-    {"SYSTem:COMMunication:TCPIP:CONTROL?", SCPI_SystemCommTcpipControlQ, 0},
-
-    {"TEST:BOOL", TEST_Bool, 0},
-    {"TEST:CHOice?", TEST_ChoiceQ, 0},
-    {"TEST#:NUMbers#", TEST_Numbers, 0},
-    {"TEST:TEXT", TEST_Text, 0},
-    {"TEST:ARBitrary?", TEST_ArbQ, 0},
-    {"TEST:CHANnellist", TEST_Chanlst, 0},
+    {"MEASure:VOLTage:DC?", DMM_MeasureVoltageDcQ, SCPI_CMD_TAG(0)},
+    {"CONFigure:VOLTage:DC", DMM_ConfigureVoltageDc, SCPI_CMD_TAG(0)},
+    {"MEASure:VOLTage:DC:RATio?", SCPI_StubQ, SCPI_CMD_TAG(0)},
+    {"MEASure:VOLTage:AC?", DMM_MeasureVoltageAcQ, SCPI_CMD_TAG(0)},
+    {"MEASure:CURRent:DC?", SCPI_StubQ, SCPI_CMD_TAG(0)},
+    {"MEASure:CURRent:AC?", SCPI_StubQ, SCPI_CMD_TAG(0)},
+    {"MEASure:RESistance?", SCPI_StubQ, SCPI_CMD_TAG(0)},
+    {"MEASure:FRESistance?", SCPI_StubQ, SCPI_CMD_TAG(0)},
+    {"MEASure:FREQuency?", SCPI_StubQ, SCPI_CMD_TAG(0)},
+    {"MEASure:PERiod?", SCPI_StubQ, SCPI_CMD_TAG(0)},
+
+    {"SYSTem:COMMunication:TCPIP:CONTROL?", SCPI_SystemCommTcpipControlQ, SCPI_CMD_TAG(0)},
+
+    {"TEST:BOOL", TEST_Bool, SCPI_CMD_TAG(0)},
+    {"TEST:CHOice?", TEST_ChoiceQ, SCPI_CMD_TAG(0)},
+    {"TEST#:NUMbers#", TEST_Numbers, SCPI_CMD_TAG(0)},
+    {"TEST:TEXT", TEST_Text, SCPI_CMD_TAG(0)},
+    {"TEST:ARBitrary?", TEST_ArbQ, SCPI_CMD_TAG(0)},
+    {"TEST:CHANnellist", TEST_Chanlst, SCPI_CMD_TAG(0)},
 
     SCPI_CMD_LIST_END
 };

diff --git a/libscpi/inc/scpi/config.h b/libscpi/inc/scpi/config.h
@@ -110,6 +110,10 @@ extern "C" {
 #define USE_COMMAND_TAGS 1
 #endif
 
+#ifndef USE_COMMAND_DESCRIPTIONS
+#define USE_COMMAND_DESCRIPTIONS 1
+#endif
+
 #ifndef USE_DEPRECATED_FUNCTIONS
 #define USE_DEPRECATED_FUNCTIONS 1
 #endif

diff --git a/libscpi/inc/scpi/minimal.h b/libscpi/inc/scpi/minimal.h
@@ -59,7 +59,7 @@ extern "C" {
     scpi_result_t SCPI_StatusOperationEnableQ(scpi_t * context);
     scpi_result_t SCPI_StatusOperationEnable(scpi_t * context);
     scpi_result_t SCPI_StatusPreset(scpi_t * context);
-
+    scpi_result_t SCPI_HelpQ(scpi_t * context);
 
 #ifdef	__cplusplus
 }

diff --git a/libscpi/inc/scpi/types.h b/libscpi/inc/scpi/types.h
@@ -114,10 +114,14 @@ extern "C" {
 
     typedef struct _scpi_command_t scpi_command_t;
 
-#if USE_COMMAND_TAGS
-	#define SCPI_CMD_LIST_END       {NULL, NULL, 0}
+#if USE_COMMAND_DESCRIPTIONS && USE_COMMAND_TAGS
+#define SCPI_CMD_LIST_END {NULL, NULL, NULL, 0}
+#elif USE_COMMAND_DESCRIPTIONS
+#define SCPI_CMD_LIST_END {NULL, NULL, NULL}
+#elif USE_COMMAND_TAGS
+#define SCPI_CMD_LIST_END {NULL, NULL, 0}
 #else
-	#define SCPI_CMD_LIST_END       {NULL, NULL}
+#define SCPI_CMD_LIST_END {NULL, NULL}
 #endif
 
 
@@ -351,6 +355,9 @@ extern "C" {
     struct _scpi_command_t {
         const char * pattern;
         scpi_command_callback_t callback;
+#if USE_COMMAND_DESCRIPTIONS
+        const char * description;
+#endif /* USE_COMMAND_DESCRIPTIONS */
 #if USE_COMMAND_TAGS
         int32_t tag;
 #endif /* USE_COMMAND_TAGS */

diff --git a/libscpi/src/minimal.c b/libscpi/src/minimal.c
@@ -213,3 +213,36 @@ scpi_result_t SCPI_StatusPreset(scpi_t * context) {
     SCPI_RegSet(context, SCPI_REG_QUES, 0);
     return SCPI_RES_OK;
 }
+
+/**
+ * HELP?
+ * @param context
+ * @return
+ */
+scpi_result_t SCPI_HelpQ(scpi_t * context) {
+    int i = 0;
+    for(;;) {
+        size_t pattern_len = strlen(context->cmdlist[i].pattern);
+        size_t block_len = 1 + pattern_len + strlen(SCPI_LINE_ENDING);
+#if USE_COMMAND_DESCRIPTIONS
+        size_t description_len = context->cmdlist[i].description ? strlen(context->cmdlist[i].description) : 0;
+        if(description_len > 0){
+            block_len = 1 + pattern_len + 1 + description_len + strlen(SCPI_LINE_ENDING);
+            }
+#endif
+        SCPI_ResultArbitraryBlockHeader(context, block_len);
+        SCPI_ResultArbitraryBlockData(context, "\t", 1);
+        SCPI_ResultArbitraryBlockData(context, context->cmdlist[i].pattern, pattern_len);
+#if USE_COMMAND_DESCRIPTIONS
+        if(description_len > 0){
+            SCPI_ResultArbitraryBlockData(context, " ", 1);
+            SCPI_ResultArbitraryBlockData(context, context->cmdlist[i].description, description_len);
+        }
+#endif
+        SCPI_ResultArbitraryBlockData(context, SCPI_LINE_ENDING, strlen(SCPI_LINE_ENDING));
+        if (context->cmdlist[++i].pattern == NULL) {
+            break;
+        }
+    }
+    return SCPI_RES_OK;
+}