---

Applies to: All NAI boards — SSK 1.x and 2.x (the status codes are identical across both)

---

NAI Status, BIT & Error Codes

Nearly every naibrd_* function returns an NAI_STATUS value. NAI_SUCCESS (0) means the call worked; any negative value is an error. This page explains the codes you’re most likely to see, how to handle them, and gives a complete reference. It also covers a separate but easily-confused topic — the channel & BIT status bits you read back from the hardware (see Channel and BIT status below).

Note

The status codes are defined identically in SSK 1.x (nai.h) and SSK 2.x (naibsp_sys_defs.h) — the same names and the same values. Everything on this page applies to both.

The basic pattern

Check the return of every call against NAI_SUCCESS and stop on the first failure — continuing after an error usually just produces more errors that hide the real one:

NAI_STATUS status;
 
status = naibrd_OpenDevice(cardIndex, /* ... */);
if (status != NAI_SUCCESS)
{
    printf("naibrd_OpenDevice failed with status %d\n", status);
    return status;   /* bail out — later calls will fail too */
}
 
status = naibrd_AD_SetChannelData(cardIndex, module, channel, value);
if (status != NAI_SUCCESS)
{
    printf("SetChannelData failed with status %d\n", status);
    /* clean up (e.g. naibrd_Close) before returning */
    return status;
}

The sample applications follow this same if (status != NAI_SUCCESS) pattern throughout — they’re a good place to see it in context.

Looking up a specific code

The names in the reference below describe the general condition each code represents. What a specific code indicates for a particular function — and which codes a given function can return — is documented per function in the SSK API reference (Doxygen): each function’s page lists its possible return values. For the parameters and valid ranges a function accepts, see that function’s entry there and the relevant module’s manual.

Complete reference

All general status codes

Value	Code	Meaning
0	NAI_SUCCESS	Operation succeeded.
-1	NAI_ERROR_INVALID_VALUE	A parameter was outside its allowed range.
-2	NAI_ERROR_INVALID_MODE	The requested mode is not valid for this operation.
-3	NAI_ERROR_INVALID_SIZE	A size argument is invalid.
-4	NAI_ERROR_INVALID_TYPECODE	The type code is not recognized.
-5	NAI_ERROR_INVALID_ADDRESS	The address is invalid.
-6	NAI_ERROR_INVALID_ADDRBOUND	The address is outside the allowed bounds.
-7	NAI_ERROR_INVALID_COMMAND	The command is not valid.
-8	NAI_ERROR_NOT_FOUND	The requested item was not found.
-9	NAI_ERROR_TIMEOUT	The operation timed out.
-10	NAI_ERROR_COMM_ERROR	A communication error occurred.
-11	NAI_ERROR_LOCK_FAILED	Failed to acquire a lock.
-12	NAI_ERROR_INVALID_WIDTH	The data width is invalid.
-13	NAI_ERROR_INVALID_CARD	The card/board index is invalid.
-14	NAI_ERROR_INVALID_MODULE	The module/slot number is invalid.
-15	NAI_ERROR_INVALID_CHANNEL	The channel number is invalid.
-16	NAI_ERROR_OPEN_FAILED	The device could not be opened.
-17	NAI_ERROR_INVALID_MESSAGE	The message is invalid.
-18	NAI_ERROR_MESSAGE_MISMATCH	The message did not match what was expected.
-19	NAI_ERROR_OVERFLOW	An overflow occurred.
-20	NAI_ERROR_NOT_MASTER	The operation requires the master, but this device is not the master.
-21	NAI_ERROR_DISCONNECTED	The device is disconnected.
-22	NAI_ERROR_IN_USE	The resource is already in use.
-23	NAI_ERROR_FULL	The buffer/queue is full.
-24	NAI_ERROR_EMPTY	The buffer/queue is empty.
-25	NAI_ERROR_NOT_READY	The device or function is not ready.
-26	NAI_ERROR_CONNECTION_LOST	The connection was lost.
-27	NAI_ERROR_NOT_OPEN	The handle is not open.
-28	NAI_ERROR_PARITY	A parity error occurred (serial).
-29	NAI_ERROR_FRAMING	A framing error occurred (serial).
-30	NAI_ERROR_FRAMING_PARITY	A combined framing and parity error occurred (serial).
-31	NAI_ERROR_NO_MESSAGE	No message was available.
-32	NAI_ERROR_WATCHDOG	A watchdog condition occurred.
-33	NAI_ERROR_BUS_TIMEOUT	A bus access timed out.
-34	NAI_ERROR_INVALID_RANGE	The range is invalid.
-35	NAI_ERROR_WRONG_DEVICE	The operation was directed at the wrong device.
-36	NAI_ERROR_BUS_READ_ERR	A bus read error occurred.
-37	NAI_ERROR_BUS_WRITE_ERR	A bus write error occurred.
-38	NAI_ERROR_MORE_DATA	More data is available than was returned.
-39	NAI_ERROR_INVALID_ENCODER_RES	The encoder resolution is invalid.
-40	NAI_ERROR_INVALID_COMMUTATION_POLES	The number of commutation poles is invalid.
-41	NAI_ERROR_INVALID_RATIO	The ratio is invalid.
-42	NAI_ERROR_INVALID_IO_PARAM	An I/O parameter is invalid.
-43	NAI_ERROR_BIT_FAILED	A Built-In Test failed.
-44	NAI_ERROR_VME_ADDR_TRANSLATION	A VME address translation error occurred.
-45	NAI_ERROR_BSP_VME_TABLE	A BSP VME table error occurred.
-46	NAI_ERROR_INT_CONNECT_FAILED	Failed to connect an interrupt.
-47	NAI_ERROR_INT_DISCONNECT_FAILED	Failed to disconnect an interrupt.
-48	NAI_ERROR_1553_MESSAGE_ERROR	A MIL-STD-1553 message error occurred.
-49	NAI_ERROR_1553_DATA_WRAPAROUND_ERROR	A MIL-STD-1553 data wraparound error occurred.
-50	NAI_ERROR_PERMISSION_DENIED	Permission was denied for the operation.
-51	NAI_ERROR_UNLOCK_FAILED	Failed to release a lock.
-52	NAI_ERROR_PROTOCOL_FUNCTION_MISMATCH	The protocol and function do not match.
-53	NAI_ERROR_FUNCTION_SPECIFIC_ERROR	A function-specific error occurred (see the function’s own documentation).
-100	NAI_ERROR_NOT_SUPPORTED	The operation is not supported by this module/board.
-1000	NAI_ERROR_UNKNOWN	An unknown error occurred.
-1001	NAI_ERROR_UNKNOWN_VALUE	An unknown value was encountered.

Gen4 Ethernet protocol error codes (-0x8000 and below)

Boards using the Gen4 Ethernet protocol can also return a block of protocol-level error codes starting at -0x8000 (NAI_ERROR_ETHER_GENERAL_GEN4). These are low-level messaging errors — invalid preamble/postamble, sequence number, payload size, EEPROM read/write failures, etc. — that most application code will not encounter directly during normal register read/write operations.

If you receive a code at or below -0x8000, it points to a problem in the Ethernet message exchange itself (malformed or mismatched packets) rather than in your API call arguments. See the NAI Ethernet Protocol APIs page and the SSK header (nai.h) for the full enumerated list.

Channel and BIT status

This is a different thing from the return codes above. The codes above are what a function call hands back — whether the call itself succeeded. Separately, NAI modules continuously report the health and condition of each channel as status bits you read from the hardware — BIT, open/overvoltage, signal loss, termination fault, and a summary. A call can return NAI_SUCCESS (it worked) and still report back a status bit telling you a channel has a fault.

Important

Don’t confuse NAI_ERROR_BIT_FAILED (a return code — the call itself could not complete) with a BIT status bit being set (the call succeeded and told you the channel failed its self-test). Same word, different layer.

You read these bits with the module family’s status getter — for example naibrd_AD_GetStatus() or naibrd_VR_GetChanMappedStatus() — passing a status-type selector. The available conditions and their exact selector names are per module family; see that function’s entry in the SSK API reference and the module’s manual.

Real-time vs latched — the R/L convention

Every status condition has two forms, and the sample applications display them side by side as R/L:

Form	Meaning
Real-time (R)	The condition right now. Clears itself as soon as the condition goes away.
Latched (L)	Records that the condition occurred. Stays set until you explicitly clear it — even after the condition itself is gone.

Each form is a separate selector (e.g. ..._BIT_REALTIME vs ..._BIT_LATCHED). In the R/L display, the first digit is real-time, the second is latched, and 0 = normal/pass, 1 = fail/detected. A latched 1 with a real-time 0 means “this fault happened earlier and has since cleared” — clear the latch to reset it.

Common conditions

• BIT — the channel failed its built-in self-test.
• Open / overvoltage — the input is disconnected or exceeds the configured range (analog input modules).
• Signal loss — the input fell below the configured minimum amplitude or frequency (e.g. VR).
• Termination fault — a fault in the channel’s input termination.
• Summary — an aggregate: set if any individual condition on the channel is set. Check the summary first, then drill down to find which condition tripped it.

Enabling and clearing

• Per-channel status reporting must be enabled with naibrd_XX_SetChanStatusEnable(). When it’s disabled, the module reports no status for that channel — and status-driven interrupts won’t assert either.
• Latched status stays set until you clear it, using the module’s clear-status function (e.g. naibrd_VR_ClearChanMappedStatus()) with the latched selector. Real-time status needs no clearing — it follows the live condition.
• PBIT (power-on BIT) runs only once, at power-on; check whether it completed with naibrd_GetModulePBITComplete(). On a board that hasn’t been power-cycled since install, PBIT may simply not have run yet — that’s not a fault.

What to check when a bit is set

Status bit set	Look at
BIT	Open input, hardware fault, or a wrong range setting — consult the module manual’s diagnostics.
Open / overvoltage	Input wiring and the configured range/polarity.
Signal loss	Excitation/power supply, thresholds, and minimum amplitude/frequency vs. the actual input.
Latched set, real-time clear	A past event that has cleared — clear the latch to reset it.

Related

• Opening a Software Handle to Your Board — opening a device (where OPEN_FAILED / NOT_OPEN come from)
• Connecting to Boards — cabling, network, and reachability (where TIMEOUT / COMM_ERROR come from)
• NAI Ethernet Protocol APIs — the transport layer and its protocol-level codes
• Software Development Guide 1.X · Software Development Guide 2.X — using the SSK