CCpilot XM and CrossCore XM - Programmers Guide
CCpilot XM and CrossCore XM - Programmers Guide
7
PROGRAMMER’S GUIDE Date: Jun 24, 13
Programmer's guide
www.maximatecc.com
Contents
Revision history
Rev Date Comments
P1.0 2010-07-06
P1.1 2012-03-26 Minor updates
P1.2 2012-03-27 Corrections
P1.3 2012-05-11 Corrections
Update for CrossCore XM and All-Integrated
P1.4 2012-11-27
functionallity.
P1.5 2012-12-03 Updated after review
P1.6 2013-04-09 Updates: Smart and PowerMgr API.
Updates: API v1 -> APIv2 migration information
P1.7 2013-06-17
Companyname changes.
www.maximatecc.com
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
1. Introduction
1.1. Purpose
Developing applications for CCpilot XM and CrossCore XM is basically the same as developing any
application under Windows or Linux.
This document contains device specific reference information describing application development
and APIs used when developing applications for the XM device hardware.
These devices are available with both Windows and Linux operating system and this guide is
applicable for both operating systems. Operating system specific information is pointed out in the
text or addressed in the respective operating system sections.
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 Windows and/or Linux programming is needed to fully benefit from
this documentation.
Defines Use
CCpilot XM Information that is specific for CCpilot XM
CrossCore XM Information that is specific for CrossCore XM
XM device Information that applies to both CCpilot XM and CrossCore XM
The observe symbol is used to highligt information in this document, such as differences between
product CCpilot and CrossCore product models.
The A symbol is used to highlight information specific for CCpilot XM All-Integrated and CrossCore
XM All-Integrated.
The exclamation symbol is used to highlight important information.
Text formats used in this document.
Format Use
Italics Paths, filenames, definitions.
Bold Command names and important information
1.3. Identification
On the side of the XM device there is a label with version and serial numbers which identify your
unique computer. Take note of them. During service and other contact with the supplier it is
important to be able to provide these numbers.
www.maximatecc.com 3
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
1.4. References
For further information on XM device software and the available APIs see the following references.
[1] CCpilot XM and CrossCore XM – Software User Guide
[2] SocketCAN from the Linux kernel,
http://lxr.linux.no/linux+v2.6.31.14/Documentation/networking/can.txt
[3] CCAux API documentation (CC AUX x.x.x.x, available in the CC AUX SDK)
[4] CAN Interface Description (available within the Windows SDK)
www.maximatecc.com 4
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
2. Interface overview
This section covers basic information on how to access the XM device hardware. Most of the
hardware is accessed using the default Windows or Linux interfaces but some XM device specific
interfaces, such as CAN and Digital In, require additional interfaces to be accessed.
The table below lists the API used to access each interface. These interfaces can be grouped into
four categories. Standard libraries (Standard API), CCAux library (CCAux API), JIDA 32 Library
(JIDA 32 API) and Other Libraries (Other API).
Depending on product model, all interfaces may not be present on your specific model. See also the
operating system specific sections and additional documentation describing the software API.
Standard API
JIDA 32 API
CCAux API
Other API
Functionality Comment
Ethernet √
USB √
RS232 √
Video In √
Audio In / Out √
Digital In √
Status LED √
Backlight √
Ambient Light
sensor √
Buzzer √
Watchdog √
Power
management √
S.M.A.R.T √
User EEPROM √
WLAN √ √ Power management access through CC AUX API required
www.maximatecc.com 5
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
2.2.1. About
Contains an API for reading hardware configuration, unit data etc.
2.2.2. Adc
Contains an API for reading built in ADC voltage information.
2.2.3. AuxVersion
Contains an API for reading firmware version information.
2.2.4. Backlight
Contains an API for controlling backlight settings as well as configuring automatic backlight
functionality on CCpilot XM.
2.2.5. Buzzer
Contains an API for controlling the built-in buzzer.
2.2.6. CanSetting
Contains an API for controlling CAN settings. Note that other or similar CAN-related settings are
available through other API’s and in the Windows registry.
2.2.7. Config
Contains an API for controlling internal and external power up and power down settings and time
configurations, including power button and on/off signal configurations.
2.2.8. Diagnostic
Contains API’s for getting run time information about the XM device.
www.maximatecc.com 6
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
2.2.9. DigIO
Contains an API to get the current status of the digital input signals.
2.2.10. FirmwareUpgrade
Contains an API that allows for updating of different firmware components of the XM device.
Consider careful usage for these functions, erroneous usage can result in a non-functional XM
device.
2.2.11. FrontLED
Contains an API for overriding the default LED behaviour.
2.2.12. LightSensor
Contains an API for reading the light sensor values and getting raw and/or calculated values.
2.2.13. Power
Contains an API for reading power status and control functions for advanced shut down behaviour.
2.2.14. PowerMgr
Contains an API for delaying OS shutdown or suspend until the application is ready.
2.2.15. Smart
Contains an API for reading the remaining expected lifetime of the compact flash device and
limited device information. The API utilizes the device S.M.A.R.T. data in the background.
2.2.16. TouchScreen
Contains an API for changing the touch screen profile between mouse or touch profile as well as
other touch screen related settings on CCpilot XM.
2.2.17. Video
Contains an API for controlling the analogue video streams in terms of location, size, scaling etc.
2.2.18. Telematics
Contains an API for controlling power to the telematics board, as well as some basic initialization
functions.
www.maximatecc.com 7
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
/ * N ew u sa ge i n CC au x A PI 2 .x * /
# i nc lu de ” Mo du le .h ”
M O DU LE HA ND LE p Mo du le = cr os sc on tr ol :: Ge t Mo du le () ;
e E rr e rr = M od ul e_ fu n ct io n_ 1( pM od ul e, a r g, … );
M o du le _r el ea se (p Mo du l e) ;
When porting your application to CC AUX API v 2.X, the above differences is what you will need to
address for all instances calling the API functions in your code.
www.maximatecc.com 8
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
The XM device doesn’t deviate from the standard OS model in case when using the
ON/OFF signaling from hardware. Hence, an application that is able to terminate properly
using a normal operating system should be able to use the same solution on the XM device.
In case of additional prevention, the applications can and should listen to operating system
power management signals and/or power status signals via the CCAux API. The shutdown
process is a quick process and when shutdown signals occur the application shall terminate
quickly, i.e. be able to quickly abrupt a file write in progress and do not write large files
such as log files upon system shut down. A general design guide would be that an
application shouldn’t need more than a few hundred ms to make itself ready for shutdown
The CCAux PowerMgr API may be used by an application to delay OS shutdown and OS
suspend operations in some use-case scenarios. The application can delay shutdown until it
is ready with its operations.
Each write to permanent storage should be forced for synchronization, like (Linux
perspective):
C o mma n d / scri p t s ty le : # s ync
P r o gra mmi n g s ty le 1 : res = f sy cnc (f d );
P r o gra mmi n g s ty le 2 : res = sy s te m (“ s y nc ” );
It may be possible to add file system locks during startup as a startup script itself, to
prevent unnecessary stress on the flash. This approach needs proper usage on several
levels, making sure writes can be performed when they are supposed to be. File system
locks can also be added as an extra security measure, possibly in combination with file
system checks. But this may lead to longer startup times.
www.maximatecc.com 9
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
For Linux based system the application should follow startup scripts guidelines to make
sure that operating system signals are correctly passed to application, as found in the
Software Guide document.
The CCAux Smart API can be used by applications to monitor the expected lifetime of the
compact flash. It can be used to warn the user that a replacement is needed before the
compact flash becomes corrupt.
www.maximatecc.com 10
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
4.2.1. CAN
In Windows the CAN interfaces is accessed using the proprietary CAN API, see the CAN interface
description documentation within the Win32CAN SDK, reference [4]. The CAN drivers are
installed per default on the XM device but the SDK is needed in the development environment.
Note that settings for CAN are stored in the Windows registry. Some, but not all of these are also
available as settings in the CCAux API.
www.maximatecc.com 11
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
This can be considered an SDK for the CC AUX API in Linux, and it installs the header files to the
system include file directory, i.e. under /usr/include.
Development versions of the appropriate libraries can easily be installed on the development
computer. See the standard Ubuntu documentation for more details.
www.maximatecc.com 12
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
Above Y.Y.Y.Y is the IP address for the XM device. 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 the 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.
5.2.1. CAN
In Linux CAN is interfaced using SocketCAN. SocketCAN 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.
Since the driver is 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 250kbit/s) by
first writing value into bitrate parameter:
# ech o 2500 00 > / s ys /cl a ss /ne t/c an 0/c an_bi ttimi n g/ bi tr a te
www.maximatecc.com 13
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
Same applies to the other CAN interfaces by changing can0 to can1, can2 or can3.
Bus restart is then scheduled through kernel and implemented through can-core.
In automatic bus recovery, can-core detects state changes and re-initializes controller after the
specified time period.
Automatic bus recovery from bus off state is by default turned off. It can be turned on via sysfs
setting, where the wanted restart period in milliseconds is set into using the can_restart_ms
variable. For example, a 100ms restart period for can0 is set from command line like this:
s u do i fc onfi g ca n0 d own
s u do sh –c “ ec ho 100 > /s ys /cl a ss /ne t/c an0 /ca n_re s tar t_ ms ”
s u do i fc onfi g ca n0 u p
Same commands apply for can1 by replacing can0 appropriately. Period is possible to set as needed
from application perspective. Value zero turns automatic bus recovery off.
Warning: Enabling automatic bus recovery may disturb other nodes on bus, if CAN interface is
incorrectly initialized.
Warning: Enabling error interrupts and sending frames when module is not connected to active
bus may cause CAN acknowledge errors to overload CPU. User caution required. It is
recommended to avoid sending until one frame is received.
www.maximatecc.com 14
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
#i fn de f AF _ C AN
# d efi ne AF _ C AN P F _ C AN
# en di f
/ * ... */
/ * S o me w here i n y our ap p */
/ * C rea t e th e s ocke t */
i n t sk t = soc ke t ( P F _C AN , S O C K_R AW, C AN _R AW );
c on st i nt l oo p ba ck = 0 ;
/ * S en d a me s sa ge to the C AN b u s */
s truc t c an_fr a me fr ame ;
fr a me .c an_i d = 0 x123 ;
www.maximatecc.com 15
CCpilot XM and CrossCore XM Revision: 1.7
Programmers Guide Date: Jun 24, 13
/ * Re a d a me ss a ge b ac k fr o m the C AN b us */
i n t by t es_re a d = re ad ( s k t , &fr a me , si ze of (f ra me ) );
www.maximatecc.com 16
Technical support
Contact your reseller or supplier for help with possible problems with your XM device. In order to
get the best help, you should have access to your XM device and be prepared with the following
information before you contact support.
The part number and serial number of the XM device, which you find on the brand label
Prepare a system report on the XM device, from within CCsettings (if possible).
Trademark, etc.
© 2011 CrossControl AB
All trademarks sighted in this document are the property of their respective owners.
CCpilot is a trademark which is the property of CrossControl AB.
Intel is a registered trademark which is the property of Intel Corporation in the USA and/or other
countries. 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.
CrossControl AB 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.
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 XM device, refer to the copyright notices
documentation.
maximatecc AB
P.O. Box 83 • SE-822 22 Alfta • Sweden
Phone: +46 271 75 76 00• info@maximatecc • www.maximatecc.com