K-Team Khepera IV Stargazer User manual

Khepera IV Stargazer
User manual
Version 1.1
February 2017

Documentation Author
Julien Tharin and Timothée Carron
K-Team S.A.
Z.I. Plans-Praz 28
133 Vallorbe
Switzerland
Email: [email protected]
URL: www.k-team.com
Documentation version
Version Date Author Description
1.0 12.09.2014 J. Tharin First draft
1.1 28.02.201 F.Lambercy
Remove remark about Gripper
Trademark Acknowledgements:
IBM PC : International Business Machines Corp.
Macintosh : Apple Corp.
S N Sparc-Station : SUN Microsystems Corp.
LabVIEW : National Instruments Corp.
Matlab : MathWorks Corp.
Webots : Cyberbotics Ltd
Logitech : Logitech Int. SA
Gumstix : Gumstix Inc.
Khepera : K-Team SA
Stargazer : Hagisonic co. Ltd
LEGAL NOTICE:
•The contents of this manual are subject to change without notice
•All efforts have been made to ensure the accuracy of the content of
this manual. However, should any error be detected, please inform K-
Team.
•The above notwithstanding, K-Team can assume no responsibility for
any error in this manual.

TABLE OF CONTENTS
1. INTROD CTION ............................................................... 1
1.1 H OW TO USE THIS HANDBOOK ........................................................ 1
1.2 S AFETY PRECAUTIONS ................................................................. 2
1.3 R ECYCLING .............................................................................. 2
1.4 S PECIFICATIONS ........................................................................ 3
2. NPACKING AND INSPECTION ......................................... 4
2.1 P ACKAGE C ONTENTS ................................................................... 4
2.2 I NSPECTION ............................................................................. 4
3. DESCRIPTION .................................................................. 5
3.1 O VERVIEW .............................................................................. 5
3.2 KSG H ARDWARE ....................................................................... 6
3.3 KSG S OFTWARE ....................................................................... 6
4. SAGE .............................................................................. 7
4.1 R EQUIRED HARDWARE / SOFTWARE ..................................................
4.1.1 R EQUIRED HARDWARE ............................................................
4.1.2 R EQUIRED SOFTWARE ............................................................
4.2 A SSEMBLY ............................................................................... 8
4.2.1 KSG ON THE ROBOT .............................................................. 8
4.2.2 L ANDMARKS SETTING ............................................................. 9
4.3 P OWER - UP AND TEST ................................................................ 10
4.3.1 T EST ............................................................................. 10
4.4 P ROGRAMMING THE KSG ........................................................... 12
4.4.1 I NSTALLATION OF THE LATEST LIBKHEPERA AND CONFIG . FILE ............ 12
4.4.2 U SING THE KSG WITH KGAZER _ TEST SOFTWARE .......................... 14
4.4.3 C OMPILING YOUR OWN PROGRAM USING THE LIBKHEPERA ................. 15
4.4.4 S OFTWARE EXAMPLE ............................................................ 22
5. WARRANTY .....................................................................24

1
1. INTROD CTION
Thank you for buying the Khepera IV Stargazer (abbreviated KSG in
this document)!
With this module, you will be able to have global position and bearing
of your Khepera IV robot.
1.1 How to use this handbook
This handbook introduces the KSG and its various operating modes.
For a quick start, jump to chapter 4 ”Usage”.
If this handbook does not answer one of the problems you wish to
solve, please consult the K-Team web site (http://www.k-team.com) and
especially the Forum and the FAQs.
•npacking and Inspection : KSG package description
•Description : KSG description
•sage : KSG usage descriptions
•Warranty : Legal notice.

2
1.2 Safety precautions
Here are some recommendations on how to correctly use the KSG:
•Keep the board away from wet area. Contact with water could
cause malfunction and/or breakdown.
•Store your board in a stable position. This will avoid the risks of
falling, which could break it or cause damage to a person.
•Do not plug any connectors while the board is powered
on. To avoid any damage, make all connections when the board
power is off.
•Never leave the KSG powered when it is unused. When you
have finished working with KSG, turn it off. It will save the battery
life.
1.3 Recycling
Think about the end of life of your product! Parts of the board can be
recycled and it is important to do so. By recycling you can help to create
a cleaner and safer environment for generations to come. For those
reasons please take care to the recycling of your product at the end of its
life cycle, for instance sending back the product to the manufacturer or to
your local dealer.
Thanks for your contribution to a cleaner environment!

3
1.4 Specifications
The main specifications of the KSG board are listed below:
Range max :2.5-3 m of diameter with 1 landmarks (for ceiling
height of 2.4 m*
1
)
Accuracy : 3.5 cm / 3 degrees *
2
Measurement time : 10 times /sec
Autonomy : 2h30 ; Li-Pol battery
Dimensions : 85 width x 80 depth*
3
x 56 height*
4
[mm]
Mass : 11 g
Compatibility : Khepera IV extensions (KB-250 specifications)
*1 : ceiling height can be from 1.1 to 6.0 m but with different landmarks; range may vary
*2 : with a homogenously flat floor
*3 : with cables
*4 : without lower ERNI connectors (as plugged)

4
2. NPACKING AND INSPECTION
2.1 Package Contents
Figure 1: View of the StarGazer module
Your package should contain the following items:
1. KSG board
2. DVD with software and this User Manual*
* Updates can be found at http://www.k-team.com/
2.2 Inspection
First, check that you have a complete package. You should find:
•the KSG module
•CD with
oThis user manual
oThe Libkhepera library software
Then, check that the wires connecting the Stargazer to the battery module
are connected and not in bad shape.

5
3. Description
3.1 Overview
An overview of the KSG hardware is depicted in the Figure 3.1. The
locations of various key elements are indicated for later references.
Figure 3-1: KSG overview – top view
Figure 2: KSG overview
battery
Stargazer module
battery module
y
x
α
axis of rotation of the robot
connector to robot
BACK
FRONT

6
3.2 KSG Hardware
The KSG module is composed of a Stargazer position module from
Hagisonic co. Ltd and the K4LFSG battery module. There are also landmarks
to put on the ceiling.
The Stargazer module has IR LEDs for lighting landmarks and a camera
for capturing the image, which is processed by onboard electronics. It
computes position and bearing related to landmarks stuck on the ceiling.
The K4LFSG battery module is composed of a battery and electronics for
managing its charge and connections to the robot. The module is ON at
startup, and OFF when the Khepera IV is OFF.
3.3 KSG Software
The position and bearing are computed internally in the Stargazer and they
are communicated through the serial port (/dev/ttyS2) to the robot using
several commands.
For the ease of use, functions were developed and included in the
Libkhepera library. A test program named kgazer_test is also provided. It
initializes the module and displays the position in an ASCII x-y graph. The
robot can be controlled with the keyboard arrows.
The parameters of the KSG are saved into the KSG and remain even after
power OFF/ON. The exception is the calibration parameter.

4. sage
4.1 Required hardware / software
The required hardware and software to use the board and develop
programs are described below.
4.1.1 Required hardware
•Computer with Bluetooth or Wi-Fi access
•KSG module
•Khepera IV robot
4.1.2 Required software
•Khepera IV light toolchain installed (see Khepera IV User
Manual)
•Libkhepera library
Remarks:
You may find updated version of these software at:
http://ftp.k-team.com/

8
4.2 Assembly
4.2.1 KSG on the robot
The assembly of the board with the robot is depicted in Figure 3 Figure .
•The assembly and disassembly must be done while the robot is
switched OFF; also the robot and KSG must not be charging.
•Insert the KSG module on top of Khepera IV (or Khepera IV
extensions stack).
•Pay attention to the orientation of the module (front/back).
Figure 3: Assembl

9
4.2.2 Landmarks setting
The landmarks should be placed at maximum of x m interval on the
ceiling for the height of about h m in order that any dead zone may not
occur (figure 4b), with a relation of:
Equation 4.1: x = 0.8 ⋅ h
Example: h=2.5 m => x = max 2m
a) with dead zone
(b) without dead zone
Figure 4: The placement of landmarks
You don’t need to install all the 4 landmarks if your area is smaller. And
they don’t need to be placed in a square shape because during the map
building process, the relative position of the landmarks are computed.
The default landmarks delivered with the KSG are of type HLD1S. They
can be used with a height range of 1.1-2.9 m. See chapter 3 A and appendix
C of “Stargazer User’s Guide” for more information about the landmark:
http://ftp.k-team.com/KheperaIII/KSG/StarGazer_Guide_02.0904.16(English).pdf
x
x

10
4.3 Power-up and test
The KSG module is switched ON when the Khepera IV robot is switched
ON. It starts autonomously sending position through the serial port, if it sees
a landmark.
4.3.1 Test
You can also launch the kgazer_test program (see chapter 4.4.2) or
test with the instructions below:
-put the robot so that it can see landmarks (for placing landmarks,
see chapter 4.2.2).
-after the robot is switched ON, you should see some red LED ON
inside the Stargazer, from its top window.
-change ssh escape character on your PC . If it is ~, it will conflict
only with the Stargazer command for the test below, not for the
normal use of that manual for Linux, run:
sudo sh -c ‘echo “EscapeChar ^” >>/etc/ssh/ssh_config’
-open a ssh connections terminal to the robot (see Khepera IV User
Manual).
-run the following command to set the serial port the terminal:
stty -F /dev/ttyS2 115200 -parenb cs8 clocal -crtscts
cat /dev/ttyS2
=> it should display lines like below without interruption if the robot
is under landmarks on the first terminal:
~^I560 +79.05 -10.94 -106.12 190.00`
~^I560 +79.05 -10.93 -106.11 190.00`
~^I560 +78.39 -10.97 -106.15 189.16`
~^I560 +79.05 -10.94 -106.15 190.00`
~^I560 +79.05 -10.94 -106.13 190.00`
~^I560 +79.05 -10.93 -106.12 190.00`
~^I560 +79.05 -10.93 -106.11 189.82`
The data is respectively landmark ID (560), angle (~ 9 deg), x
position (~-10cm), y position (~-106cm), height to landmark
(~190cm).
To stop, push keys CTRL and C together at the first terminal.

11
To test sending commands, please use minicom on your Khepera IV:
-launch minicom with the command: minicom -o
-set its parameters with the sub-menu “Serial port” setup of the
menu [configuration]
(Figure 4.4) (keys “Ctrl-A + O”) as described in Figure 4.3.
Figure 5: Minicom serial parameters
-Save the settings with the sub-menu “Save setup as dfl” (Figure
Figure 6: Minicom configuration menu
- push CTRL a and e keys to have local echo.
- write the following command to stop receiving position: ~#CalcStop`
=> return should be: ~!CalcStop`
Multiple stops may be needed. The command ~#CalcStart`
starts again the position computation.
-write the following command to get Stargazer firmware version:
~#Version`
=> return should be: ~!Version`~$Version 2.1101.18`
See Stargazer User’s Guide for more information on chapter 6 for
commands and on chapter for landmarks:
http://ftp.k-team.com/KheperaIII/KSG/StarGazer_Guide_02.0904.16(English).pdf
+-------------------------------------------------------------+
| A - Serial Device : /dev/ttyS2 |
| B - Lockfile Location : /var/lock |
| C - Callin Program : |
| D - Callout Program : |
| E - Bps/Par/Bits : 115200 8N1 |
| F - Hardware Flow Control : No |
| G - Software Flow Control : No |
| |
| Change which setting? |
+-------------------------------------------------------------+
+-----[configuration]------+
| Filenames and paths |
| File transfer protocols |
| Serial port setup |
| Modem and dialing |
| Screen and keyboard |
| Save setup as dfl |
| Save setup as.. |
| Exit |
+--------------------------+

12
4.4 Programming the KSG
The KSG is an extension that can be used only with the Khepera IV.
That means that the Khepera IV controls all the functions of the KSG. As
all the Khepera IV extensions, a library including all the available
functions is provided with the Libkhepera version 1.0 or greater. If you
already have a Libkhepera installed in your computer but with an older
version, you can download the latest version on our ftp:
http://ftp.k-team.com/
If your Khepera IV has already the latest Libkhepera installed, jump
to section 4.4.2.
You can check if the latest version is installed:
•Log on the Khepera IV (via ssh, Bluetooth or serial port)
•You can check if you have the 1.0 version in listing the
present files:
ls –s /usr/lib/libkhepera*
This should give this, where the number after .so. is the
current version:
0 /usr/lib/libkhepera.so 315
/usr/lib/libkhepera.so.1.0
4.4.1 Installation of the latest libkhepera and config. file
To use the KSG with the Khepera IV, it’s necessary to install the
libkhepera version 1.0 or greater.
Normally, if you have received the Khepera IV at the same time than
the KSG, the Khepera IV is ready to be used with the KSG; in this case,
you can jump to section 4.4.2. Otherwise, if you have bought the KSG
separately, you will need to execute the step described below:
•Log on the Khepera IV (via ssh, Bluetooth or serial port)
You have different ways to update the library:
Autonomously with the package:
•Upload the package file libkhepera-1.0-r0_armv5te.ipk by ssh,
Bluetooth or Serial.
•Remove the old one with the command: ipkg remove libkhepera
•Install the new one with the command:
ipkg install libkhepera-1.0-r0_armv5te.ipk

13
By hand:
•Remove the old libkhepera: rm /usr/lib/libkhepera*
•Copy or send the libkhepera.so.1.0 file (located in the build-
khepera-2.6/lib/ directory of the libkhepera source files) to the
directory /usr/lib.
•Link the libkhepera file as libkhepera.so:
ln -s /usr/lib/libkhepera.so.1.0 /usr/lib/libkhepera.so

14
4.4.2 sing the KSG with kgazer_test software
The kgazer_test is a test and example program given also in source
code in directory src/tests/ of the Libkhepera library.
After copying this program to the Khepera IV and launching it with the
command ./kgazer_test , it will initialize the Stargazer, display the version
of its internal software, ask if you would like to change its parameters
(number, type and reference of landmark) . Then, it will rotate to do a
calibration due to the fact that the ceiling may not be exactly parallel to the
KSG module. Then it displays an ASCII interface (figure 4.5).
You can move the robot with the keyboard arrows keys. The robot is
represented by the character A,<,> or V depending of its orientation. Other
keys are defined below:
+/- : zoom in / out
Page Up / Down : speed up/down the robot
c : redo position calibration
g : goto xy (choose goal, then go to goal using a very
basic algorithm)
m : if several landmarks, starts map building
k : use / don’t use correction from calibration
p : change stargazer parameters
s : start/stop saving data to file data_corr.csv
t : display / undisplay old robot position
q : exit program
Figure 7: kgazer_test ASCII interface
[cm,deg] x= -2.6 y= +4.4 angle= +18.2 height= +200.4 idnum= 560 | zoom: 5.0x speed[mm/s]: 23.4 ( 5120) mode: I
KEYS: (q):quit (arrows)=move (+/-)=zoom (PG UP/DOWN)=speed (s)=save(OFF) (k)=apply corr(OFF) (t)=trace (m)=build map(OFF) (p)=param
(c)=calib (g)=goto(OFF)
..
..... ....
... ..
.A. .
... ..
..
.. ..
. . -
. .
. 0,0 .
.. .
.. .
. ...
... ...
... .......
scale: x 20cm = > < y 20cm = -

15
4.4.3 Compiling your own program using the libkhepera
To make your own software to control the KSG, you need to install
the development tools for the Khepera IV on your computer (with Linux
OS). If it is not already done, please look at the Khepera IV User Manual
to know how to install it.
Once done, you can start writing your program. The best solution is
to copy the kgazer_small_ex.c source code (see chapter 4.4.4) and
modify it. The source code kgazer_test.c is a more complete example.
In any case, keep your program in the src/tests/ directory, and modify
the Makefile to compile your new software: add your new program
filename in line 35 at the variable TARGETS of the file in the
src/test/Makefile or start with the template program in the template
directory.
As for all the Khepera IV extensions, you need to initialize the library
before using the functions described below.
The Libkhepera provides high-level functions which include all the
available capabilities of the KSG. Look at the following sections to view
the different exported constants variables and functions provided by the
Libkhepera for that KSG extension.
4.4.3.1 Constants
Constants defined in the header file are described below:
NB_MARK_TYPES
Number of types of different landmarks:
#define NB_MARK_TYPES 6
HLD1S
Index of landmark type HLD1S:
#define HLD1S 0
HLD1L
Index of landmark type HLD1L:
#define HLD1L 1
HLD2S
Index of landmark type HLD2S:
#define HLD2S 2

16
HLD2L
Index of landmark type HLD2L:
#define HLD2L 3
HLD3S
Index of landmark type HLD3S:
#define HLD3S 4
HLD3L
Index of landmark type HLD3L:
#define HLD3L 5
NB_MARK_MODES
Number of landmark modes:
#define NB_MARK_MODES 2
MARK_ALONE
Alone landmark mode index:
#define MARK_ALONE 0
MARK_MAP
Map landmark mode index:
#define MARK_MAP 1
NB_HEIGHT_FIX_MODES
Number of landmark height modes:
#define NB_HEIGHT_FIX_MODES 2
HEIGHT_FIX_NO
Index of the non-fix height:
#define HEIGHT_FIX_NO 0
HEIGHT_FIX_YES
Index of the fixed height:
#define HEIGHT_FIX_YES 1
ANGLE_CORRECTION
Angle correction for calibration:
#define ANGLE_CORRECTION 137.0
CALIB_STDEV_MAX
Maximum standard deviation before calibration error [cm]:
#define CALIB_STDEV_MAX 3.0