skype

Confidently. Accurately.

ADK

xOEMcore Advanced

Devkit

User Manual

ADK manual

Revision: 171024 2

Legal notices

Information furnished is believed to be accurate and reliable. However, Oxford

Technical Solutions Limited assumes no responsibility for the consequences of use of

such information nor for any infringement of patents or other rights of third parties

which may result from its use. No license is granted by implication or otherwise under

any patent or patent rights of Oxford Technical Solutions Limited. Specifications

mentioned in this publication are subject to change without notice and do not represent

a commitment on the part of Oxford Technical Solutions Limited. This publication

supersedes and replaces all information previously supplied. Oxford Technical

Solutions Limited products are not authorised for use as critical components in life

support devices or systems without express written approval of Oxford Technical

Solutions Limited.

All brand names are trademarks of their respective holders.

The software is provided by the contributors “as is” and any express or implied

warranties, including, but not limited to, the implied warranties of merchantability and

fitness for a particular purpose are disclaimed. In no event shall the contributors be

liable for any direct, indirect, incidental, special, exemplary, or consequential damages

(including, but not limited to, procurement of substitute goods or services; loss of use,

data, or profits; or business interruption) however caused and on any theory of liability,

whether in contract, strict liability, or tort (including negligence or otherwise) arising in

any way out of the use of this software, even if advised of the possibility of such

damage.

ADK manual

Revision: 171024 3

Copyright notice

© Copyright 2015, Oxford Technical Solutions.

Revision

Document revision: 170611 (see Revision history for detailed information).

Contact details

Oxford Technical Solutions Limited

77 Heyford Park

Upper Heyford

Oxfordshire

OX25 5HD

United Kingdom

Tel: +44 (0) 1869 238 015

Fax: +44 (0) 1869 238 016

Web: http://www.oxts.com

Email: support@oxts.com

Trademark information

microSDHC Logo is a trademark of SD-3C,

LLC.

ADK manual

Revision: 171024 4

Table of contents

Overview of materials 5

Getting started 6

Tutorials 10

Hardware overview 12

xDEV overview 16

ADK manual

Revision: 171024 5

Overview of materials

The following resources are provided with the ADK:

Document Description NDA

required

Quick start guide Basic guide to get a user up and running with the

ADK Yes

ADK Manual This document Yes

ADK Support page

The support site contains code examples and other useful ADK reference material

Yes

xOEMcore Manual

Outlines communication formats and states of the xOEMcore

No

xOEMcore datasheet

Specifications of the xOEMcore No

NAV Configuration

manual Description of the configuration files and commands Yes

Open source NCOM decoder

example repository

Repository with the latest version of the NCOM decoders written in C

No

NCOM description

manual Description of the NCOM format No

XCOM description

manual Description of the XCOM format No

CCOM description

manual Description of the CCOM format Yes

ADK manual

Revision: 171024 6

Getting started

Purpose

This is a step by step guide to getting up and running with the xOEMcore ADK

(Advanced DevKit). As part of this guide you will see how to:

• Install the required software ready for working with the ADK

• Setup the hardware ready for use

• Make basic changes, build and update the firmware on the ADK

• Run firmware on the ADK in debug mode

Install and setup software

To get up and running in the most efficient way OxTS recommend installing the latest

software versions to avoid compatibility issues. This guide describes the installation

procedure for Windows.

• Install CCS (Code Composer Studio) version 6.1.1.00022 from

http://processors.wiki.ti.com/index.php/Download_CCS. During the installation

make sure that ‘Sitara 32-bit ARM Processors’ is ticked on the ‘Processor Support’

page. CCS is TI’s (Texas Instruments) IDE (Integrated Development

Environment). N.B. You may need to create an account with TI in order to

download the software.

1) Install SYS/BIOS version 6.42.3.35 from

http://downloads.ti.com/dsps/dsps_public_sw/sdo_sb/targetcontent/bios/sysbios/,

this is TI’s real-time operating system which is primarily used in the ADK

firmware to manage interrupts and threads.

2) If you do not already have a terminal program on your PC, you should get one

now. PuTTY is a free terminal program you can get from http://www.putty.org/.

3) Unzip the xDEV firmware package from OxTS onto your local machine.

4) Run CCS and accept the prompt to install the SYS/BIOS.

5) In the ‘Project’ menu select Import ‘CCS Projects…’, browse to the location you

extracted the firmware package to and select xDEV (Figure 1).

ADK manual

Revision: 171024 7

Figure 1: Importing xDEV project into CCS.

6) Now the project is open, right click on it in the ‘Project Explorer’ pane to the left of

the window and select ‘Rebuild project’.

7) Check that the build finished without errors. After a successful build, an image file

called ‘xDEV_xxxxxx.img’ will have been created in the directory where you put

the xDEV firmware package. You now have everything required to start using the

ADK installed on your PC (Figure 2).

Figure 2: Rebuild the project and check that the build finished without errors. An image file called

'xDEV_xxxxxx.img' will have been created in the directory where you installed xDEV.

ADK manual

Revision: 171024 8

Setup xOEMcore ADK hardware

(1) Main ADK hardware

(2) GNNSS antennas and magnetic patch

(3) RT-XLAN, mounting pole and cable

(4) Ethernet cables

(5) Serial Cable

(6) USB Data cable for debugging

(7) Power brick and converter cables

(8) µSD card

Figure 3: Hardware setup.

1) Unpack all the supplied parts of the ADK.

2) Optional: Screw the RT-XLAN antenna into the metal base plate, and connect the

powered Ethernet cable into the RT-XLAN, the Ethernet switch and the RT-XLAN

power socket J21.

3) Use the 300mm Ethernet cable to connect the socket on the ADK to the Ethernet

switch and the 2m Ethernet cable to connect the Ethernet switch to your PC.

4) Use the USB cable to connect the debug port to your PC and if your PC has a serial

port, connect it to UART1 using the serial cable.

5) Connect the supplied antennas and if possible place these somewhere they will be

able to get a GNSS signal.

6) Use the supplied PSU and the correct power cable for your power outlets to power

the ADK via the DC socket.

ADK manual

Revision: 171024 9

7) The spare power output can be used to power other sensor inputs for example, a

wheel speed encoder (please consult the ADK hardware schematic for more

information).

8) Now the ADK is powered, your computer should detect and install the XDS100v2

Debug Probe which has two channels. One channel provides the debug probe

itself, which allows you to run code on the device from CCS so you can step

through bits of code and set break points. The other provides access to UART0

which is used as the debug output.

9) Look in your PC’s Device Manager under Ports for the ‘USB Serial Port’ to

discover which COM port number your PC has assigned to the device.

10) Open this COM port in your chosen terminal program at baud 115200, 8 data bits,

1 stop bit and no parity.

11) Now reset the ADK using the Soft Reset button (located in the middle of the board

next to the ‘Spare AM3358 Pins’, Figure 3). You should start to see some output

in your terminal program. There will be an initial burst of information from the

bootloader followed by a 15-20 second pause while SYS/BIOS boots. There will

then be another burst of information from the xDEV firmware initialising various

modules of the ADK. As part of this there will be a line telling you what ip address

the network interface has been setup with, you should make a note of this to

connect to the device over FTP and UDP. You can also use this debug interface

to send commands, for example if you enter: !reset the unit will reset itself (you

can also press the Soft Reset button at any time to reset the ADK).

12) You should also now be able to open NAVdisplay (part of the OxTS NAVsuite) to

view the unit’s output and be ready to begin changing the code.

NB: Feature codes are required for advanced functionality. The device can be

configured in a similar way to other OxTS products using NAVconfig or with a custom

config (mobile.cfg) file.

ADK manual

Revision: 171024 10

Tutorials

This section contains a basic hello world example to get you up and running.

Classic "Hello World!" example

The purpose of this example is to:

• Introduce the basic structure of main.cpp where xDEV is setup

• Understand the purpose of xBLINK and how to use the watchdog timer

• Make basic changes and update the firmware

1. Open CCS with the xDEV project loaded (see the getting started section of this manual)

2. In ‘Project Explorer’ pane on the left navigate to xDEV -> code -> main and open main.h.

3. At the top of main.h is the line: #define DEV_ID "161005ez" this is the development id for the xDEV firmware. The number is a reverse date format of the day the release was made so, for example, the above release was made on the 5th October 2016. Modify the DEV_ID to be today’s date.O

Open main.cpp and make sure that #define DISABLE_WATCHDOG_TIMER is commented out, thus enabling the watchdog timer. This is useful when debugging software to allow the unit to reset after an exception or long pause (currently set to 60 seconds) occurs as we will see below.

NOTE: To learn more about what is happening in main.cpp and a general overview of the xDEV firmware, please see this article here

4. Now in main.cpp in the idle_function() put the line while(1);. This will help to demonstrate how xBLINK works.

5. On the line before while(1); put oxts_stdout("\r\nHello World!\r\n", "");

6. oxts_stdout is a function to write to the debug port and can be used anywhere within task threads. This function requires at least two arguments and supports formatted inputs. When formatted inputs are not required, the second argument should be NULL. So for example, you could put oxts_stdout("\r\nHello World! %d %f\r\n", 5, 0.75); which would print “Hello World! 5 0.75”. To support arguments internally this function uses memory allocation so it cannot

ADK manual

Revision: 171024 11

be used in the context of hardware interrupts. For this purpose UARTPuts("\r\nHello World!\r\n", -1); can be used where the second argument is the length of the data or -1 for a NULL terminated string.

7. Right click on xDEV in the ‘Project Explorer’ pane and select ‘Rebuild Project’. This will do a clean build of the project and when it is completed in the folder where you put the xDEV firmware package an image file called ‘xDEV_xxxxxx.img’ will have been created. You can replace the xxxxxx in the file name or with whatever you like, typically the Dev_ID is put here.

8. FTP the image to the device. The IP address will be listed in the debug output by default, if you don't have it you get it from there, alternatively you can use NAVdisplay to see the IP address of the unit if you have a default configuration applied via NAVconfig.

9. Press the ‘Soft Reset’ button on the ADK board and the reset button of the xOEMcore. Both these buttons have to be pushed due to a handshaking process that takes place on the bootup of ether of the two modules.

10. When the xDEV application starts you can see one of the first things it prints is the Dev ID and this will now have been updated. You will also see that after initialisation, your message will begin printing to the terminal.

ADK manual

Revision: 171024 12

The unit will now appear to be working normally and will appear in NAVdisplay, however after a minute or two it will reset on its own. This is because the code that was added is halting the idle_function() so the watchdog timer is not being reset. The same thing would happen if the code was stuck in any other thread or had hit an exception.

11. If you review the bootloader output when it resets, you will see that the bootloader has detected the watchdog reset and now launches xBLINK instead of xDEV. NOTE: xBLINK is a cut down stable version of xDEV that is written to the flash outside of the file system so that the unit can be recovered if a faulty or corrupted xDEV firmware is loaded. In blink mode the IP address is 195.0.0.133, see this article for more details.

12. Remove the while(1) that you added, rebuild, reapply the image and power cycle the unit. It will now boot back as normal with your new Dev ID and not automatically reset.

Further Examples

For more examples that look into using basic features of the ADK you can visit the

support site here:

https://support.oxts.com/hc/en-us/sections/115001268269-ADK

You will need to have a login from OxTS for this, please contact projects@oxts.com

for more details).

ADK manual

Revision: 171024 13

Hardware overview

ADK board breakdown

ADK manual

Revision: 171024 14

Orientation

The default orientation of the IMU on the board is:

Buttons

There are 4 buttons on the xDEV, but in practice only two of them will be useful during

end user development:

xOEMcore reset button

ADK manual

Revision: 171024 15

(1) xOEMcore reset button. This will reset the core, so any xDEV outputs that rely on

it will cease to be output (e.g. NCOM)

xDEV buttons

(1) µSD boot: Holding this button during power on or hard reset will cause the

ADK to look for a bootloader on the µSD card instead of the eMMC, this

functionality is unlikely to be required unless xBLINK or the bootloader

require changes.

(2) Hard reset: If held for more than 8 seconds this button will cut the power to

anything powered from the SoM, things that will not be reset by this button

are:

• GNSS Cards

• xOEMcore

• RT-XLAN

(3) Soft reset: This button will reset the AM3358 chip and is used to reboot any

firmware running on the processor (exists on the “system on module”, or

SoM PCB)

ADK manual

Revision: 171024 16

xDEV overview

Purpose

This chapter gives a high level overview of the workings of the xDEV firmware. The

primary purpose of the firmware is to handle all of the different IO functionality

separately from the xOEMcore where the navigation algorithms are run.

This means the CPU on the xOEMcore can be devoted to running the navigation

algorithms and these will not be affected by sporadic CPU loads, for example heavy

Ethernet traffic. This also means that we are able to distribute the xDEV firmware for

system integrators that wish to develop their own applications with a xOEMcore

providing a navigation solution.

The ADK was designed to have ample spare CPU above and beyond its current needs,

it uses about 15% of its CPU when all of the features are enabled and being stressed,.

There are some cases where all free CPU will be diverted for cases like file transfer via

FTP, but for live running the CPU bandwidth exist. This is to allow scope for system

integrators to implement their own applications on the CPU as well as for OxTS to

implement more advanced functionality in our products in the future.

This chapter will provide a basic overview of the xDEV firmware and how to start

working with it.

Top level firmware overview

The main functionality of the xDEV firmware can be viewed simply as multiplexing

incoming data into CCOM packets and sending it to the xOEMcore and de-

multiplexing XCOM data from the xOEMcore and sending it to the appropriate

output/internal module.

Typically, all of the interfaces such as CAN, serial, UDP and wheelspeed are C++

classes that all have a common Device child class ensuring a common, thread safe

interface for all within the code. Some of these interfaces have restrictions, for

example wheelspeed and CAN have standardised packet types that must be passed in

and out and these are documented at the top of the devices source file.

xDEV does have some more intelligent functionality such as file logging, ftp and the

encoders/decoders. For example, SCOM which is sent from the xOEMcore over

XCOM is how the xOEMcore requests specific actions from the ADK such as what it

should be doing with the LEDs, for it to send the configuration files or for it to send

data to the GPS cards.

ADK manual

Revision: 171024 17

Below is a diagram that illustrates this (Figure 4).

Figure 4: Top level architecture overview

Threads and priorities

The xDEV firmware makes use of three types of threads with different priority levels

so that the prioritisation of low latency functionality can be guaranteed, these are:

• Hardware interrupts which happen as a result of an external event such as new

serial data or a PPS pulse. These tend to be very short and push/pull data from

the hardware into software buffers. These do not have access to a heap for

memory allocation etc. and run to completion. Hardware interrupts are the

highest priority threads and will always interrupt other thread types and each

interrupt also has a priority assigned to it. There is a total of 16 priority levels

with 1 being the highest for a standard hardware interrupt as 0 is reserved for

the Non-Maskable Interrupt.

• Task threads are where the firmware spends the majority of its time when it is

doing something. Each task has its own heap that is setup with a defined size

when the task is initialised and they tend not to run to completion but instead be

suspended until a semaphore is posted. The number of priorities for tasks is

configurable in SYS/BIOS in xDEV this is set at 16 and 15 is the highest, 0 is

reserved for the idle threads.

• Idle threads are a special type of task thread that run in a permanent loop in the

lowest priority context. These can be used to run non-time-critical periodic

tasks in the background.

ADK manual

Revision: 171024 18

Because nearly all threads can be interrupted mid-way through, it is important to make

sure data is shared between threads in a way that is safe from corruption or data loss.

There is a C++ class in the firmware that provides a thread safe cyclic buffer and these

are used a lot within the xDEV firmware to pass data between threads. In other areas

that cyclic buffers aren’t used, precautions should be taken to ensure changes to shared

variables are atomic or protected in some other way and shared resources such as the

TCP/IP library and the file system are only accessed from the same priority level.

The current priority levels for both hardware interrupts (HWI) and task threads can be

viewed and edited in main.h.

xDEV software package file structure

The zipped package that the xDEV code is distributed in contains three folders which

are:

• xDEV, which contains the CCS (Code Composer Studio) project files including

the configuration for the SYS/BIOS OS.

• utils, which contains the tools required for converting CCS output files to an

image file that can be loaded to the ADK and the xdc package for the ADK

board, this tells CCS how much memory etc. the PCB has.

• source, which contains all of the source files for the firmware.

Source files

The source files are further broken down into sub folders and this structure is mimicked

in CCS. The source file sub folders are:

• main, contains the higher level functionality including command parsing, ftp

etc.

• codecs, contains encoders and decoders.

• board, contains lower level functionality that interfaces to the hardware modules

such as setting up pin multiplexing and the Ethernet interface.

• devices, contains the devices classes for the UARTs, CAN, UDP, triggers etc.

• library, contains some common libraries written by OxTS such as the cyclic

buffer and useful mathematical declarations.

• com, this folder contains the files required for decoding the OxTS XCOM

stream.

• lwip-1.4.1, a third party TCP/IP library.

• fatfs, a third party library for the FAT file system which is not currently used in

xDEV. Instead a file system written by OxTS, which is more optimised for

writing large files and allows long file names, is used.

• TIStarterWare, the starter ware package from TI provides a number of drivers

and examples to help users get up and running with applications. In xDEV this

is mainly used for the interfaces to the uSD/eMMC, Ethernet and USB. Please

take care if you wish to update the StarterWare as significant changes have been

ADK manual

Revision: 171024 19

made to the source files, for example to add eMMC support and make the USB

work for more complex devices such as the FTDI chip used on the ADK.

• ogg, a third party library for decoding the ogg container format. This is the

container format XCOM is based on.

Notes on specific modules

XCOM decoding

XCOM, which is received from the xOEMcore over the xbns UART (xbns is the

firmware that runs on the xOEMcore) is decoded in two stages.

The first stage of decoding happens in a high priority task and here just the low latency

output data is dealt with. The ogg pages are pulled out one at a time and, depending on

the stream category, are either sent over the designated interface or passed through a

cyclic buffer to the second stage of decoding.

In the second stage the pages are decoded to pull complete valid packets out. This is

done in a lower priority task as it is more CPU intensive and not time critical. The full

page decoding ensures only complete uncorrupted packets are pulled out to ensure the

integrity of streams like the raw data.

SCOM decoding

SCOM is packaged inside XCOM, comes from the xOEMcore and is called within the

context of the XCOM slow task. It is the way the xOEMcore communicates

information and requests to xDEV. Examples of this include requesting the

configuration files to be sent at startup and updating the LED patterns.

CCOM encoding

CCOM is the format used to send data to the xOEMcore.

As CCOM data comes from multiple sources in many different threads the interface is

required to be thread safe, therefore all communications to the xOEMcore should go

through this module. Thread safety is achieved by each interface being allocated a

handle that reserves it a cyclic buffer internal to the module.

To setup a new interface to the CCOM module you must use hCcomChan

OpenCcomChannel() to initialise it. In most cases you will use bool CcomSend(hCcomChan ccom_chan_handle, uint16_t type, const void * data,

uint32_t len) to send data where the type should be one of the CCOM_PKT_ types

declared in library/EnumHardware.h.

ADK manual

Revision: 171024 20

Task, hardware interrupt and semaphore creation

Tasks, Hardware Interrupts and Semaphores should be created through SYS/BIOS.

OxTS have provided generic functions that can be used to do this. The declarations of

these can be seen in main/bios.h and examples of how to use them throughout the code

such as in main/main.cpp.

CPU usage measurement

CPU usage is tracked using the functionality in board/CpuUsage.cpp. There is a

function called from the idle loop which processes the information collated and reports

it periodically when enabled. The reporting period is set by a define at the top on

main/main.h and a value of 0 disables it. The information reported is shown below

(Figure 5):

Figure 5: CPU usage reporting

To add a module to the report you must first register it using CpuUsageTrackSetup()

which will return a handle for the tool. You can now use

CpuUsageThreadStart(uint32_t thread_handle) at the start of the thread or function

you wish to measure the CPU usage of and then CpuUsageThreadStop(uint32_t

thread_handle) at the end to monitor the CPU usage.

Several examples of how to use this can be found in the code for all the currently

monitored threads.

Status reporting

xDEV periodically populates a status structure and sends it over CCOM to the

xOEMcore. This gets logged in the rd file while some information is also decoded and

broadcast in real time. This information is useful for debugging issues and what is

included can be seen in main/status.h.

ADK manual

Revision: 171024 21

Options parsing

Options parsing is one of the first things that is done at the start of the initialisation task

in main/main.cpp. This is so that options set by the configuration files can be used

during the setup of the interfaces and configuration of the behaviour of different

modules.

The parsing code is in main/options.cpp and it goes through the mobile.cfg (the main

configuration file written by NAVconfig) one line at a time attempting to parse each

one. The parsing itself is done by a series of else if statements so to add an option

simply add to the end of this series of else ifs.

Command parsing

In xDEV, commands can come from UDP or any of the UARTs depending on the

configuration. The command parsing happens in main/commandrx.cpp and again this

is a series of else if statements only in this case the code is parsing for a space separated

string or ‘token’. This sets variables within the command structure which are then

acted on in main/user_commands.cpp.

Simulation

The xDEV firmware has the ability to replay raw data to the xOEMcore which can be

useful to simulate real world output from the xOEMcore on a bench. To activate this

functionality:

• The rd file you wish to replay should be named debug.rd and put on the unit.

• An empty file called mobile.dbg should also be created and put on the unit.

• All of the relevant configuration files for the data should be put on the unit.

• Reset both the ADK and xOEMcore (with a !reset command for example).

The unit should now boot and start to replay the data.

File formats

The following file formats are used in the ADK.

• µSD Card: FAT32

• eMMC: Custom file system

ADK manual

Revision: 171024 22

Bootloader and xBLINK

Both the bootloader and xBLINK are stored in raw flash outside of the file system

where they should be safe from corruption or accidental deletion.

xBLINK is a cut down stable release of xDEV whose function is to provide ftp

functionality following a watchdog reset or detection of a corrupt xDEV image. This is

to ensure the xDEV image can be updated in the event of firmware corruption, even on

a fully boxed unit.

The bootloader sets up the core parts of the hardware including PLL, DDR3 interface,

WDT and then it checks for and applies updates to various bits of firmware before

booting xDEV/xBLINK.

The graphic below demonstrates where on the eMMC the different firmware types

reside (Figure 6).

Figure 6: Firmware on the eMMC