REF Summary

REF Summary Sample Application (SSK 2.x)

Overview

The REF Summary sample application demonstrates how to read and manage fault status across all channels of a Reference module using the NAI Software Support Kit (SSK 2.x). It covers the core status operations you will need in your own application: displaying latched BIT and summary status for every channel, and clearing latched status registers.

The summary register is the key concept in this sample. It is a bit-mapped register where each bit corresponds to a channel (bit 0 = channel 1). A bit reads 1 when the corresponding channel has detected a fault in its BIT status. This gives you a single register to poll for any fault condition across the entire module, rather than reading BIT status individually for each channel.

Unlike most other summary samples, the REF Summary does not include interrupt configuration. It provides a simpler two-command interface focused on status display and clearing. This sample supports the AC1 module type. It serves as a practical API reference — each menu command maps directly to one or more naibrd_REF_*() API calls that you can lift into your own code.

Note	This pattern is new to SSK 2.x and has no SSK 1.x counterpart.

Prerequisites

Before running this sample, make sure you have:

An NAI board with a Reference module installed (AC1).
SSK 2.x installed on your development host.
The sample applications built. Refer to the SSK 2.x Software Development Guide for platform-specific build instructions.

How to Run

Launch the ref_summary executable from your build output directory. On startup the application looks for a configuration file (default_REF_Summary.txt). On the first run, this file will not exist — the application will present an interactive board menu where you configure a board connection, card index, and module slot. You can save this configuration so that subsequent runs skip the menu and connect automatically. Once connected, select a channel, then use the command menu to display and clear status registers.

The recommended sequence for exploring this sample is:

CLEAR — clear all latched status registers to start from a clean state.
STAT — display all latched statuses (should all be zero after clearing).
STAT — display statuses again to observe any changes over time.
CLEAR — clear all statuses to reset.

Board Connection and Module Selection

Note	This startup sequence is common to all NAI sample applications. The board connection and module selection code shown here is not specific to Reference modules.

The main() function follows a standard SSK 2.x startup flow:

Call naiapp_RunBoardMenu() to load a saved configuration file (if one exists) or present the interactive board menu. The configuration file (default_REF_Summary.txt) is not included with the SSK — it is created when the user saves their connection settings from the board menu. On the first run, the menu will always appear.
Query the user for a card index with naiapp_query_CardIndex().
Query for a module slot with naiapp_query_ModuleNumber().
Retrieve the module ID with naibrd_GetModuleName() so downstream code can adapt to the specific Reference variant installed.

#if defined (NAIBSP_CONFIG_SOFTWARE_OS_VXWORKS)
int32_t ref_summary(void)
#else
int32_t main(void)
#endif
{
   int32_t cardIndex;
   int32_t moduleCnt;
   int32_t module;
   bool_t stop = NAI_FALSE;
   uint32_t moduleID;
   int8_t inputBuffer[80];
   int32_t inputResponseCnt;

   if (naiapp_RunBoardMenu(DEF_CONFIG_FILE) == (bool_t)NAI_TRUE)
   {
      while (stop != NAI_TRUE)
      {
         stop = naiapp_query_CardIndex(naiapp_GetBoardCnt(), DEF_REF_CARD_INDEX, &cardIndex);
         if (stop != NAI_TRUE)
         {
            check_status(naibrd_GetModuleCount(cardIndex, &moduleCnt));
            stop = naiapp_query_ModuleNumber(moduleCnt, DEF_REF_MODULE, &module);
            if (stop != NAI_TRUE)
            {
               check_status(naibrd_GetModuleName(cardIndex, module, &moduleID));
               if ((moduleID != 0))
               {
                  Run_REF_Summary(cardIndex, module, moduleID);
               }
            }
         }
      }
   }

   naiapp_access_CloseAllOpenCards();
   return 0;
}

After module selection, Run_REF_Summary() calls naibrd_REF_GetChannelCount() to determine how many channels the installed module supports, then hands off to the command loop in Cfg_REF_Channel().

maxchannel = naibrd_REF_GetChannelCount(modid);
if (maxchannel == 0)
{
   naiif_printf(" *** Module selection not recognized as REF module. ***\r\n\r\n");
}
else
{
   Cfg_REF_Channel(cardIndex, module, maxchannel);
}

modid — the module ID returned by naibrd_GetModuleName().
naibrd_REF_GetChannelCount() — returns 0 if the module ID does not match a known Reference module type.

Program Structure

Application Parameters

The sample stores connection and module context in an naiapp_AppParameters_t struct:

naiapp_AppParameters_t  refparams;
p_naiapp_AppParameters_t refParams = &refparams;

refParams->cardIndex = cardIndex;
refParams->module = module;
refParams->maxChannels = MaxChannel;
refParams->channel = chan;

cardIndex — identifies the board.
module — the slot containing the Reference module.
maxChannels — the channel count for the installed module.
channel — the channel selected during setup.

In your own application, you will track these same values however is convenient — the struct is a sample convenience, not an API requirement.

The sample presents two commands through its menu system:

Command Menu Label Operation

Command	Menu Label	Operation
`STAT`	REF Display Status	Display latched BIT and summary status for all channels
`CLEAR`	REF Clear Status	Clear all latched status registers across all channels

STAT

REF Display Status

Display latched BIT and summary status for all channels

CLEAR

REF Clear Status

Clear all latched status registers across all channels

The menu system is a sample convenience — in your own code, call these API functions directly. The command table and menu handling use the standard naiapp_cmdtbl_params_t pattern shared across all SSK 2.x samples.

Display Configuration

Reading Latched Status

To read the latched fault status for every channel on a Reference module in your own application, call naibrd_REF_GetChanMappedStatus() with each status type. The sample reads two status registers per channel:

nai_status_bit_t statusBit;

for (chan = 1; chan <= refParams->maxChannels; chan++)
{
   check_status(naibrd_REF_GetChanMappedStatus(cardIndex, module, chan,
      NAIBRD_REF_STATUS_BIT_LATCHED, &statusBit));

   check_status(naibrd_REF_GetChanMappedStatus(cardIndex, module, chan,
      NAIBRD_REF_STATUS_SUMMARY_LATCHED, &statusBit));
}

cardIndex — identifies the board.
module — the slot containing the Reference module.
chan — the channel number (1-based).
NAIBRD_REF_STATUS_BIT_LATCHED — the latched built-in test status. Reads 1 if the channel has detected a BIT failure since the status was last cleared.
NAIBRD_REF_STATUS_SUMMARY_LATCHED — the latched summary status. Reads 1 if a BIT fault has been detected on this channel. This is the aggregated fault indicator.

The sample also reads raw status words using naibrd_REF_GetChanMappedStatusRaw() to display the entire register in hexadecimal, giving a consolidated view of all channels at once.

Understanding the Summary Register

The summary register provides a consolidated view of all fault conditions on a channel. Rather than polling BIT status separately for each channel, you can check the summary bit — if it reads 1, at least one fault condition exists. This is particularly useful in applications that monitor many channels and need a fast way to detect any fault.

A latched summary bit remains set until you explicitly clear it by writing a 1 to the corresponding bit position.

Clearing Latched Status

To clear all latched status registers in your own application, call naibrd_REF_ClearChanMappedStatusRaw() for each status type with a bitmask of 0xFFFFFFFF to clear all channels at once:

status = check_status(naibrd_REF_ClearChanMappedStatusRaw(cardIndex, module,
   NAIBRD_REF_STATUS_BIT_LATCHED, 0xFFFFFFFFu));
if (status == NAI_SUCCESS)
{
   status = check_status(naibrd_REF_ClearChanMappedStatusRaw(cardIndex, module,
      NAIBRD_REF_STATUS_SUMMARY_LATCHED, 0xFFFFFFFFu));
}

The sample clears both status types (BIT and summary). The order matters — if you clear summary without clearing the underlying BIT status, the summary bit may reassert on the next status scan. Clear both to ensure a clean state.

Important

Common Errors

Summary bit reasserts after clearing — If the underlying fault condition (BIT) is still active, the summary bit will reassert. Clear BIT status as well, or resolve the underlying hardware condition.
NAI_ERROR_NOT_SUPPORTED — The module at the selected slot is not a recognized Reference module type. Verify the module type with naibrd_REF_GetChannelCount().

Troubleshooting Reference

This table summarizes common errors and symptoms covered in the sections above. For detailed context on each entry, refer to the relevant section. Consult your module’s manual (AC1 Manual) for hardware-specific diagnostic procedures.

Error / Symptom Possible Causes Suggested Resolution

Error / Symptom	Possible Causes	Suggested Resolution
No board found or connection timeout	Board not powered, incorrect or missing configuration file, network issue	Verify hardware is powered and connected. If `default_REF_Summary.txt` exists, check that it lists the correct interface and address. If it does not exist, the board menu will appear — configure and save your connection settings.
Module not detected at selected slot	No module installed at the specified slot, incorrect module number entered	Verify hardware configuration and module slot assignment
Module not recognized as Reference	Module ID does not match a known REF type — wrong slot selected or non-REF module installed	Select a different module slot. Verify that an AC1 module is installed at the selected position.
`NAI_ERROR_NOT_SUPPORTED`	Feature not available for this module type, or calling a REF function on a non-REF module	Check your module type with `naibrd_REF_GetChannelCount()`. Consult your module’s manual for supported features.
Summary bit reasserts after clearing	Underlying BIT fault still active	Clear BIT status along with summary status. If the condition persists, resolve the hardware fault.

No board found or connection timeout

Board not powered, incorrect or missing configuration file, network issue

Verify hardware is powered and connected. If default_REF_Summary.txt exists, check that it lists the correct interface and address. If it does not exist, the board menu will appear — configure and save your connection settings.

Module not detected at selected slot

No module installed at the specified slot, incorrect module number entered

Verify hardware configuration and module slot assignment

Module not recognized as Reference

Module ID does not match a known REF type — wrong slot selected or non-REF module installed

Select a different module slot. Verify that an AC1 module is installed at the selected position.

NAI_ERROR_NOT_SUPPORTED

Feature not available for this module type, or calling a REF function on a non-REF module

Check your module type with naibrd_REF_GetChannelCount(). Consult your module’s manual for supported features.

Summary bit reasserts after clearing

Underlying BIT fault still active

Clear BIT status along with summary status. If the condition persists, resolve the hardware fault.

Full Source

The complete source for this sample is provided below for reference. The sections above explain each part in detail.

Full Source — ref_summary.c (SSK 2.x)

/* nailib include files */
#include "nai_libs/nailib/include/naitypes.h"
#include "nai_libs/nailib/include/nailib.h"
#include "nai_libs/nailib/include/nailib_utils.h"

/* naibrd include files */
#include "nai_libs/naibrd/include/naibrd.h"
#include "nai_libs/naibrd/include/functions/naibrd_ref.h"

/* naiif include files */
#include "nai_libs/naiif/include/naiif_stdio.h"

/* Common Sample Program include files */
#include "nai_sample_apps/naiapp_common/include/naiapp_boardaccess_menu.h"
#include "nai_sample_apps/naiapp_common/include/naiapp_boardaccess_query.h"
#include "nai_sample_apps/naiapp_common/include/naiapp_boardaccess_access.h"
#include "nai_sample_apps/naiapp_common/include/naiapp_boardaccess_display.h"
#include "nai_sample_apps/naiapp_common/include/naiapp_boardaccess_utils.h"

#if defined (NAIBSP_CONFIG_SOFTWARE_OS_VXWORKS)
#include "logLib.h"
#endif
static const int8_t *DEF_CONFIG_FILE = (const int8_t *)"default_REF_Summary.txt";

/* Function prototypes */
static int32_t Run_REF_Summary(int32_t cardIndex, int32_t module, uint32_t modid);
static void Cfg_REF_Channel(int32_t cardIndex, int32_t module, int32_t MaxChannel);
static void Verify_REF_ParamCnt(int32_t paramCnt);
static nai_status_t Display_REF_Status(int32_t paramCnt, int32_t* p_params);
static nai_status_t Clear_REF_Status(int32_t paramCnt, int32_t* p_params);

static const int32_t DEF_REF_CARD_INDEX    = 0;
static const int32_t DEF_REF_MODULE        = 1;
static const int32_t DEF_REF_CHANNEL       = 1;

/****** Command Table *******/
enum ref_basic_summary_commands
{
   REF_SUMMARY_SUMMARY_CMD_STATUS_READ,
   REF_SUMMARY_SUMMARY_CMD_STATUS_CLEAR,
   REF_SUMMARY_SUMMARY_CMD_COUNT
};

/****** Command Tables *******/
static naiapp_cmdtbl_params_t REF_SummaryMenuCmds[] = {
   {"STAT",     "REF Display Status",         REF_SUMMARY_SUMMARY_CMD_STATUS_READ,       Display_REF_Status},
   {"CLEAR",    "REF Clear Status",           REF_SUMMARY_SUMMARY_CMD_STATUS_CLEAR,      Clear_REF_Status}
};

/**************************************************************************************************************/
/**
 * <summary>
 * The purpose of the ref_summary example is to illustrate the methods to call in the naibrd library to
 * perform basic operations with Reference modules for reading fault statuses including the
 * summary status register and clearing status bits. The summary register is bit-mapped by channel
 * (bit index zero is channel 1) and reports a '1' if the corresponding channel has detected a fault
 * (including BIT). A latched summary bit can be cleared by writing a '1' to the bit.
 * </summary>
 */
/**************************************************************************************************************/
#if defined (NAIBSP_CONFIG_SOFTWARE_OS_VXWORKS)
int32_t ref_summary(void)
#else
int32_t main(void)
#endif
{
   int32_t cardIndex;
   int32_t moduleCnt;
   int32_t module;
   bool_t stop = NAI_FALSE;
   uint32_t moduleID;
   int8_t inputBuffer[80];
   int32_t inputResponseCnt;

   if (naiapp_RunBoardMenu(DEF_CONFIG_FILE) == (bool_t)NAI_TRUE)
   {
      while (stop != NAI_TRUE)
      {
         /* Select Card Index */
         stop = naiapp_query_CardIndex(naiapp_GetBoardCnt(), DEF_REF_CARD_INDEX, &cardIndex);
         if (stop != NAI_TRUE)
         {
            check_status(naibrd_GetModuleCount(cardIndex, &moduleCnt));

            /* Select Module */
            stop = naiapp_query_ModuleNumber(moduleCnt, DEF_REF_MODULE, &module);
            if (stop != NAI_TRUE)
            {
               check_status(naibrd_GetModuleName(cardIndex, module, &moduleID));
               if ((moduleID != 0))
               {
                  Run_REF_Summary(cardIndex, module, moduleID);
                  naiif_printf("\r\nType Q to quit or Enter to continue:\r\n");
                  stop = naiapp_query_ForQuitResponse(sizeof(inputBuffer), NAI_QUIT_CHAR, inputBuffer, &inputResponseCnt);
               }
            }
         }
      }
   }

   naiif_printf("\r\nType the Enter key to exit the program: ");
   naiapp_query_ForQuitResponse(sizeof(inputBuffer), NAI_QUIT_CHAR, inputBuffer, &inputResponseCnt);
   naiapp_access_CloseAllOpenCards();
   return 0;
}
/**************************************************************************************************************/
/**
 * <summary>
 * Verify_REF_ParamCnt verifies parameter count and displays error message if invalid.
 * </summary>
 */
 /**************************************************************************************************************/
static void Verify_REF_ParamCnt(int32_t paramCnt)
{
   if (paramCnt != APP_PARAM_COUNT)
   {
      naiif_printf(" *** Parameter count specified is incorrect!!! ***\r\n");
   }
}
/**************************************************************************************************************/
/**
 * <summary>
 * Run_REF_Summary prompts the user for the card, module and channel to use for the application and calls
 * Cfg_REF_Channel if the card, module, and channel specified are all valid for the REF module.
 * </summary>
 */
/**************************************************************************************************************/
static int32_t Run_REF_Summary(int32_t cardIndex, int32_t module, uint32_t modid)
{
   bool_t bQuit = NAI_FALSE;
   int32_t maxchannel;

   if (!bQuit)
   {
      maxchannel = naibrd_REF_GetChannelCount(modid);
      if (maxchannel == 0)
      {
         naiif_printf(" *** Module selection not recognized as REF module. ***\r\n\r\n");
      }
      else
      {
         Cfg_REF_Channel(cardIndex, module, maxchannel);
      }
   }
   return cardIndex;
}

/**************************************************************************************************************/
/**
 * <summary>
 * Cfg_REF_Channel handles calling the Display_REF_ChannelCfg routine to display the reference channel
 * configuration and calling the routines associated with the user's menu commands.
 * </summary>
 */
/**************************************************************************************************************/
static void Cfg_REF_Channel(int32_t cardIndex, int32_t module, int32_t MaxChannel)
{
   bool_t bQuit = NAI_FALSE;
   bool_t bContinue = NAI_TRUE;
   bool_t bCmdFound = NAI_FALSE;
   int32_t chan, defaultchan = 1;
   int32_t cmd;
   naiapp_AppParameters_t  refparams;
   p_naiapp_AppParameters_t refParams = &refparams;
   int8_t inputBuffer[80];
   int32_t inputResponseCnt;

   while (bContinue)
   {
      naiif_printf("\r\n\r\n");
      naiif_printf("Channel selection\r\n");
      naiif_printf("=================\r\n");
      defaultchan = DEF_REF_CHANNEL;

      bQuit = naiapp_query_ChannelNumber(MaxChannel, defaultchan, &chan);
      refParams->cardIndex = cardIndex;
      refParams->module = module;
      refParams->maxChannels = MaxChannel;
      refParams->channel = chan;

      naiapp_utils_LoadParamMenuCommands(REF_SUMMARY_SUMMARY_CMD_COUNT, REF_SummaryMenuCmds);
      while (bContinue)
      {
         naiapp_display_ParamMenuCommands((int8_t *)"REF Summary Menu");
         naiif_printf("\r\nType REF command or %c to quit : ", NAI_QUIT_CHAR);
         bQuit = naiapp_query_ForQuitResponse(sizeof(inputBuffer), NAI_QUIT_CHAR, inputBuffer, &inputResponseCnt);
         if (!bQuit)
         {
            if (inputResponseCnt > 0)
            {
               bCmdFound = naiapp_utils_GetParamMenuCmdNum(inputResponseCnt, inputBuffer, &cmd);
               if (bCmdFound)
               {
                  switch (cmd)
                  {
                  case REF_SUMMARY_SUMMARY_CMD_STATUS_READ:
                  case REF_SUMMARY_SUMMARY_CMD_STATUS_CLEAR:
                     REF_SummaryMenuCmds[cmd].func(APP_PARAM_COUNT, (int32_t*)refParams);
                     break;
                  default:
                     naiif_printf("Invalid command entered\r\n");
                     break;
                  }
               }
               else
               {
                  naiif_printf("Invalid command entered\r\n");
               }
            }
         }
         else
         {
            bContinue = NAI_FALSE;
         }
      }
   }
}

/**************************************************************************************************************/
/**
 * <summary>
 * Display_REF_Status illustrates the methods to call in the naibrd library to retrieve the status states.
 * </summary>
 */
/**************************************************************************************************************/
static nai_status_t Display_REF_Status(int32_t paramCnt, int32_t* p_params)
{
   p_naiapp_AppParameters_t refParams = (p_naiapp_AppParameters_t)p_params;
   int32_t cardIndex = refParams->cardIndex;
   int32_t module = refParams->module;
   int32_t chan;
   nai_status_bit_t statusBit;
   uint32_t rawValue;
   Verify_REF_ParamCnt(paramCnt);

   naiif_printf("\r\n");
   naiif_printf("  --------Latched Status---------\r\n");
   naiif_printf("   Chan      BIT       SUMMARY   \r\n");
   naiif_printf("  ------ ---------- -------------\r\n");

   for (chan = 1; chan <= refParams->maxChannels; chan++)
   {
      naiif_printf("  %3i   ", chan);

      check_status(naibrd_REF_GetChanMappedStatus(cardIndex, module, chan, NAIBRD_REF_STATUS_BIT_LATCHED, &statusBit));
      naiif_printf("    %3i   ", statusBit);

      check_status(naibrd_REF_GetChanMappedStatus(cardIndex, module, chan, NAIBRD_REF_STATUS_SUMMARY_LATCHED, &statusBit));
      naiif_printf("      %3i   ", statusBit);

      naiif_printf("\r\n");
   }

   /* Print status words in hex */
   naiif_printf("  All   ");

   check_status(naibrd_REF_GetChanMappedStatusRaw(cardIndex, module, NAIBRD_REF_STATUS_BIT_LATCHED, &rawValue));
   naiif_printf(" 0x%08X ", rawValue);

   check_status(naibrd_REF_GetChanMappedStatusRaw(cardIndex, module, NAIBRD_REF_STATUS_SUMMARY_LATCHED, &rawValue));
   naiif_printf(" 0x%08X ", rawValue);

   naiif_printf("\r\n\r\n");

   return NAI_SUCCESS;
}

static nai_status_t Clear_REF_Status(int32_t paramCnt, int32_t* p_params)
{
   nai_status_t status = NAI_ERROR_NOT_SUPPORTED;
   p_naiapp_AppParameters_t refParams = (p_naiapp_AppParameters_t)p_params;
   int32_t cardIndex = refParams->cardIndex;
   int32_t module = refParams->module;
   Verify_REF_ParamCnt(paramCnt);

   status = check_status(naibrd_REF_ClearChanMappedStatusRaw(cardIndex, module, NAIBRD_REF_STATUS_BIT_LATCHED, 0xFFFFFFFFu));
   if (status == NAI_SUCCESS)
   {
      status = check_status(naibrd_REF_ClearChanMappedStatusRaw(cardIndex, module, NAIBRD_REF_STATUS_SUMMARY_LATCHED, 0xFFFFFFFFu));
   }

   if (status == NAI_SUCCESS)
   {
      naiif_printf("Cleared all statuses...\r\n");
   }

   return status;
}

REF Summary

Table of Contents

Integrator Resources

REF Summary

REF Summary Sample Application (SSK 2.x)

Overview

Prerequisites

How to Run

Board Connection and Module Selection

Program Structure

Application Parameters

Command Menu

Display Configuration

Reading Latched Status

Understanding the Summary Register

Clearing Latched Status

Troubleshooting Reference

Full Source

Help Bot