ADK - OxTS · ADK manual Revision: 171024 6 Getting started Purpose This is a step by step guide to...
Transcript of ADK - OxTS · ADK manual Revision: 171024 6 Getting started Purpose This is a step by step guide to...
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: [email protected]
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 [email protected]
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