Blue Technix Sentis-ToF-M100 User manual

Sentis-ToF-
M100
Getting Started
Programming
Version 1

© Bluetechnix 2013
Bluetechnix GmbH
Waidhausenstraße 3/19
A-1140 Vienna
AUSTRIA
[e-mail]
www.bluetechnix.com
Sentis-ToF-M100 –Getting Started Programming
Document No.: 900-308 / A
Publication date: July 18, 2013
Subject to change without notice. Errors excepted.
This document is protected by copyright. All rights reserved. No part of this document may be reproduced or
transmitted for any purpose in any form or by any means, electronically or mechanically, without expressly
written permission by Bluetechnix GmbH.
Windows is a registered trademark of Microsoft.

© Bluetechnix 2013
Table of Contents
1General Information ................................................................................................................ 4
1.1 Symbols Used .................................................................................................................. 4
2Introduction ............................................................................................................................ 5
2.1 Installing VDSP++............................................................................................................. 5
2.2 Plugging the JTAG device ................................................................................................. 5
2.3 Creating a Session ........................................................................................................... 6
3Programming with VDSP++ ..................................................................................................... 9
3.1 Flashing Applications with Bootloader ............................................................................... 9
3.2 Linker Description File (*.ldf).............................................................................................. 9
3.3 Programming with JTAG Device........................................................................................ 9
3.4 Flashing applications with JTAG-device............................................................................. 9
3.4.1 Using the VDSP++ Flash Programmer ........................................................................ 9
4Sentis-ToF-M100 VDSP++ Project......................................................................................... 11
4.1 Project Structure ............................................................................................................ 11
4.1.1 Dependencies ......................................................................................................... 11
4.1.2 Components and Data Flow ..................................................................................... 12
4.2 Features and Functions .................................................................................................. 12
4.2.1 Program Flow .......................................................................................................... 12
4.2.2 Buffer Management ................................................................................................. 16
4.2.3 Register Access ...................................................................................................... 18
4.3 Customizing streams ...................................................................................................... 19
4.4 Start Here: User Thread .................................................................................................. 19
4.5 Threading ...................................................................................................................... 21
4.6 Semaphore .................................................................................................................... 23
4.7 Mutex ............................................................................................................................ 24
5Recommended Documents ................................................................................................... 26
6Appendix.............................................................................................................................. 27
6.1 Supporta........................................................................................................................ 27
6.1.1 General Supp ort ...................................................................................................... 27
6.2 Software Packages ........................................................................................................ 27
6.3 Related Products ........................................................................................................... 27
7Document Revision History ................................................................................................... 28
8Index.................................................................................................................................... 29

© Bluetechnix 2013
© Bluetechnix GmbH 2013
All Rights Reserved.
The information herein is given to describe certain components and shall not be considered as a guarantee
of characteristics.
Terms of delivery and rights of technical change reserved.
We hereby disclaim any warranties, including but not limited to warranties of non-infringement, regarding
circuits, descriptions and charts stated herein.
Bluetechnix makes and you receive no warranties or conditions, express, implied, statutory or in any
communication with you. Bluetechnix specifically disclaims any implied warranty of merchantability or fitness
for a particular purpose.
Bluetechnix takes no liability for any damages and errors causing of the usage of this board. The user of this
board is responsible by himself for the functionality of his application. He is allowed to use the board only if
he has the qualification. More information is found in the General Terms and Conditions (AGB).
Information
For further information on technology, delivery terms and conditions and prices please contact Bluetechnix
(http://www.bluetechnix.com).
Warning
Due to technical requirements components may contain dangerous substances.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 4
1General Information
This guide applies to the Sentis-ToF-M100 camera platform from Bluetechnix GmbH. Follow this guide
chapter by chapter to set up and understand your product.
1.1 Symbols Used
This guide makes use of a few symbols and conventions:
Warning
Indicates a situation which, if not avoided, could result in minor or moderate injury and/or
property damage or damage to the device.
Caution
Indicates a situation which, if not avoided, may result in minor damage to the device, in
malfunction of the device or in data loss.
Note
Notes provide information on special issues related to the device or provide information that will
make operation of the device easier.
Procedures
A procedure always starts with a headline
1. The number indicates the step number of a certain procedure you are expected to
follow. Steps are numbered sequentially.
This sign indicates an expected result of your action.
References
This symbol indicates a cross reference to a different chapter of this manual or to an
external document.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 5
2Introduction
2.1 Installing VDSP++
Please download VDSP++ and update 10 from the Analog Devices website.
Get your copy of VDSP++ at
http://www.analog.com
Install both the program and the update. For further information refer to the documentation contained in the
VDSP++ download.
2.2 Plugging the JTAG device
In order to connect your computer with the Sentis over JTAG an adapter is needed.
Figure 1: JTAG adapter for Sentis-ToF-M100
Figure 2: Sentis-ToF-M100 with JTAG adapter

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 6
Caution
Please be alert and connect the JTAG adapter in the proper way, shown in Figure 2.
2.3 Creating a Session
In order to open a debug session to the Sentis-ToF-M100 follow following steps:
1. Connect the Sentis with power and JTAG.
2. Connect the JTAG to your pc.
3. In VDSP++ click on ‘Session’-> ‘New Session’The session wizard opens (Figure 3).
Figure 3: Session creation wizard
4. Select ADSP-BF561 and click ‘Next’

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 7
Figure 4: Session creation wizard
5. When asked for the connection type, select ‘Emulator’ (Figure 4) and click ‘Next’.
Figure 5: Session creation wizard
6. The platform used depends on your JTAG device. Please select the one you have purchased and
click ‘Finish’ (Figure 5) the session wizard closes and the device is already connected.
7. Now click on ‘Settings’ -> ‘Target Options’

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 8
Figure 6: Session target options
8. As target options we recommend configuring everything like in Figure 6.
9. For a better performance, click on ‘Settings’ -> ‘JTAG Frequency Selection’ and choose a higher
frequency.
10. Lastly click on ‘Settings’ -> ‘Session’ the session settings open up.
Figure 7: Session settings
11. Check the checkbox besides ‘Enable customizations’ and select the file in your support package:
‘Sentis-ToF-M100_development_package\prj\BLT\tof\firmware\sentis-tof-m100_bsp\vdsp\common\sentis-tof-
m100-custom.xml’ (Figure 7).
12. After the required reconnection you are finished and ready.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 9
3Programming with VDSP++
VDSP++ is a development and debug platform for the Blackfin processors provided by Analog Devices. The
following section describes how you can use VDSP++ to start developing and executing the first examples.
You can develop projects and download the executable via a JTAG. You have full control over the Blackfin
processor and full debug capabilities. Refer to the Compiler and Linker Manuals and the User Guides from
Analog Devices to learn more about developing projects.
3.1 Flashing Applications with Bootloader
The Sentis-ToF-M100 is delivered with a Bootloader which is able to flash a loader file onto the onboard SPI-
flash module. Please read the User Manual to understand the process of updating your device via its
configuration interface. Once a firmware is flashed it can be loaded and executed by restarting your Sentis.
3.2 Linker Description File (*.ldf)
The linker description file included in the Sentis-ToF-M100 development kit is tailored for this product and
should only be modified if necessary.
3.3 Programming with JTAG Device
If you have a JTAG device from Analog Devices you can just download the executable with the load
command of VDSP++. Refer to the VDSP++ documentation for further information.
3.4 Flashing applications with JTAG-device
Caution
If you flash your application via VDSP++ and JTAG, the Bootloader is overwritten.
To be able to flash an application first off all you have to create a loader file of your project. Refer to the
“VDSP++ Linker and Loader Manual” to see how to create loader files that can be booted by the Blackfin
processor.
If you have sections in the SDRAM that have to be initialized during the boot process you have to use an
initialisation file. This initialisation function sets up the SDRAM controller prior to boot the application. As the
SDRAM settings depend on the used type, it is important to use the initialisation file delivered by Bluetechnix.
The project in the support package should already include ‘ Sentis-ToF-M100_InitCode_V1.0.0.dxe’ as
initialisation file in the loader settings.
3.4.1 Using the VDSP++ Flash Programmer
Once connected to your Sentis via JTAG, open the Flash Programming Tool by selecting “ToolsFlash
Programmer” from the VDSP++ menu.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 10
Note
The Flash Programmer is only available if you have opened a valid session, i.e. you are not
connected to your Sentis.
As flash driver file use ‘Sentis-ToF-M100_FlashProgrammingToolDriver_V1.0.0.dxe’included in the support
package.
Press the “Load Driver” button. The section “Flash information” should be filled as shown in the figure below.
Figure 8: Device Programmer window when driver is loaded
Select the „Programming“ tab. Make sure to only erase affected sectors, that the file format is s et to binary,
select the loader file to flash and press the “Program” button. When done disconnect from target and restart
the Sentis by cycling its power on. The application should boot.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 11
4Sentis-ToF-M100 VDSP++ Project
In the support package you can find a complete and fully functional VDSP++ project. It includes libraries for
the basic functions of the camera, header files for accessing some of the functions and source code which
can be modified and extended to meet special needs.
4.1 Project Structure
4.1.1 Dependencies
When compiling the project, be aware of the dependencies and file types.
sentis-tof-m100_bf561_firmware.ldr sentis_tof_m100_bf561_firmware_CoreA.dxe
sentis_tof_m100_bf561_firmware_lwip_B.dxe
sentis_tof_m100_bf561_firmware_lib_B.dlb
Vdkoslib-bf561.dlb
Tcpip_wrapper-BF561.dlb
liblwIP-BF561.dlb
Sentis_tof_m100_bf561_firmware_lib_CoreA.dlb
Source code in project:
Sentis_tof_m100_bf561_firmware_CoreA
Source code in project:
sentis_tof_m100_bf561_firmware_lwip_B
Figure 9: Dependencies when compiling executables and the loader file.
Libraries are precompiled and have the file extension ‘dlb’. Executables (‘dxe’ files) are for downloading and
debugging via JTAG. Loader files (‘ldr’ files) can be programmed onto flash memory (either via JTAG or the
Bootloader).
The core A library includes all the data acquiring and data processing code, as well as the buffer and register
handling.
The core B library includes the code for the control interfaces and data interfaces, as well as BLACKSheep,
the Blackfin operating system (separately available with source code).
The other libraries in core B are Blackfin implementations for the lwIP –lightweight TCP/IP stack. UDP and
TCP communication is done via these libraries. Feel free to use them for your own purposes.
For the lwIP documentation, please visit
http://lwip.wikia.com/

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 12
4.1.2 Components and Data Flow
On both cores there are independently working modules that need synchronization and exchange of data.
Basically there is visual data from the camera and the register map data. Figure 10 shows the structure for a
better understanding.
Data
Acquiring
Data
Processing
Data
Filtering
User
Thread
Data Queue
Tcp
Streaming
Interface
Ssdi
Streaming
Interface
Tcp
Control
Interface
I2C
Control
Interface
Serial
Control
Interface
Register Map
Udp
Streaming
Interface
Core B
Core A
Control data
Camera data
Figure 10: Components and the flow of data between them.
4.2 Features and Functions
4.2.1 Program Flow
This section lists the relevant running threads and describes their tasks.
Core A does not run a kernel with threads, hence all asynchronous events are interrupt triggered. Core B has
a VDK kernel and implements the POSIX interface. Several threads are running at the same time but only the
source code of the ‘user thread’ is public.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 13
Core B main
start
Start thread:
Register check
Start thread:
Control server
Start thread:
Tcp stream server
Initialization
Start thread:
Udp streamer
Start thread:
Ssdi streamer
Finished
Start thread:
User thread
Register check
thread
start
A relevant
register changed? N
Y
Notify corresponding
thread / component
about change
Core A main
start
Integration
(image capturing)
Data
processing &
filtering
Data
enqueuing
in queue
Register map
synchronization
Initialization
Figure 11: Flowchart of core A, the boot thread of core B and its register polling thread.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 14
Control server
thread
start
Abort?
Finished
Open socket and
listen
Change port?
OR
Abort?
N
Accept a
connection
Maximum
number reached?
N
Start thread:
Control worker
Y
Y
Y
Control worker
thread
start
Connection
available?
AND
Not abort?
NFinished
Y
Wait for preamble
Receive command
Take action
Send response
Figure 12: TCP control interface; one thread to accept connection and one or more worker threads to handle requests.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 15
Tcp stream
server thread
start
Abort?
Finished
Open socket and
listen
Change port?
OR
Abort?
N
Accept a
connection
Maximum
number reached?
N
Start thread:
Tcp streamer
Y
Y
Y
Tcp streamer
thread
start
Connection
available?
AND
Not abort?
NFinished
Y
Request data from
queue
Got data? NSend dummy
header? YSend a dummy header
Y
Send frame
Call
customizeTcpBuffer
N
Mark processed
previously
requested data
Figure 13: TCP data interface; one thread to accept connections and one or more to transmit the data.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 16
Udp streamer
thread
start
Streaming
enabled?
N
Y
Request data from
queue
Got data?
N
Y
Send frame
Call
customizeUdpBuffer
Adjust port if
requested
Ssdi streamer
thread
start
Ssdi ready to
transmit?
N
Y
Request data from
queue
Got data?
N
Y
Send frame
Call
customizeSsdiBuffer
Mark processed
previously
requested data
Mark processed
previously
requested data
Figure 14: Two threads collecting camera data and streaming it over UDP and Fast SPI, respectively.
4.2.2 Buffer Management
Core A manages the buffers with the processed camera data. Figure 15 shows the basic structure: Core A
generates data at its own predefined pace. This data is then simultaneously inserted in each client’s queue
(see Figure 15). If there is no free slot in a client’s queue, nothing is inserted. By default all four queues have
a length of three. Even if all three slots of all four clients are filled up, core A continues to generate data.

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 17
Data acquisition
Data processing
Data filtering
Data ready
Tcp queue
Udp queue
Ssdi queue
User queue
Tcp streamer
thread
Udp streamer
thread
Ssdi streamer
thread
User thread
Core A Shared memory Core B
Figure 15: Buffer management: Organization of camera data in queues
A client can the access the data via following functions:
This function is for retrieving the data:
Function Name
Parameters
Description
BMTdequeue
T_BMT_CLIENT_HANDLE pa_tHndl
The handle of the buffer manager
T_BMT_BUFFER_DESC
**pa_ptBuffer
Result: The data buffer (is succeded)
Returns T_ERROR_CODE
Error code (ERR_TCI_INVALID_HANDLE,
ERR_BMT_BUFFER_EMPTY) or ERR_NONE
This function removes the last item in the queue:
Function Name
Parameters
Description
BMTdequeueProcessed
T_BMT_CLIENT_HANDLE
pa_tHndl
The handle of the buffer manager
Returns T_ERROR_CODE
Error code (ERR_TCI_INVALID_HANDLE,
ERR_BMT_BUFFER_EMPTY) or ERR_NONE
This function removes all items in the queue:
Function Name
Parameters
Description
BMTflushClient
T_BMT_CLIENT_HANDLE
pa_tHndl
The handle of the buffer manager
Returns T_ERROR_CODE
Error code (ERR_TCI_INVALID_HANDLE) or
ERR_NONE

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 18
Interactions and the manager’s behavior is explained more closely in Figure 16. The following five steps
explain what happens in Figure 16. It is an example of a slow client with a lower frame rate than core A.
1
The program just started and no data is in the buffer queue.
2
After three cycles core A has generated enough data to fill the queue and nothing changes
anymore.
3
The client called BMTdequeue and is processing the camera data of frame 0. The data, however
stays in the shared memory.
4
The client called BMTdequeueProcessed. The buffer manager discards frame 0 and inserts one
new frame into the queue. The client can now continue with frame 1. Frames 3 through 5 are lost for
this client and frame 1 and 2 must be dequeued in order to get to frame 6.
5
In that slow case the client decided to call BMTflushClient. This way frame 6 is lost, too. Shortly, the
buffer is filled with fresh data again.
Program start
Frame 2 Frame 1 Frame 0
After some time
Frame 2 Frame 1 Frame 0
BMTdequeue
Frame 6 Frame 2 Frame 1
BMTdequeueProcessed
Frame 9 Frame 8 Frame 7
BMTflushClient
1
2
3
4
5
Figure 16: Illustration of buffer operations
4.2.3 Register Access
A register can be written using the register-write function:
Function Name
Parameters
Description
TCIregisterWrite
T_TCI_HANDLE pa_tHndl
The handle of the service (use 0 to imply the default
handle)
unsigned short pa_usRegister
Register address to write to
void *pa_pBuffer
Value(s) to write into register

Getting Started Programming - Sentis-ToF-M100 Last change: 18 July 2013
Version 1
© Bluetechnix 2013 Page | 19
unsigned short pa_usLength
Length of pa_pBuffer. Must be a multiple of 2 since a
register is 2 bytes wide
Returns T_ERROR_CODE
Error code (ERR_TCI_INVALID_HANDLE,
ERR_TCI_ILLEGAL_REG_WRITE) or ERR_NONE
A register can be read using the register-read function:
Function Name
Parameters
Description
TCIregisterRead
T_TCI_HANDLE pa_tHndl
The handle of the service (use 0 to imply the default
handle)
unsigned short pa_usRegister
Register address to read from
void *pa_pBuffer
Result: Value(s) read from register
unsigned short *pa_pusLength
Length of pa_pBuffer i.e. the number of bytes to
read. Must be a multiple of 2 since a register is 2
bytes wide. Result: Bytes actually read
Returns T_ERROR_CODE
Error code (ERR_TCI_INVALID_HANDLE,
ERR_TCI_REGISTER_END_REACHED) or ERR_NONE
4.3 Customizing streams
The included source code can be modified to one’s own needs. To start from scratch it is recommended to
look at the example cod e in ‘user_buffer_customizing.c’. It is well documented and simply modifies the
distance and amplitude data before being streamed. It can be seen in the flowcharts of the threads ‘TCP
streamer thread’, ‘UDP streamer thread’ and Ssdi streamer thread’, that before transmitting any camera data
over the wire, a function ‘customize***Buffer‘ is called. So, in the functions ‘customizeTcpBuffer‘,
‘customizeUdpBuffer‘ and ‘customizeSsdiBuffer‘ the camera data can be altered and it is then streamed
normally. It is important to consider, though:
As stated in the user manual, a header precedes the camera data buffer.
The data buffer is locked until it is transmitted. The frame rate for the interface may drop as a
consequence of heavy processing.
4.4 Start Here: User Thread
Secondly, the file ‘user_thread.c’(visible in Figure 17) contains a few examples on how to gather camera
data and access some registers. In order to understand what the example is d oing, please refer to Figure 18
and/or the comments in the code.