Sparrow Application Guide: Diagnostic

Application Introduction

The Diagnostic Application is designed to help new developers to the Sparrow Application ecosystem understand and trace the behaviors of an application. The Diagnostic application uses all features (albeit trivially) to demonstrate their usage, and generates logs with calling parameters for each callback it enters. This gives the developer a feel for the rhythm and flow of a Sparrow Application.

Expected Behavior

The Diagnostic application has a period of 10 minutes, which means it will wake from “sleep” every 10 minutes to perform work. While awake, it has a polling interval of 5 seconds, which means it will invoke the polling callback every 5 seconds. When a Sparrow running the Diagnostic application is connected to a terminal, it will create an output log as it enters each callback.

The Diagnostic will create a template, register it with the Notecard attached to the Sparrow Gateway and parse the response. Once it has successfully registered a template, the application then performs “real work” by making system calls to collect the runtime memory usage of the Sparrow Runtime, including all applications.

Output to Notehub

The Diagnostic application will generate a Note with the following details. The Note will appear in a Notefile prefixed with the device id (e.g. 012345678901234567890123) and suffixed with #diag.qo.

This Note can be viewed on Notehub.io, by looking for the project associated with the Notecard attached to the Sparrow Gateway.

Logging Output

The logs generated by the Diagnostic application are verbose by design.

In the logs below, you can see the application send a request to register a template (8), receive a response that the registration was successful (43), generate a diagnostic report (46), and finally receive a response of success (73).

More importantly, you can see the application progress through the callbacks:

• diagActivate - (1)

• diagPoll - (4, 6, 16, 19, 22, 32)

• diagResponse - (38)

• diagPoll - (41, 52, 56, 65, 75)

• diagResponse - (81)

• diagPoll - (84)

Implementation Details

Source Code Link: https://github.com/blues/sparrow-reference-firmware/blob/main/sparrow-application/diag/diag.c

Defines

Custom Application States

• STATE_DIAG_ABORT - This state is reserved for application specific error conditions, and will allow for graceful deactivation of the application.

• STATE_DIAG_CHECK - When this state is received by the polling callback and the application has not be marked for deactivation, it will generate a diagnostic report, send the results to the Gateway Notecard, and mark itself ready for deactivation. Otherwise, if this state is received by the polling callback and the application has already been marked for deactivation then it will log a completion message and immediately deactivate.

• STATE_DIAG_ISR_XFER - This state is set from within the ISR, and it allows the polling callback to know the interrupt was invoked.

Application Specific Values

• REQUESTID_DIAGNOTE - An arbitrary number to match a diagnostic Note response and request.

• REQUESTID_TEMPLATE - An arbitrary number to match the template response and request.

• APPLICATION_NOTEFILE - The dynamic filename of the application specific queue.

  NOTE: The Gateway will replace * with the originating node's ID. The resulting transformation will resemble 012345678901234567890123#diag.qo.

Array and Counter Limits

• ISR_MAX_CALL_RETENTION - The maximum number of ISRs that will be recorded.

• ISR_COUNTER_MASK - The mask will limit the value of the counter.

Structures

• isrParameters - Since an APP_PRINT() statement cannot be used from within an interrupt service routine, this structure is used to collect the calling parameters of the ISR for later processing.

  • appID - The application ID passed to the ISR callback

  • pins - The pin(s) prompting the ISR invocation.

• applicationContext - A rather trivial example of application context, but never the less ALL the application state is stored in a single structure which is shared between callbacks.

  • isrCount - The number of times the ISR was invoked.

  • isrOverflow - Indicates whether the ISR was invoked more than ISR_MAX_CALL_RETENTION times.

  • isrParams - An array dedicated to recording the calling parameters of each ISR invocation.

  • templateRegistered - Provides a mechanism for the polling callback to only attempt to register a template once.

  • done - Provides a mechanism for the polling callback to indicate when a note has been submitted to the Notecard, so it will know when to deactivate itself.

Global Static Variables (a.k.a. Singleton Application Specific Context)

none

Callbacks

• bool diagActivate(int appID, void *appContext)

   

  This line casts the context, so it can be used in subsequent operations.
  
  

  This line logs the entry into the function along with the calling parameters.
  
  

  The function resets the done state, so the application will progress until it has generated a Note or has failed during execution.
  
  

  The function returns true, so the application will progress to the polling callback
  
  

• void diagISR(int appID, uint16_t pins, void *appContext);
  
  

  This line casts the context, so it can be used in subsequent operations.
  
  

  The function executes inside an actual ISR, so there is no time to perform expensive operations (like logging). Therefore, it collects the calling parameters and updates metadata. This is necessary to track how many times the interrupt has been called, so it may log the details outside the ISR.
  
  

  These lines filter to ensure the ISR only responds to the PAIR button (BUTTON1_Pin), and checks with the scheduler that the application is not already in an active state. If these conditions are met, then it will request the scheduler to schedule the application for immediate activation instead of respecting the activation period.
  
  The logs generated by the ISR look like this:

  Since the parameter collection is performed outside the filter, the ISR callback is invoked multiple times. However, an ISR is only significant to this application when pin equals 8192 (which is 0x2000 or BUTTON1_Pin). As you can see, there are other invocations where pin equals 128. Those invocations are related to the PIR application interrupts, and are ignored by this application.
  
  

• void diagPoll(int appID, int state, void *appContext);
  
  

  This line casts the context, so it can be used in subsequent operations.
  
  

  This line logs the entry into the function along with the calling parameters.
  
  

  This case handles the newly activated state. It will first check to see if a template has been registered in a previous invocation of the polling callback.
  If a template has not been registered, then it will attempt to do so. If the request is delivered successfully, then the state will be changed to the next state in the progression, to process the diagnostic values. Otherwise, if the message fails to be delivered, then the state will be set to the ABORT state.
  If a template has already been registered on a previous invocation, then the state will be changed to the next state, to process diagnostic values.
  
  

  This case handles a transfer from the interrupt routine. It will print the invocation, along with the parameters, of of each recorded ISR, up to ISR_MAX_CALL_RETENTION times. Once it has exhausted it’s cache, it will reset all values related to the ISR. Instead of exiting, it will fall through into the next case…
  
  

  This case handles the main objective of the application, the collection of diagnostics and sending a Note to the Notehub. It will check for the done flag, which is only set once a Note has been successfully received by the Notecard. If done is set, then the application will log a success message and request to be deactivated. If the done flag has not been set, then schedSetCompletionState is called to instruct the scheduler what to do when the request to add a Note either succeeds or fails. As you can see above, if the request is successful, then it will return to this state, but the done flag will be true, and the app will request deactivation. However, if it were to fail, then the application will proceed to the ABORT state. Finally, the request to add a Note is made.
  
  

  This case is reserved for fail cases encountered during the application processing. It request for the application to be deactivated and generates a log indicating the failure.
  
  

• void diagResponse(int appID, J *rsp, void *appContext);
  
  

  This line casts the context, so it can be used in subsequent operations.
  
  

  These lines log the entry into the function along with the calling parameters. Special accommodation is made for the JSON response. APP_PRINTF is limited to 90 characters, so two calls are required to reliably log the parameters.
  
  

  These lines will peek inside the response JSON to see if an error message is present. If so, the error message will be logged and the application will proceed to the ABORT state.
  
  

  This switch statement is designed to handle responses to successful requests. The switch operates on the unique identifiers given to each request. If the ID of a diagnostic Note is encountered, the done flag is set and a success log is generated. If the ID associated with a template request is encountered, then the flag indicating the template was successfully recorded is set and a log is generated. If neither of these IDs are present, then a log is generated indicating the response was not recognized.

Other Functions

External

• bool diagInit(void);
  
  

  This line logs the entry into the function.
  
  

  This line initializes the result of the function to false, which means “Failed to init”.
  
  

  These lines allocate and initialize the values of the portable application context.
  
  

  These lines initialize the application configuration that will be passed to the scheduler.
  
  

  These lines will attempt to register the application with the scheduler. On success, an application identifier greater than or equal to zero is returned, otherwise a negative value is returned to indicate registration failure. For basic usage, it is unnecessary to capture the application identifier, because it is returned as the first parameter of each of the callbacks registered by the application.
  
  

  This line returns the result to the caller.

Internal

• static void addDiagnosticNote(bool immediate);
  
  

  This line simply logs the intent of the function.
  
  

  These lines are constructing a JSON object that looks like the following:

  NOTE: The asterisks (*) in the file name will be expanded to include the Sparrow's UID. For the Note above, this operation tips the Note size greater than MESSAGE_MAX_BODY which causes the body to be chunked and delivered over the LoRa network in two parts.

   

  This line submits the Note to the Notecard attached to the Sparrow Gateway. The req parameter is the JSON object outlined above, and the true parameter informs the schedule that the application expects a response from the Notecard.
  
  

  This line logs the completion of the function.
  
  

• static const char * diagStateName (int state);
  
  

  The function translates the int value of an application specific state into a const char * description of the state. In the default case, where a state is unrecognized, it will defer to the analogous system API, which will either transcribe the state or simply print the integer's string representation.
  
  

• static bool registerNotefileTemplate();
  
  

  This line simply logs the intent of the function.
  
  

  These lines are constructing a JSON object that looks like the following:

   

  This line submits the Note to the Notecard attached to the Sparrow Gateway. The req parameter is the JSON object outlined above, and the true parameter informs the schedule that the application expects a response from the Notecard.
  
  

  This line informs the caller we were able to successfully create and submit the Note to the Notecard attached to the Sparrow Gateway.
  
  

• static inline void resetIsrValues(applicationContext *ctx);
  
  

  This line logs the entry into the function.
  
  

  These lines will reset all metadata and parameters related to the ISR.