Programming applications with the CEI-x30 API

Following the outline below, you can easily incorporate simple features from the CEI-x30 API into your application.

1.     For your application to interface to any CEI-x30-SW supported products the device must first be initialized.  Invoke the AR_OPEN routine with parameters as described in the API Routines section. 

2.     Assign the characteristics of the transmit and receive channels if the default configuration is not appropriate.  This is performed with multiple invocations of either AR_SET_DEVICE_CONFIG.

3.     Perform receiver buffer mode selection based on individual channel/protocol usage via the routine AR_SET_DEVICE_CONFIG.  Using buffered mode for multiple channels of the same protocol provides channel-specific access to received data, where merged mode provides for single receive channel access to selected channel data. 

4.     Once channel configuration is complete, invoke AR_GO to initiate data processing. 

5.     Invoke AR_PUTWORD and AR_GETWORD, or one of the many message transmit/receive API routines available to send and receive single ARINC 429 messages, respectively, (alternatively you could use the message scheduling feature). 

6.     When communication is complete, invoke AR_STOP to suspend active data processing. 

Subsequently, you could invoke AR_GO again to restart message processing. 

7.     On termination of the application, invoke AR_CLOSE to release all resources acquired during initialization.  It is very important that all applications invoke AR_CLOSE upon termination; otherwise, the operating system does not release the resources acquired when the API was initialized.

The example wrap program source code, contained in TST_CNFG.C, is supplied with your installation.  This program demonstrates the use of the API for the ARINC 429 and equivalent protocols.

When calling the utility routines that return a status value, it is important to verify the returned status indicates success; otherwise, the application may not be aware that an important function may have failed to fulfill a requested operation.

Example Routines in C – Summary

Example applications demonstrating various CEI-x30 API features are provided in the C programming language, as described in the following paragraphs.

Tst_cnfg.c

The example source file TST_CNFG.C is included with your installation.  Access this example executable under the Windows operating system as follows:

For Windows 7, XP and Server 2008R2, access the "Test Configuration" shortcut created in the Abaco CEI-x30-SW program group located by selecting START->PROGRAMS->Abaco CEI-x30-SW on the Task Bar.  For Windows 10/8.1/8, and Server 2012R1/R2, access the "Test Configuration" shortcut listed under the Abaco CEI-x30-SW group in Apps By Name or All Apps, or accessed via the CEI-x30-SW Shortcuts folder.

Within TST_CNFG.C are application-style routines demonstrating use of the API routines for the ARINC 429 protocol:

test_basic_arinc_429             An internal wrap test designed to demonstrate ARINC 429 API usage.  This routine enables internal wrap on all 429 receive channels.  It also assigns a bus speed of 12.5kbps and ODD parity to both transmit and receive channels.  Ten ARINC 429 messages are sent on each transmit channel and proper reception verified on the respective receive channel.

demo_advanced_arinc_429    A demonstration of the following advanced features available with CEI-x30 products:

Transmit Message Scheduling

Enhanced Label/SDI/ESSM Data Filtering

Snapshot Message Data Acquisition

Enhanced Time-tag Reset and Conversion

IRIG Time-tag Selection (if installed on hardware)

demo_discrete_io_features     A demonstration on the use of the Discrete I/O Channels and the respective API routines

demo_irig_features                A demonstration of IRIG features requiring an external IRIG connection:

IRIG DAC Threshold Adjustment

IRIG Bias (Offset) Time Assignment

IRIG Validity Determination

IRIG Time Conversion and Display

test_arinc_717                      An internal wrap test designed to demonstrate ARINC 717 protocol support.  This routine enables internal wrap on the ARINC 717 receive channel.  It also assigns a bus speed 768bps, a sub-frame size of 64 words, and a BPRZ selection to the ARINC 717 transmit and receive channels.   A frame consisting of a data pattern incrementing from $01 to $FF and sync words of $123, $224, $325, and $426 is transmitted and proper reception verified.

demo_pci_interrupts              This routine demonstrates how to setup a custom interrupt service routine, setup Label Filter Table triggers generating interrupt events, enabling interrupts, and retrieving interrupt event data from the queue.

custom_interrupt_handler       This routine is the custom interrupt service routine assigned within the example routine demo_pci_interrupts.

demo_programmable_channels        Demonstration of how to define software programmable/shared channels as transmitters or receivers.

Config_from_file.c

This application-level source code demonstrates the channel configuration and scheduled message definition from files features available with the CEI-x30-SW distribution.  Two files are available for each selected file type, XML and text, one for channel configuration of a two-channel board and the other defining four scheduled messages on each of two transmit channels.  The four data files used with this application are:

8 msg def.txt

8 msg def.xml

2 chan cfg.txt

2 chan cfg.xml

 

Multiprocess_test.c

Provisions for simultaneous multiple process access to a CEI-x30 board are supported under the Windows and Linux operating systems.  This feature is implemented in the standard API with minimal requirements on the application developer.  The example program contained in the source file multiprocess_test.c describes how one method of multi-process application may be implemented.

This example application is based on separate processes, one for ARINC  429 scheduled message transmission on multiple transmit channels, and others for ARINC 429 message reception on individual receive channels.  Regardless of the process invocation type, setup for the multiple process application is performed via invocation of the API routine AR_SET_PRELOAD_CONFIG, prior to invocation of AR_OPEN.

A single "transmit" process should be launched first, with subsequent invocation of one or more "receive" processes.  The "transmit" process loads the board using AR_OPEN, configure board and transmit channel specific parameters using AR_SET_DEVICE_CONFIG, and activate data processing using AR_GO.  After the "transmit" process invokes AR_GO, it is permissible to launch one or more "receive" processes.  A "receive" process first attaches to the board using AR_OPEN, then execute operations strictly confined to the particular channel to which that process is associated (in this case AR_SET_DEVICE_CONFIG and AR_GETWORDT).  When finished, each "receive" process invokes AR_CLOSE and terminates.  The "transmit" process should remain running until all "receive" processes have terminated; upon termination the "transmit" process invokes AR_STOP and AR_CLOSE.

While the previously discussed application API invocation order is recommended, it is not strictly required.  You may actually invoke a "receive" process first and terminate it last; however, multi-process applications should rely on a primary board-control process as the focus for board initialization, BIT functionality, and control of h/w message processing.

C# Support

The CEI-x30 API is an unmanaged DLL, not built using the .NET framework; however, a managed DLL wrapper allows you to use the CEI-x30 API library in your application development.  This reference solution consists of:

·          A managed wrapper class written in C# that encapsulates the CEI-x30 API function prototypes, constants, and data types.

·          A sample managed GUI written in C# that demonstrates use of the wrapper class to interact with a CEI-x30 product.

The managed wrapper class can be used with C#, VB.NET, or any of the managed languages .NET supports.  This documentation assumes familiarity with Visual Studio 2008 or later, and creating and running .NET applications.

The Reference Solution

The reference solution is a Microsoft Visual Studio 2008 solution in the CEI-x30-SW\Examples\C#\C# Wrapper Example folder, named ArincCsApplication.sln. When you open this solution, you will see two projects in the solution explorer window.

·          ArincCsApp:  This project creates the C# application ArincCsApp.exe, which allows you to perform a simple single ARINC 429 channel internal or external wrap test or monitor reception on a specific ARINC 429 receiver.

·          ArincCsWrapper:  This project creates the C# class library ArincCsWrapper.dll, which wraps the unmanaged CEI-x30 API functions, constants, and data types.

The Managed Wrapper Class

The ArincAPI namespace encapsulates all the API functions, Data Types, and Constant definitions. It is recommended you do not change this namespace name, as it identifies the wrapper and provides name separation when loaded into other projects.

The API static class contains managed entry points for most of the CEI-x30 API functions from the unmanaged CEI-x30 API library (with the prefix "ar_" omitted). The .NET interop environment requires that managed entry points be contained in a static class. This class is found in file API.cs, with supported functions listed below.

The DataTypes namespace contains managed equivalents of the structures required by the unmanaged CEI-x30 API library. The managed equivalents are implemented using C# structures, classes, and unions. This namespace is found in file DataTypes.cs.

The Constants static class contains managed definitions of the constants required by the unmanaged CEI-x30 API library. This class is found in file Constants.cs.

Adding the Managed Wrapper to an Existing .NET Application

First, it is suggested (but not required) that you add the C# project ArincCsWrapper to your existing .NET solution.

Then, in the Solution Explorer, right-click your project and select "Add Reference". If you added ArincCsWrapper to your solution, click the Projects tab and select ArincCsWrapper. Otherwise, select the Browse tab and locate ArincCsWrapper.dll on your disk.

At the top of each of your code pages, add the following lines:

using ArincAPI;

using ArincAPI.DataTypes;

using System.Runtime.InteropServices;

You may need to edit the file API.cs in the ArincCsWrapper project. At the top of this file is a statement that defines exactly where cdev_api.dll should be found.

You can now use the managed wrapper classes in your project.

C# Managed Wrapper Functions

The following is an alphabetical function list showing the link between the managed wrapper functions in the namespace/class ArincAPI.API, to the respective unmanaged CDEV_API.DLL function exports. 

Assign_Scheduler_Start_Offsets

ar_assign_scheduler_start_offsets

Bypass_Wrap_Test

ar_bypass_wrap_test

Close_Session

ar_close

Clear_Rx_Count

ar_clr_rx_count

Define_Periodic_Message

ar_define_msg

Define_Msg_Block

ar_define_msg_block

Enh_Label_Filter

ar_enh_label_filter

Execute_Bit

ar_execute_bit

Get_Board_Name

ar_get_boardname

Get_Board_Type

ar_get_boardtype

Get_Config

ar_get_config

Get_Data

ar_get_data

Get_Data_XT

ar_get_data_xt

Get_Device_Config

ar_get_device_config

Get_Error

ar_get_error

Get_Filter_Table

ar_getfilter

Get_429_Message

ar_get_429_message

Get_573_Config

ar_get_573_config

Get_573_Frame

ar_get_573_frame

Get_Label_Filter

ar_get_label_filter

Get_Latest

ar_get_latest

Get_Latest_T

ar_get_latest_t

Get_Msg_Block

ar_getblock

Get_Msg_Block_T

ar_getblock_t

Get_Next

ar_getnext

Get_Next_T

ar_getnextt

Get_Next_XT

ar_getnext_xt

Get_Snap_Data

ar_get_snap_data

Get_RX_Channel_Status

ar_get_rx_channel_status

Get_RX_Count

ar_get_rx_count

Get_RX_Status

ar_get_status

Get_RX_Storage_Mode

ar_get_storage_mode

Get_Time

ar_get_time

Get_Transmitter_Mode

ar_get_transmitter_mode

Get_Word

ar_getword

Get_Word_T

ar_getwordt

Get_Word_XT

ar_getword_xt

Go

ar_go

Interrupt_Buffer_Read

ar_hw_interrupt_buffer_read

Interrupt_Queue_Read

ar_interrupt_queue_read

Label_Filter

ar_label_filter

Modify_Msg

ar_modify_msg

Modify_Msg_Block

ar_modify_msg_block

Num_RX_Chans

ar_num_rchans

Num_TX_Chans

ar_num_xchans

Open_Session

ar_open

Put_Block

ar_putblock

Put_Block_Multi_Chan

ar_putblock_multi_chan

Put_Filter_Table

ar_putfilter

Put_429_Message

ar_put_429_message

Put_573_Frame

ar_put_573_frame

Put_Word

ar_putword

Query_Device

ar_query_device

Read_Scheduled_Msg_Block

ar_read_scheduled_msg_block

Read_Message_Schedule_Table_Entry

ar_read_message_schedule_table_entry

Reset_Device

ar_reset

Reset_Timer_Count

ar_reset_timercnt

Set_Config

ar_set_config

Set_Device_Config

ar_set_device_config

Set_573_Config

ar_set_573_config

Set_Multi_Thread_Protect

ar_set_multithread_protect

Set_ISR_Function

ar_set_isr_function

Set_Preload_Config

ar_set_preload_config

Set_Raw_Mode

ar_set_raw_mode

Set_Storage_Mode

ar_set_storage_mode

Set_Time

ar_set_time

Set_Timer_Rate

ar_set_timerrate

Set_Transmitter_Mode

ar_set_transmitter_mode

Sleep

ar_sleep

Stop

ar_stop

Update_Message_Block

ar_update_msg_block

Transmit_Sync

ar_xmit_sync

 

Visual Basic and VB.NET Support

The CEI-x30-SW distribution contains Visual Studio .NET solutions providing support for the VB.NET and C# programming languages.  These solutions are located in folders beneath the Examples\C# folder of the software distribution. 

Beneath the first folder “.Net Console Example”, the first folder CEIx30NetClass, contains a Visual Studio 2008 solution called x30Wrap.sln, which builds a VB wrapper class library over the standard API library cdev_api.dll, called Ceix30ClassLib.dll.  Within this library is the class “Arinc”, containing all of the necessary constants and function references to support application development with the CEI-x30 API.  The second folder Arinc429Example, contains a Visual Studio 2008 solution called Arinc429Example.sln, which is a very basic C# console application based on the source file CEIx30Class.cs, and demonstrating how to use the “Arinc” class for .NET application development.

Visual Basic Support

A text file, CDEV_API_VB.TXT, is provided to aid the Visual Basic programmer in using the CDEV_API DLL in the Examples\VB folder of the software distribution.  This text file contains the Function Declaration and Global Constant statements required to interface to CDEV_API.DLL.  You can manually copy and paste text from this file to your project, or you can use the Microsoft API Text Viewer utility included with Visual Basic.  For more information on the API Text Viewer, consult Microsoft Visual Basic documentation. 

The CDEV_API_VB.TXT is designed for use with any 32-bit version of Visual Basic; however, the VB example and API interface are recommended for use with Visual Basic version 6.0 or later.

Working with Unsigned Integers in Visual Basic

Visual Basic doesn’t support unsigned integers.  Since the CEI-x30 API library uses unsigned integers for some function parameters, problems can arise when attempting to set values in the upper half of the range.

Example

When a CEI-x30 API function uses an argument of C type unsigned short the equivalent type is integer in Visual Basic or short in VB.Net.  All are 16-bit values but the Visual Basic variable has a range of -32768 to 32767.  The C argument has a range of 0 to 65535.  A Visual Basic error is generated if an integer type is set to value greater than 32767.

Solutions

There are two solutions to this problem.  The easiest is to set the value of variables directly in Hex.  To set an integer variable to 65535 use: myVariable = &HFFFF.  (note the &H syntax) .  For setting long variables use the ending “&” as in myvar = &H12&.

The second solution is to convert the desired unsigned value to the signed equivalent.  This can be accomplished in a small utility function:

Function u_conv (unsigned as Long) as Integer

   Dim signed as Integer

   If unsigned > 32767 then

      signed = unsigned - 65536

   Else

      signed = unsigned

   End If

   u_conv = signed

End Function

When using returned values from CEI-x30 API functions the opposite conversion can be made.  Often, the returned values from CEI-x30 API functions simply need to be compared to the predefined values.

References

Alphabetical Function Index
Hierarchical Function Index

CEI-x30 API Description

API Status and Error Codes

Application Programming Utilities