crosscontrol CCpilot VS 12” Programmer's Manual

Download

Page 1

Document revision: C

2018-06-26

CCpilot VS 12”

Programmer’s Guide

www.crosscontrol.com

Page 2

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

Contents

1. Introduction ....................................................................................................................................3

1.1. Convention and defines .......................................................................................................... 3

1.2. List of abbreviations .................................................................................................................. 3

1.3. References .................................................................................................................................. 3

2. Interfaces .......................................................................................................................................4

2.1. Standard libraries ....................................................................................................................... 4

2.2. CCAux library ............................................................................................................................. 4

2.3. CCAux API calling convention ............................................................................................... 5

2.4. Telematics API ............................................................................................................................ 6

3. Board Support Package ...............................................................................................................6

3.1. Downloading and installing the BSP ...................................................................................... 6

3.2. BSP structure ............................................................................................................................... 6

3.3. Using the BSP ............................................................................................................................... 8

4. Software Development Kit ............................................................................................................9

4.1. Downloading and installing the SDK ...................................................................................... 9

4.2. Using the SDK ............................................................................................................................ 10

4.3. Debugging remotely .............................................................................................................. 11

5. Device specifics for CCpilot VS .................................................................................................12

5.1. CAN ............................................................................................................................................ 12

5.2. Analog video ............................................................................................................................ 13

5.3. Graphics .................................................................................................................................... 14

5.4. Serial Number Broadcast interface ...................................................................................... 14

6. Examples ......................................................................................................................................15

6.1. Building applications with the SDK ....................................................................................... 15

Technical support ............................................................................................................................19

Trademarks and terms of use ........................................................................................................19

Revision history

Revision

Date

Author

Comments

2017-11-23

Released

2018-05-16

Chapter on writing Qt full screen applications added

2018-06-26

Removed Qt fullscreen workaround chapter (moved to Knowledge Base aritcle on the CrossControl customer support site)

Page 3

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

1. Introduction

This document contains device specific reference information describing application development and APIs used when developing applications for the CCpilot products supported in the CCLinux platform (currently, this includes the CCpilot VS device). Additionally, this document contains information on how to build a custom Linux operating system for your device based on the CCLinux reference system.

Several functionalities are available using operating system or de-facto standard APIs. These may be briefly mentioned but not further described within this documentation.

A good prior understanding of Linux programming is needed to fully benefit from this documentation. It is also recommended to read the Software Guide for your CCpilot device prior to reading this document.

1.1. Convention and defines

This document covers all devices included in the CCLinux platform. For the sake of example, the CCpilot VS device is sometimes used throughout this document. Any significant device differences will be stated. When the <xx> is used, it should be replaced with the proper device name (VS, for instance).

The observe symbol is used to highligt information in this document, such as differences between product models.

The exclamation symbol is used to highlight important information.

Text formats used in this document:

Format

Use

Italics

Paths, filenames, definitions.

Bolded

Command names and important information

1.2. List of abbreviations

API

Application Programming Interface

BSP

Board Support Package

CCAux

CrossControl Common Aux Control

LED

Light Emitting Diode

Main Processor running Linux

Operating System

SDK

Software Development Kit

System Supervisor co-processor

1.3. References

For further information on the device software and the available APIs see the following references.

[1] CCpilot VS – Software Guide [2] CCAux API documentation

Page 4

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

2. Interfaces

This section covers basic information on how to access the device hardware. Most of the hardware is accessed using the default Linux interfaces but some specific interfaces may require additional functions to be accessed.

Table 1 lists the API used to access each interface. These interfaces can be grouped into two categories; Standard operating system libraries (Std. API) and CCAux Library (CCAux API).

See also the operating system specific sections and additional documentation describing the software API.

Table 1: APIs used for different interfaces in CCpilot devices

Functionality

Std. API

CCAux API

Comment

CAN √

SocketCAN available through Linux.

Ethernet √

Standard Linux kernel drivers.

USB √

Standard Linux kernel drivers.

RS232 √

Standard Linux kernel drivers.

RS485 √

Standard Linux kernel drivers.

Video in √ √

Video4Linux2 API, gstreamer, and QtMultimedia can be used directly without CCAux API.

Digital outputs

√

Configurable input

√

Analog input

√

Status indicator

√

Backlight √

Ambient light sensor

√

Buzzer √

Power management

√

Your device might not support all interfaces stated here. See the Product Leaflet or Technical Manual of your device for a complete list of available interfaces.

2.1. Standard libraries

Most interfaces are accessed using standard libraries and access methods. Various access methods are possible to be used depending on the development environment and additional installed frameworks, such as Qt.

The standard libraries used for Linux are described in their respective documentation sources, such as MAN pages.

2.2. CCAux library

The CCAux API gives access to several hardware specific interfaces. The API functions of this library are documented in the CCAux API documentation.

Table 2 gives a brief introduction on the API’s found therein and their functions. Most API functions can be used from the pre-installed CCSettingsConsole application as well.

Page 5

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

Table 2: Short description of CCAux API contents and the supported devices

API

Description

Supported devices VS

About

Hardware information API related to the hardware configurations.

Yes Adc

Read built in ADC voltage information.

Yes

AuxVersion

Read firmware version information.

Yes

Backlight

Control display backlight settings and configure automatic backlight functionality.

Yes

Battery

Control battery related settings, if a battery is connected.

No Buzzer

Control the built-in buzzer.

Yes

CanSetting

Control CAN settings.1

Yes

Config

Control internal and external power up and power down settings and time configurations, including power button and on/off signal configurations.

Yes CfgIn

Get/set current status of configurable input signals.

Yes

Diagnostic

Get run time information about the device.

Yes

DigIO

Get/set current status of Digital Output signals.

Yes

FirmwareUpdate

Update/verify System Supervisor (SS) and other firmware.

Yes FrontLED

Override the default LED behaviour.

Yes 3

LightSensor

Read the light sensor values and get raw and/or calculated values.

Yes

Power

Read power status and control functions for advanced shut down behaviour.

Yes

Telematics

Control power to the telematics board, as well as basic initialization functions.

No4

TouchScreen

Change the touch screen profile between mouse or touch profile and other touch screen related settings.

No Video

Control the analogue video streams in terms of channel, size, scaling etc.

Yes

Most settings for CAN usage are available over the SocketCAN interface instead.

Consider careful usage for these functions, erroneous usage can result in a non-functional device.

CCpilot VS does not have a front LED, so this API controls the button backlight LED instead.

See the separate Telematics API instead.

2.3. CCAux API calling convention

The standard way to call CCAux API functions is shown below. Please adhere to this calling convention. Example code snippets for each function are available in the CCAux API documentation. Moreover, chapter 6.1 gives an example on how to call the CCAux API in order to set the front LED color.

/* U s a g e i n CC A ux A P I 2. x * / $ incl u d e ” M o d u l e. h ”

MO D U L E HAN D L E p M o d u le = Cro s s Co n t r o l: : G e tM o d u l e( ) ;

eE r r e rr = Mod u l e _ fu n ct i o n _ 1( p M o du l e , a r g , …) ;

Mod u l e _ re l e ase ( p M o du l e ) ;

Page 6

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

2.4. Telematics API

Some CCpilot devices support the external add-on telematics device CrossLink AI. The interfaces provided by this board are not accessed via the CCAux API, but through the separate Telematics API instead. This API is included in both the BSP and SDK and its functions are called in the same way as in CCAux API. Please refer to the Telematics API reference documentation for more information about the functions available.

3. Board Support Package

In order to create custom Linux images for CCpilot devices, a board support package (BSP) has been created. The BSP is a Yocto-project build system that produces complete Linux images for the CCpilot devices. It also includes necessary application and driver code, as well as example or template code that may serve as a basis for further application and driver development.

The open-source Yocto system has built-in package support with many thousands of maintained packages available, while also providing a set of standard tools and build guidelines. The BSP adds necessary drivers and applications required for the CCpilot board images. For more information regarding the Yocto project, please refer to the Yocto Project reference manual at

www.yoctoproject.org/docs/2.2/dev-manual/dev-manual.html

3.1. Downloading and installing the BSP

The BSP package comes in the form of a gzipped tar archive which can be acquired from the CrossControl support site. The BSP was created on an x86-64 machine running Ubuntu 14.04.5 LTS and must be unpacked to a Linux host machine/build server. Much disk space (at least several hundred gigabytes) and memory is required for the Yocto system, as the folder structure tends to grow quickly in size. Please refer to the Yocto Project reference manual mentioned earlier for information about required dependencies.

3.2. BSP structure

This chapter will go through the structure of the BSP, covering CrossControl specific parts. For other third party components (Qt, OpenEmbedded, Yocto, etc.), please refer to their respective reference documentation.

Initially, the BSP base directory only contains CrossControl folders. All other required third party tools are provided as hash-files which will be downloaded from remote repositories upon first build. The following subsections will describe these initial folders.

Internet connection is required to build BSP.

While most components in the BSP are released under various open source licenses, others are of proprietary nature and protected under the CrossControl Software License. Be aware of which license applies and comply with the license terms.

VS is the internal CrossControl code name for the CCpilot VS architecture/platform; therefore the

BSP contains references to the VS platform such as “PLATFORM_VS”. The same applies for other CCpilot devices. Additionally, CrossControl specific components are named “cc”, such as “meta-cc” and “recipes-cc”.

Page 7

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

3.2.1. Apps

Contains the source code to CrossControl-developed libraries and applications such as CCAux API library, CCAux daemon, CCLauncher, CCSettingsConsole, CCVideo, Telematic API, etc.

3.2.2. Drivers

The drivers folder contains the source code to the following CrossControl-developed drivers:

ss Handles communications between the System Supervisor (SS) and the main processor (MP, i.e. the Linux system) over the MP-SS SPI bus. This driver is required for the CCAux API to work.

<xx>-io Used to set the direction of the internal UART, in order to support either bootloader output to the update board or to the serial port of the SS.

3.2.3. Meta-cc

This folder contains the Yocto layer with all CrossControl developed board-specific recipes. See Table 3 for more details of the subfolders.

Table 3: Content of the subfolders in the meta-cc folder in the BSP.

Folder

Content

classes

Class recipes which can be inherited by other recipes:

 Class recipes to be inherited in recipes building applications and

modules with locally stored source code

 Class recipes which enable recipes to switch between Qt 4 and 5 when

building applications

conf

meta-cc layer configuration files for the <xx> machines. The machines are

based on more general machines. For instance, the ‘vs’ machine is based on the ‘mx6q’ machine, which in turn is based on the ‘mx6’ machine in the

meta-fsl-arm layer.

recipes-bsp

Contains the u-boot specific patches which adapt the default iMX6 u-boot configuration.

recipes-cc

Contains recipes for CrossControl-developed libraries and applications. These have the source code stored locally in the apps/ folder.

recipes-core

 Image recipes (both main and rescue system) for all supported devices;

used to produce the reference CCLinux image. This is a good starting place to add or remove features from the image.

 Psplash recipe, used to create a bootsplash image during the time

which the Linux system loads

 Initscript recipes

recipes-devtools

A recipe for input utilities, which are used to enable the touch panel driver for devices with a touch panel, such as CCpilot VS.

recipes-extended

A recipe to enable password free sudo privileges for users.

recipes-graphics

An init script for the Weston reference implementation of the Wayland graphics server.

recipes-kernel

 Kernel recipes; board-specific kernel patches, device tree, kernel

configuration files

Page 8

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

 Recipes for the CrossControl developed drivers in the drivers folder

recipes-qt

 Recipe-append to build QtMultimedia with the gstreamer backend  Recipe-append to separate some default Qt applications (calculator for

instance) from their examples-package, in order to enable individual installation

3.2.4. Platform

The platform folder contains a folder for each of the CCLinux devices as well as one common folder. These folders contain environment-setup scripts, extra Makefile rules to build individual system components with bitbake, and the configuration files for configuring the build system. The file local.conf can be modified to change the default Yocto download directory etc. If you want to add a new layer to the Yocto build, it must be added to the bblayers.conf file.

When building, the working directory build will be located in the platform/<xx> directory, as well as the resulting images.

3.2.5. Tools

Contains scripts to be used for device OS update. See the CCpilot VS – Software Guide for instructions on how to use them.

3.3. Using the BSP

The purpose of this chapter is not to give the reader a full description of the Yocto build system and all its possibilities; but rather give useful tips on how to build Linux images and application binaries from within the BSP.

3.3.1. Building Linux images

Out of the box, the BSP produces a CCLinux image containing a reference implementation, as described in the CCpilot VS – Quick Start Guide. The reference implementation is intended to be used as a basis for creating custom images.

The first time building the image will take several hours, depending on your host machine. Subsequent builds will be quicker as Yocto reuses all unchanged components from previous builds.

Depending on your host machine, you might need to edit the platform/<xx>/local.conf file. For instance, the default download directory can be changed; and if you have limited disk space, there is a setting for removing temporary files once builds are completed. However, removing temporary files will slow down your build process.

In the BSP root directory there is a Makefile containing rules to make main and rescue images for all CCLinux devices. For instance, to make the CCpilot VS rescue image, type

$ m a k e vs- r es c u e

make will automatically source the environment scripts in the platform folder and invoke bitbake to bake the image recipe in the meta-cc/recipes-core/images directory.

The resulting image is located in platform/<xx>.

Page 9

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

To build your own custom Linux image, either edit the image recipe right away, or make a new

recipe and add a new rule for it to the Makefile. If choosing the latter, don’t forget to add a rule to

the platform/<xx>/Makefile as well.

See the CCpilot <XX> - Software Guide for your CCpilot device for instructions on how to program the images to the device.

3.3.2. Building applications

Provided there exists a recipe for the application, building with the BSP can be done in two ways. The first method is the most straightforward whereas the second can be more convenient during development as it is more flexible and fast.

First method:

1. Include the recipe for the application in the image recipe:

IMA G E _ IN S T A LL + = “ap p l ic a t i o nna m e ”

2. Make the image as usual:

$ m a k e <i m a g er u l e >

Second method:

1. Make sure you are in the platform/<xx> folder and source the environment script:

$ s o u r ce o e -e n v

2. Use bitbake to build your application:

$ bi t b ake < app l i c ati o n n a me >

Both methods will put the resulting application binaries in platform/<xx>/build/tmp/work.

In the second method, additional bitbake commands can be invoked. For instance, use the –c flag to recompile the application without re-fetching the source files.

4. Software Development Kit

This section is dedicated to useful tips and hints about how to use the Software Development Kit (SDK) on a Linux development host for application development and debugging purposes.

The SDK is based on the Yocto Project SDK. Refer to the Yocto Project SDK Developer’s Guide (www.yoctoproject.org/docs/2.2/sdk-manual/sdk-manual.html) for additional information and tips.

4.1. Downloading and installing the SDK

The toolchain included in the SDK is an ARM GNU/Linux cross compiler based on the standard GNU GCC compiler toolchain. Additionally, the SDK contains header and library files for CCAux API and other peripherals. To get the SDK, visit the CrossControl support site. For support on SDK issues, please contact CrossControl directly.

Page 10

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

The SDK comes in the form of a self-extracting shell script. It contains precompiled binaries for 64-bit x86 Linux systems. To install the SDK, move the script to the host computer and run the following shell command:

$ s h s cri p t n am e . s h - d < s d k i n s t all d i r>

Omitting the -d flag will install the SDK to the default directory, /opt/poky/2.2.1.

Example output from installing the CCpilot VS SDK to /opt/sdk/:

$ s h p ok y - g l ib c - x86 _ 6 4 -c c p i lot - vs-i m a g e- v 1 0 00 - c ort e x a9 h f - neo n - t oo l c hai n -

2.2 . 1 . s h - d / o p t /sd k / Po k y ( Yo c t o Pro j e c t R efe r e nce D i st r o ) SD K i ns t a l l er v e r si o n 2.2 . 1 ===================================================== ============ Yo u a r e a b o u t t o i ns t a l l t h e SD K t o " / o p t / s dk/ " . Pro c e e d[ Y / n ]? Y

Ext r a c ti n g S DK. . . . .. . . . . . .. . . . . ..d o n e

Set t i n g it u p .. . d o ne SD K h a s b e e n su c c e s s f u l ly s e t u p a nd i s r e ad y t o b e u sed .

The SDK for CCpilot VS is named poky-glibc-x86_64-ccpilot-vs-image-v1000-cortexa9hf-neontoolchain-2.2.1.sh and was created using an x86-64 machine running Ubuntu 14.04 LTS.

4.2. Using the SDK

4.2.1. Starting a new session

Once installed, the SDK contains the sysroots directory with target and host system root file systems, and an environment setup file; environment-setup-XXXX-linux-gnueabi. The environment setup file exports the correct $PATH and other important build environment variables, such as $CC and $CFLAGS. (Read the file content to get an understanding of the default settings).

This file needs to be sourced before using the SDK each time a new shell session is started:

$ s o u r ce e n v i ro n m e nt - s et u p - XXXX- li n u x - gn u e a b i

Now the cross-compiler is ready to use.

4.2.2. Using correct development headers

The SDK is released containing binary images. This package contains libraries available at the unit and all header files for utilizing them. The header files are located in:

<sdk-install-dir>/sysroots/<targetsysroot>/usr/include/

and the libraries are found in these two directories:

<sdk-install-dir>/sysroots/<targetsysroot>/lib/

<sdk-install-dir>/sysroots/<targetsysroot>/usr/lib/

These directories are automatically added to the search path when sourcing the environment setup script and don’t need any special consideration.

Page 11

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

If additional development files placed outside of the SDK installation directory is to be used they can be added to the compiler search path by appending the $CFLAGS/$CXXFLAGS variable. This can be done either in the project settings or in the Makefile using:

CFL A G S += – I <pa t h - to-h e a d e rfi l e -di r > -L < p a t h - to- l i br a r y -di r >

4.2.3. Compiler optimizations

The environment setup script automatically sets the –mcpu=<cpu> compiler flag for optimizing the code for the instruction set generated for the specific processor. Additionally, floating point computations are automatically set to use hardware acceleration (–mfpu=<fpu>).

In order to optimize floating point additionally, append the -funsafe-math-optimizations flag to the $CFLAGS/$CXXFLAGS environment variables.

To see which optimizations are done by default, study the content of the environment setup script. All these settings can be overridden after the script has been sourced. See the compiler documentation for additional information about available optimizer flags.

4.2.4. Special considerations using CCAux API

In order to build applications using functions from the CCAux API library two steps need to be specially considered in either the project file or the Makefile:

1. The $LD variable should be overridden to use the same content as the $CXX variable

2. The $CFLAGS/$CXXFLAGS must be appended with the -DLINUX flag

If omitting these steps, the build will fail. See chapter 6.1 for examples of how to build CCAux API applications.

4.3. Debugging remotely

To use GDB to debug an application running on the device, the application must have been compiled with the -g flag. Start gdbserver on the device:

~$ g d b ser v e r :1 0 0 0 0 t e s t App l i c ati o n

Then start the host GDB and connect to the server:

$ a rm- p o k y- l i n ux- g n u e abi - g db t e s tAp p l i cat i o n $ ( g d b ) t a r g e t r e m o te Y . Y .Y . Y : 1 000 0

Above Y.Y.Y.Y is the IP address of the device. Then issue the set sysroot command:

$ ( g d b ) se t sys r o o t $ S D K TAR G E T SYS R O O T

You can now debug the application normally, except that rather than to issue the run command one should use continue since the application is already running on the remote side.

Note that it is possible to fully debug the application but not to make system calls made by the application. Such system calls include calls to the soft float library, like divide, add or multiply on floating point variables. It is therefore recommended to use next rather than step when such system calls are being made.

Page 12

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

5. Device specifics for CCpilot VS

This section is dedicated to device specifics that require extra attention when programming.

5.1. CAN

In Linux, CAN is interfaced using SocketCAN which is a widely used CAN communication interface for Linux environments, and is a standard used in the Linux kernel.

Usage of SocketCAN requires knowledge of some system specific settings and details described herein. For additional SocketCAN information see the official SocketCAN documentation.

5.1.1. Configuration of the device interface

The device node files for the CAN interfaces are can0 … can3 (for a device with 4 CAN interfaces). The interfaces should be shown when listing all network interfaces with the ifconfig command. The device drivers are implemented as loadable kernel modules. The modules are can_dev.ko and flexcan.ko. Startup scripts handle the loading of the kernel modules upon start-up.

When the device has finished its start-up, the CAN driver modules are loaded as a part of the kernel. This can be checked via terminal access using lsmod command:

$ l s m o d | g r ep c a n fle x c a n 100 9 2 0 ca n _ d e v 8641 1 f l e x can , x l in x

Since the drivers are compiled as modules, unnecessary protocols may be removed or new modules inserted according to user needs.

The CAN bus itself is not initialized during start-up, it only loads the drivers. Before any communications can be executed, user must set correct bus speed (as an example 250kbps) by first writing value into bitrate parameter:

$ s u d o ip l i nk s e t c a n 0 typ e can b i t rat e 2 5000 0

and then setting interface up with ifconfig:

$ s u d o i f c o n fig c a n0 u p

After this, ifconfig should show can0 as a network interface:

$ i f c o nfi g ca n 0 L i nk e n c ap: U N S PEC H W add r 0 0 - 00-00- 00- 00- 00 UP R U N N ING N O AR P M TU: 1 6 Met r i c:1 RX p a c k ets : 0 e rro r s :0 d r o p ped : 0 ove r r uns: 0 f ra m e : 0 TX p a c k ets : 0 e rro r s :0 d r o p ped : 0 ove r r u ns: 0 c arri e r :0 co ll i s i on s : 0 t xq u e u ele n : 1 0 RX b y t e s:0 ( 0 .0 B ) TX b y t es: 0 ( 0.0 B ) Inter r u p t:3 1

5.1.2. Configuring the CAN socket transmission buffer

By default, the CAN driver is configured with a transmission buffer that can hold 10 CAN frames. As each frame is sent on the bus, the buffer is cleared. However, it is possible to write frames to the socket faster than the frames are sent, especially if your messages are low-priority frames on a

Page 13

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

high-traffic bus. If your application needs to send more than 10 CAN frames in bursts, it might be a good idea to increase the size of the transmission buffer:

$ i f c o nfi g c an0 t xque u e l e n 1 0 0

5.1.3. Bus recovery options

It is possible to implement automatic bus recovery after bus off has occurred. State changes are automatically detected and controller is re-initialized after the specified time period.

Automatic bus recovery from bus off state is by default turned off. It can be turned on using the ip command, where the wanted restart period in milliseconds is set. For example, a 100 ms restart period for can0 is set from command line like this:

$ i f c o nfi g c an0 d o wn $ i p l i nk s e t c a n 0 ty p e c an r e s t ar t -m s 1 00 $ i f c o nfi g c an0 up

Same commands apply for all available CAN interfaces by replacing can0 appropriately. The period is possible to set as needed by the application. Value zero turns automatic bus recovery off.

Warning: Enabling automatic bus recovery may disturb other nodes on the bus, if CAN interface is incorrectly initialized.

5.2. Analog video

For QML applications with analog video, CrossControl recommends using the QtMultimedia framework rather than CCAux API since the video performance is higher and development process quicker. For non-QML applications, CCAux API is recommended.

5.2.1. Analogue Video using QtMultimedia

CCLinux includes an example QML application CCVideo for displaying analog video using a QtCamera instance. This application is for test purposes only, CrossControl recommends

implementing the video functionality into your application for correct behavior. The source code for CCVideo is provided in both the BSP and SDK.

QtMultimedia uses the gstreamer backend and the application must export the correct video source:

set e n v ("Q T _ G ST R E A M E R_ C A M ERA B I N _ V I D E O SRC " , "im x v 4 l 2vi d e osr c " , 1) ;

5.2.2. Analogue Video using CCAux API

There are some design constraints on the usage of analog video and CCAux API that is important to highlight, to create a better understanding of what can be done and what is necessary to do within the applications. Below is a brief video API description for the developers to consider.

The most important CCAuxVideo API functions are as follows:

Initialize (will open file handles, setup basic settings and request frame buffers), select deviceNr=1 for input channel 1:

Vid e o _ ini t ( V IDE O H A NDL E p Obj , u nsig n e d c h a r de v i c e Nr )

Select the active channel 1-4, corresponds to the physical port number:

Page 14

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

Vid e o _ set A c t ive C h a nne l ( VID E O H A NDL E p Obj, V ideo C h a nne l cha n n e l )

CCpilot VS only has one video channel.

Set the area where video is shown:

Vid e o _ set V i d eoA r e a (VID E O HAND L E pOb j , uns i g ned s h o rt t o p Le f t X , unsi g ned sho r t t op L e ftY, u n s ig n e d s h o r t bo t t o mRi g h t X, u n s i gn e d s h o rt b o tto m R i g ht Y )

Enable or disable (horizontal) mirroring of the video image:

Vid e o _ set M i r ro r i n g ( VID E O HAND L E pOb j , CCS t a t us m o d e)

Show (or hide) video image:

Vid e o _ sho w V i deo ( V IDEO H A N DLE p O bj , boo l s ho w )

Further and more detailed API information can be found in the CCAux API documentation.

5.3. Graphics

The graphics framework uses the Wayland protocol reference implementation Weston for graphics operations. Wayland is is fast and efficient, and is used by all modern major Linux desktop systems, giving it vast standard support in the Linux user space world.

For instance, Qt has a plugin that enables the Qt libraries to be built for Weston. For Qt applications the impact for that means that it simply needs to be started with a specific flag, -platform wayland-egl, and built with the correct development libraries. In CCpilot VS, this flag has been set to the default graphics framework, hence there’s no need to pass the flag.

Weston includes a windowing system, enabling several applications to be run overlapped.

The Wayland protocol does not allow its clients (Qt applications etc.) to have any information about where on the screen the client is positioned. Therefore, some Qt functions, like QWidget::pos(), will always give a zero return.

5.4. Serial Number Broadcast interface

The device has a Serial Number Broadcast service (SNB). The SNB does not have programming interface at the device end, but the broadcasted data output can be handled elsewhere; even in another device if required.

The message sent is a multicast UDP datagram to address 224.0.0.27. The message contains a char array with three values separated by tabs; Serial number, Firmware version and device type. The sender’s IP address is available in datagram headers.

Example data contents (without quotes):

“PR 0 1 <tab > 1 0 .0. 0 < t ab > 0 ”

An example implementation of the data listener is available in the BSP: apps/snb/snb_reader.c.

Page 15

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

6. Examples

Source code for the example applications included in the CCLinux reference image (CCSettingsConsole, CCSettings, CCVideo, CCLauncher, CCMultitouchDemo, etc.) is provided in both the SDK and BSP. These can be used as templates or starter points for your applications.

Example snippets on how to call the functions provided by CCAux API are found in the CCAux API documentation and in the examples folder of the CCAux API source code provided in the BSP. Additionally, this chapter provides examples on the build process.

6.1. Building applications with the SDK

This chapter gives two examples on how build a small example application which uses CCAux API functions to set the color of the status LED. The first example shows how to build a C++ application using a Makefile. The second example shows how to build a Qt application with qmake to autogenerate the Makefile.

6.1.1. C++ Makefile example

This example shows how to build a C++ application example using a Makefile. The source file example.cpp is listed below. The file consists of a simple main function calling the status LED

functions.

/** * e x a mple . c pp ** /

#i n c l ude < s t dio . h > #i n c l ude < F r ont L E D .h> #i n c l ude < C C Au x E r r o rs . h >

usi n g nam e s p ace C r o ss C o n t ro l ;

int m a i n ( v o i d) { pri n t f(" S e t t i ng F r ont L E D to b l ue! \r\ n " ) ;

FRO N T L EDH A N D L E p L e d = G e tFr o n t L ED ( ) ;

eE r r e rr; err = Fro n t L ED_ s e t Sta n d a rdCo l o r(p L e d , BL U E );

if ( e r r != E R R_ S U C C ESS) p r i n t f( " A n err o r o c c u r r ed! \r\ n " ) ;

Fro n t L ED_ r e l ease ( p L ed ) ; ret u r n 0; }

Following is an example Makefile that is used to build example. The additional -Wall flag enables all warnings and is recommended. This file can easily be expanded to build more complex applications.

Page 16

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

# # M a k e fil e f o r e x a mpl e u si n g F ro n t L e d # # N O T E: be f o re r u n ning m a ke , t he S D K e nvi r o nme n t mu s t b e se t up b y # so u r cin g t he e n v iron m e nt f i l e #

TAR G E T =ex a m p le LD = $ (C X X)

CC_ O B J S = $ ( TAR G E T ).o C_ O B J S =

OBJ S = $( C C _ OBJ S ) $(C _ O B JS)

CXX F L A GS + = -DL I N U X - W a l l CFL A G S += - D LIN U X -Wa l l LDF L A G S+= - l cc - a u x2 - l p thr e a d

CCC M D = $ ( C C) - c $( C F L AGS ) CXX C M D = $ ( CXX) -c $ ( C X XFL A G S )

all : cle a n

$(T A R GET )

$(T A R GET ) : $(O B J S) $(L D ) -o $@ $ ( O BJS ) $ (LD F L A GS)

# p a t t ern r u l es f o r ob j e ct f i l e s %.o : % .c $( C C C M D ) $ < -o $ @

%.o : % .cp p $( C X X C MD ) $ < - o $ @

cle a n : rm -rf * . o *. e l f *.g d b *~ $ ( T ARG E T )

To build example, make sure the environment setup script has been sourced, and then issue the following command:

$ m a k e ex a m p l e

make will expand the content of the Makefile and the previously sourced environment setup script to the following output (for CCpilot VS):

Page 17

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

6.1.2. Qt qmake example

This example shows how to build a Qt application example-qt. The source file example-qt.cpp is listed below. The file consists of a simple main function calling the status LED functions and opening a MessageBox widget.

/** * e x a mple - q t. c p p ** /

#i n c l ude < F r ont L E D .h> #i n c l ude < C C Au x E r r o rs . h > #i n c l ude < Q M ess a g e Box > #i n c l ude < Q t Wid g e ts / Q A ppl i c a t io n >

usi n g nam e s p ace C r o ss C o n t ro l ;

int m a i n ( i n t a r g c , c h a r *ar g v [ ]) { QAp p l i cat i o n a( a r g c, a r g v); QMe s s a g eBo x msg ;

msg . s e tTe x t ( "Set t i ng F r o ntLE D t o r e d ! \ r \n") ; msg . s how( ) ;

FRO N T L EDH A N D L E p L e d = G e tFr o n t L ED ( ) ;

eE r r e rr; err = Fro n t L ED _ s e t St a n d ard C o l o r( p L e d , R E D ) ;

if ( e r r != E R R_ S U C C ESS) p r i n t f( " A n err o r o c c u r r ed! \r\ n " ) ;

Fro n t L ED_ r e l ease ( p L ed ) ;

a.e x e c ();

ret u r n 0; }

Following is an example Qt project file that is used to build example-qt. It can easily be expanded for more complex applications.

# # E x amp l e - qt . p r o #

Page 18

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

QT + = cor e g ui w i d g et s

TAR G E T = e x a mpl e - qt TEM P L A TE = a p p SOU R C E S + = e xa m p l e - q t . c pp

uni x : { li n u x - oe-g+ + { mess a g e (Co m p i l i n g f o r Y o c t o L i n ux) DEF I N E S +=L I N U X LIBS + = -l c c -aux 2 } }

To autogenerate the Makefile from the project file, make sure the environment setup script has been sourced, and then run qmake:

$ q m a k e Pro j e c t M E S S AG E : C o mp i l i ng f o r Yo c t o Li n u x

Then, run make in order to build the application:

$ m a k e ex a m p l e - qt

make will expand the content of the Makefile and the previously sourced environment setup script to the following output (for CCpilot VS):

arm-pok y - l in u x - g nu e a b i -g + + - m a r c h= a r m v7 - a - m arm - m f p u = n e o n - mfl o a t abi = h a rd - m c p u = c o rtex - a9 --s ysro o t =/o p t / vs - s d k/s y s r o ot s / c o rt e x a 9 hf - n e on po k y - l in u x - g nue a b i - c - p i p e - O 2 - p i p e - g - f e l im i n a t e - u n use d - d eb u g - t ype s - O 2 Wall -W -D_ R E E N TR A N T - f P IC - D L INU X - D Q T _ N O _D E B U G - D Q T_W I D G ETS _ L I B DQ T _ G U I_L I B -D Q T _ COR E _ L IB - I . - I . . / vs - s d k/ s y s r oot s / cort e x a 9h f - neo n - p ok y li n u x -gn u e a b i/ u s r /i n c l u de / q t 5 - I . ./ v s - sdk/ s y s roo t s / cor t e xa9 h f - n e o n - po k y - li n u x gn u e a b i / u s r / i nc l u d e /qt 5 / Q tWi d g ets -I . . / vs- s d k/s y s r o ot s / c o rte x a 9 hf - n eo n - p o ky li n u x -gn u e a b i/ u s r / in c l u d e/q t 5 /Qt G u i - I ../ v s - sd k / s ysro o t s /co r t e xa9 h f -n e o n-po k y li n u x -gn u e a b i/ u s r / in c l u d e/q t 5 /Qt C o r e - I. - I . . /v s - sdk / s y sroo t s / co r t e xa9 h f -ne o n po k y - l in u x - g nue a b i / u s r / l ib/ q t 5 /mk s p e cs/ l i n ux - oe- g ++ - o ex a m p l e - q t .o e x a m pl e qt . c p p arm-pok y - l in u x - g nu e a b i -g + + - m a r c h= a r m v7 - a - m arm - m f p u = n e o n - mfl o a t abi = h a rd - m c p u = c o rtex - a9 --s ysro o t =/o p t / vs - s d k/s y s r o ot s / c o rt e x a 9 h f - n e on po k y - l in u x - g nue a b i - W l ,-O1 - Wl, --h a sh - s t yle = g n u - W l ,--as- n e ed e d -Wl , - O1 - o ex a m p l e-q t e xam p l e - q t . o - l cc - a u x2 - l Q t5Wi d g e ts - l Qt 5 G u i - l Q t 5Co r e -l E G L lGL E S v2 - l p thre a d

Page 19

CCpilot VS 12”

Document revision: C

Programmer’s Guide

2018-02-26

www.crosscontrol.com

Technical support

Contact your reseller or supplier for help with possible problems with your device. In order to get the best help, you should have access to your device and be prepared with the following information before you contact support.

 The part number and serial number of the device, which you find on the brand label.  Date of purchase, which is found on the invoice.  The conditions and circumstances under which the problem arises.  Status indicator patterns (i.e. LED blink pattern).  Prepare a system report on the device, using CCSettingsConsole (if possible).  Detailed description of all external equipment connected to the unit (when relevant to the

problem).

Trademarks and terms of use

All trademarks sighted in this document are the property of their respective owners.

CCpilot is a trademark which is the property of CrossControl.

Linux® is a registered trademark of Linus Torvalds.

Microsoft® and Windows® are registered trademarks which belong to Microsoft Corporation in the USA and/or other countries.

Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.

Qt is a registered trademark of The Qt Company Ltd. and its subsidiaries.

CrossControl is not responsible for editing errors, technical errors or for material which has been omitted in this document. CrossControl is not responsible for unintentional damage or for damage which occurs as a result of supplying, handling or using of this material including the devices and software referred to herein. The information in this handbook is supplied without any guarantees and can change without prior notification.

For CrossControl licensed software, CrossControl grants you a license, to under CrossControl’s intellectual property rights, to use, reproduce, distribute, market and sell the software, only as a part of or integrated within, the devices for which this documentation concerns. Any other usage, such as, but not limited to, reproduction, distribution, marketing, sales and reverse engineer of this documentation, licensed software source code or any other affiliated material may not be performed without written consent of CrossControl.

CrossControl respects the intellectual property of others, and we ask our users to do the same. Where software based on CrossControl software or products is distributed, the software may only be distributed in accordance with the terms and conditions provided by the reproduced licensors.

For end-user license agreements (EULAs), copyright notices, conditions, and disclaimers, regarding certain third-party components used in the device, refer to the copyright notices documentation.