K-Team KoreUSBCam User manual

Kor
KorKor
Kore
ee
eUS
USUS
USBCam
BCamBCam
BCam
User manual
Version 1.2
April 2009

KoreUSBCam User Manual rev 1.2 2

KoreUSBCam User Manual rev 1.2 3
Documentation Author
Julien Tharin
K-Team S.A.
Rue Galilee 9, Y-Parc
1400 Yverdon-les-Bains
Switzerland
Email: [email protected]
Url: www.k-team.com
Documentation version
Version Date Author Description
1.0 02.12.2008 J. Tharin First draft
1.1 05.03.2009 J. Tharin Added support of new camera QuickCam e2500,
corrected wcggrabber command
1.2 08.04.2009 J. Tharin Added description of new camera
Trademark Acknowledgements:
IBM PC: International Business Machines Corp.
Macintosh: Apple Corp.
SUN Sparc-Station: SUN Microsystems Corp.
LabVIEW: National Instruments Corp.
Matlab: MathWorks Corp.
Webots: Cyberbotics
Khepera: K-Team and LAMI
Logitech: Logitech Int. SA
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.

KoreUSBCam User Manual rev 1.2 4
TABLE OF CONTENTS
1 INTRODUCTION.................................................................................................5
1.1. H OW TO USE THIS HANDBOOK .....................................................................................5
1.2. S AFETY PRECAUTIONS .................................................................................................6
1.3. R ECYCLING .................................................................................................................6
2 UNPACKING AND INSPECTION.....................................................................7
2.1. P ACKAGE C ONTENTS ...................................................................................................7
2.2. S PECIFICATIONS ..........................................................................................................7
2.3. R EQUIRED HARDWARE AND SOFTWARE .......................................................................8
A ) R EQUIRED HARDWARE :...............................................................................................8
B ) R EQUIRED SOFTWARE : ................................................................................................8
3 USAGE .................................................................................................................9
3.1. A SSEMBLY ..................................................................................................................9
3.2. P OWER - UP .................................................................................................................10
3.3. I MAGES ACQUISITION ................................................................................................10
3.4. V IDEO STREAMING ....................................................................................................10
A ) KTGRAB .....................................................................................................................10
B ) C AMSOURCE / W EB C AM A PPLET ...............................................................................11
3.5. P ROGRAMMING .........................................................................................................12
4 ANNEXES............................................................................................................14
4.1. U SING A W IRELESS COMPACT FLASH CARD ...............................................................14
4.2. C ONNECTING TO THE K OREBOT WITH NETWORK OVER USB CABLE ...........................16
4.3. T RANSFERRING FILES USING SCP ( SSH )......................................................................16
5 WARRANTY.......................................................................................................17

KoreUSBCam User Manual rev 1.2 5
1 INTRODUCTION
Thank you for buying the KoreUSBCam module. With this module, you will be able to
grab pictures and stream/process video images.
1.1. How to use this handbook
This handbook introduces the KoreUSBCam and its various operating modes. For a quick
start, jump to chapter 3: Usage.
If this handbook does not answer one of the problems you are confronted with, please
consult the K-Team web site (www.k-team.com) and, especially the Forum and the FAQs.
•Unpacking and Inspection: KoreUSBCam package description and first start-up
•Usage: KoreUSBCam usage descriptions.
•Annexes: Detailed descriptions of several helpful tools and commands
are explained.

KoreUSBCam User Manual rev 1.2 6
1.2. Safety precautions
Here are some recommendations on how to correctly use the KoreUSBCam:
•Keep the module away from wet area. Contact with water could cause malfunction
and/or breakdown.
•Store your module in a stable position. This will avoid the risks of falls, which
could break it or cause damage to a person.
•Do not attach any connectors while the module is powered on. To avoid any
damage, make all connections when the module power is off.
•Never leave the KoreUSBCam powered when it is unused. When you have
finished working with KoreUSBCam, turn it off. It will save the battery life.
1.3. Recycling
Think about the end of life of your product! Parts of the module 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!

KoreUSBCam User Manual rev 1.2 7
2 UNPACKING AND INSPECTION
2.1. Package Contents
1. KoreUSBCam module
2. User manual
Figure 2.1: Contents of the KoreUSBCam Pack
Your package should contain the following items:
1. KoreUSBCam module
2. this present document
2.2. Specifications
The principal specifications of the KoreUSBCam module are listed below:
• images capture : 160 x 120 up to 640 x 480 pixels
• video acquisition : 160 x 120 up to 640 x 480 pixels, 5-15 fps,
depending of video size and compression
• module size : 85 x 72 x 76 (width x length x height mm)
• module mass : 80 g.
• connector : 2 female ERNI 50 pins connectors, compatible with
other K-Team Kore modules
•power : 5V, from ERNI connector
•video/image cable : USB2, from ERNI connector
•software drivers : gspca, videodev, v4l (video for linux) modules
•image software : wcggrabber, vgrabber
•video software : ktgrab, camsource

KoreUSBCam User Manual rev 1.2 8
2.3. Required hardware and software
The required hardware and software to use the module is described below.
a) Required hardware:
To use the KoreUSBCam module, you must have any of these components:
• KorebotLE with software kernel 2.6
*
• KheperaIII + KorebotLE with software kernel 2.6
*
* You can check the Kernel version with the command “uname –r ” . The kernel and
toolchain 2.6 for the Korebot is available at:
http://ftp.k-team.com/korebot/toolchain-2.6-betaV0.1/
b) Required software:
On the KoreBotLE, the driver for the camera is installed by default when delivered
with kernel 2.6. It is located on your KoreBotLE at the following path:
/lib/modules/YOUR_KERNEL_VERSION/kernel/drivers/usb/media/gspca.ko
where YOUR_KERNEL_VERSION may be 2.6.23-kb1, 2.6.25-7-kb1 or above.
Depending on the KoreUSBCam module version you may have to update the driver:
•KoreUSBCam board with the QuickCam Chat camera (White/Blue colour):
→The driver is already included on the KorebotLE.
•KoreUSBCam board with the new camera QuickCam E2500 camera (Black/Grey
colour):
→A update of the current driver must be done.
The procedure is explained below:
• download the driver at the following site:
http://ftp.k-team.com/korebot/koreusbcam/driver/gspca-kb2-YOUR_KERNEL_VERSION.ko.gz
• transfer the file to the KorebotLE (with Minicom or ssh, see Annexes:
ssh)
• extract it with the command:
gunzip gspca-kb2-YOUR_KERNEL_VERSION.ko.gz
• overwrite the previous driver module:
mv gspca.ko /lib/modules/YOUR_KERNEL_VERSION
/kernel/drivers/usb/media/
• update module dependencies
depmod -a
• reboot your Korebot
reboot

KoreUSBCam User Manual rev 1.2 9
3 Usage
3.1. Assembly
This sub-chapter explains how to connect the KoreUSBCam module, depending on your
configuration:
•Plug the KoreUSBCam module onto the KorebotLE as depicted below (figure 3.1):
KoreUSBCam + KoreBotLE KoreUSBCam + Khepera III/ KoreBotLE
Figure
3.1:
KoreUSBCam
+ KoreBotLE/ KheperaIII
assembly

KoreUSBCam User Manual rev 1.2 10
3.2. Power-up
• Power up the Korebot (or Khepera 3).
 During the boot of the Korebot, the camera is detected and its gspca
module driver is automatically loaded.
Below a part of the boot sequence is depicted (fig. 3.2):
Figure 3.2: part of the boot sequence with detected camera
3.3. Images acquisition
• Grab an image with the following command:
wcggrabber --size=max --palette=RGB24 -R BGR -a -t 5 -n 0>output.ppm
This takes an image named output.ppm in the current folder.
You can view the program options with wcggrabber -h
You can transfer the image by Minicom or scp (see Annexes 4.3).
3.4. Video streaming
This part describes two streaming applications you can use to display the camera video on
a remote computer.
a) ktgrab
ktgrab is a video server running on the Korebot. You can access it with the Java applet
KTGrab. The instructions are explained below:
1. Get the ktgrab from http://ftp.k-team.com/korebot/koreusbcam/application/, file
ktgrab_libfg-0.3.1-kb1.tar.bz2
[ 13.110000] Linux video capture interface: v2.00
[ 13.130000] korebot_pcmcia_configure_socket(): Reset off sock 0
[ 13.150000] Korebot CF Init
[ 13.150000] korebot_init: skt->irq=78
[ 13.170000] korebot_pcmcia_configure_socket(): Reset off sock 1
[ 13.310000] korebot_pcmcia_configure_socket(): Reset off sock 0
[ 13.420000] /home/jtharin/projects/kernel2.6/development/gspcav1-20071224-kb2/gspca_core.c: USB GSPCA camera
found.(ZC3XX)
[ 13.510000] /home/jtharin/projects/kernel2.6/development/gspcav1-20071224-kb2/gspca_core.c: [spca5xx_probe:4314] Camera type
JPEG
[ 13.540000] /home/jtharin/projects/kernel2.6/development/gspcav1-20071224-kb2/Vimicro/zc3xx.h: [zc3xx_config:588] Sensor
MC501CB
[ 13.590000] drivers/usb/otg/otg_linux.c: otg_hcd_endpoint_disable stub
[ 13.620000] drivers/usb/otg/otg_linux.c: otg_hcd_endpoint_disable stub
[ 13.650000] /home/jtharin/projects/kernel2.6/development/gspcav1-20071224-kb2/gspca_core.c: [spca5xx_getcapability:1262] maxw
640 maxh 480 minw 160 minh 0
[ 13.680000] usbcore: registered new interface driver gspca
[ 13.680000] /home/jtharin/projects/kernel2.6/development/gspcav1-20071224-
kb2/gspca_core.c: gspca driver 01.00.20 registered

KoreUSBCam User Manual rev 1.2 11
2. Establish a connection with the computer (either network through usb, or wireless: see
Annexes 4.2)
3. Transfer ktgrab to the KoreBot by Minicom or ssh (see Annexes).
4. Launch the streaming program ktgrab on the Korebot with the command:
ktgrab PORT WIDTH HEIGHT COMPRESSION
e.g: ktgrab 1234 320 240 1
where the parameters are detailed below:
PORT : TCP communication port
WIDTH : video width: 160, 320, or 640
HEIGHT : video height: 120, 240 or 480
COMPRESSION : video compression type: 1= JPEG, 0 = RAW
Remark: these following parameters are reported as not working:
TCP port width height
Compression
1234 160 120 1
1234 640 480 0
5.
On the computer, get and extract the KTGrab Java applet available at the following
link:
http://ftp.k-team.com/korebot/koreusbcam/application/
To launch the applet, in the directory KTGrab/build/classes , run the following
command:
java ktgrab.KTGrab KOREBOT_IP PORT
e.g: java ktgrab.KTGrab 10.0.0.2 1234
where the parameters are detailed below:
KOREBOT_IP : Korebot IP address
PORT : TCP communication port (the same as above used for
the Korebot)
b) Camsource / WebCamApplet
Camsource is the video server running on the Korebot. You can access it with an Internet
browser or with the Java WebCamApplet as explained below.
1. Establish a connection with the computer (either network through usb, or wireless: see
Annexes 4.2)
2.
Launch the streaming program camsource on the Korebot with the command:
camsource

KoreUSBCam User Manual rev 1.2 12
This capture pictures at low resolution (160x120) by default, you can change the
configuration file /etc/camsource.conf to get higher resolution, at the price of much
lower frame rate (the webcam then compresses the image, and decompressing it on
the ARM is relatively slow).
3. From a computer, you can access the video by the two following ways:
a)
With an Internet browser at the following URL:
http://KOREBOT_IP:9192/largequal
b) You can also use the java applet WebCamApplet , available at the address below:
http://ftp.k-team.com/korebot/tools/WebCamApplet.zip
You can run it as a standalone application, with a command like this (change port
8888 to 8889 for high resolution images):
java WebCam KOREBOT_IP 8888 352 288
It will print picture interval in ms every time a picture is acquired (1000/the value
gets the number of frames per second).
On the KoreBot you can stop the streaming with the command:
camsource -k
3.5. Programming
The standard video for Linux device (v4l) can be used.
You can start by using the following source codes of the image capture programs
vgrabber
(1)
or wcggrabber
(2)
as examples:
You have to install the light toolchain 2.6
(3)
and compile with it:
For vgrabber:
• source the env.sh to have the cross-compiler in the path (as explained in
(3)
“Development”)
• Build it with the command:
arm-angstrom-linux-gnueabi-gcc –o vgrabber vgrabber.c
• Transfer the file vgrabber to the KoreBot (by Minicom or ssh , see
Annexes: ssh)
You can take a picture with: vgrabber> img.ppm
For wcggrabber :
• source the env.sh to have the cross-compiler in the path (as explained in
(3)
“Development”)
• Execute make –e to build it.
• Transfer the file wcggraber to the korebot
• Use it as explained in chapter 3: Usage

KoreUSBCam User Manual rev 1.2 13
(1)
http://www.tazenda.demon.co.uk/phil/vgrabber.c
(2)
http://ftp.k-team.com/korebot/tools/wcggrabber-1.6.2_arm.tar.bz2
(3)
http://ftp.k-team.com/korebot/toolchain-2.6-
betaV0.1/light_toolchain/development_light_kernel2.6_readme.txt

KoreUSBCam User Manual rev 1.2 14
4 Annexes
In this part, the detailed descriptions of several tools and helpful commands are explained.
4.1. Using a Wireless compact flash card
Two wireless compact flash models are supported. The card name and its driver are listed below:
A) Ambicom WL1100C-CF with hostap_cs driver module
B) Ambicom WL5400G-CF with libertas_cs driver module
Remark:
The following instructions are for the wireless compact flash A) Ambicom WL1100C-
CF . With the model B) WL5400G-CF , you have to update your kernel and the driver as
described at:
http://ftp.k-team.com/korebot/kernel/kernel2.6.25.7-kb1/Kernel2.6.25-7-
kb1_WifiG-support.txt
Then you may replace the wireless port name wlan0 by eth0 in the following instructions.
1) insert a Wireless compact flash card in the Korebot
2) load the module by typing: modprobe pxa2xx_cs
You may load the Wifi module automatically by adding pxa2xx_cs in the file
/etc/modules .
You can use the following command echo to add the module name to the file:
echo pxa2xx_cs>>/etc/modules
3)
- i) WEP support
a) for configuring the wifi connection, type:
iwconfig wlan0 essid YOUR_SSID_OF_NETWORK
b) if the network is secured, enter the key by typing :
iwconfig wlan0 key YOUR_KEY
c) then set an ip address to the korebot:
ifconfig wlan0 YOUR_IP_ADDRESS
d) configure the gateway by entering the gateway ip:
route add default gw YOUR_GATEWAY_IP wlan0

KoreUSBCam User Manual rev 1.2 15
e) insert the local domain name in /etc/resolv.conf
echo search YOUR_LOCAL_DOMAIN_NAME>>etc/resolv.conf
f) and the dns server
echo nameserver YOUR_DNS_SERVER_IP_ADDRESS>> /etc/resolv.conf
You can also create a file in
/etc/network/if-pre-up.d named wireless to have these
settings saved.
Put the following into it:
#!/bin/sh
ifconfig wlan0 up
iwconfig wlan0 essid YOUR_SSID_OF_NETWORK
iwconfig wlan0 key s:YOUR_KEY
ifconfig wlan0 YOUR_IP_ADDRESS
route add default gw YOUR_GATEWAY_IP wlan0
And the following in a file named /etc/resolv.conf :
search YOUR_LOCAL_DOMAIN_NAME
nameserver YOUR_DNS_SERVER_IP_ADDRESS
ii) WEP, WPA and other encryptions:
a) create a file named /etc/wpa_supplicant/wpa_supplicant.conf
and insert your selected wireless encryption:
WEP:
#Shared WEP key connection (no WPA):
network={
ssid="YOUR_SSID"
key_mgmt=NONE
wep_key0="YOUR_WEP_KEY"
auth_alg=SHARED
wep_tx_keyidx=0
priority=5
}
WPA-TKIP:
- see instructions at:
http://ftp.k-team.com/korebot/kernel/modules/wpa-tkip/wpa-tkip_support.txt
#/etc/wpa_supplicant/wpa_supplicant.conf
with WPA-PSK TKIT:
network={
ssid="YOUR_SSID"
psk="YOUR_PASS_KEY"
key_mgmt=WPA-PSK
group=TKIP

KoreUSBCam User Manual rev 1.2 16
pairwise=TKIP
proto=WPA
priority=5
}
You can check the following link for other encryptions:
http://hostap.epitest.fi/wpa_supplicant/
b) run the daemon controlling the wireless connection with the following command:
wpa_supplicant -c /etc/wpa_supplicant/wpa_supplicant.conf -i wlan0 -Dwext -B
You can also add the command above to a file
in /etc/network/if-pre-up.d named wireless :
#!/bin/sh
ifconfig wlan0 up
ifconfig wlan0 YOUR_IP_ADDRESS
route add default gw YOUR_GATEWAY wlan0
wpa_supplicant -c /etc/wpa_supplicant/wpa_supplicant.conf -i wlan0 -Dwext -B
4.2. Connecting to the Korebot with network over usb cable
a) launch the usb module on the Korebot:
modprobe g_ether
b) connect the computer to the Korebot USB slave port with an USB cable
c) configure the usb port on the Korebot:
ifconfig usb0 10.0.0.2/24
d) on the computer, configure also the usb port (you must be root, or use sudo):
ifconfig usb0 10.0.0.1/24
4.3. Transferring files using scp (ssh)
1) Establish a network connection between the computer and the korebot (using Wifi see
chapter "Using a Wireless compact flash card", or using Ethernet over usb see chapter
"Connecting to the Korebot with network over usb cable"
2) Execute the following command, where FILE, is the file to transfer, KOREBOT_IP the
Korebot ip address.
scp FILE root@KOREBOT_IP:/home/root

KoreUSBCam User Manual rev 1.2 17
5 WARRANTY
K-TEAM warrants that the KoreUSBCam is free from defects in materials and
workmanship and in conformity with the respective specifications of the product for the
minimal legal duration, respectively one year from the date of delivery.
Upon discovery of a defect in materials, workmanship or failure to meet the
specifications in the Product during the afore mentioned period, Customer must request
help on K-Team Internet forum on http://www.k-team.com/kforum/ by detailing:
• The type of KoreUSBCam used (version).
• The kernel version of the Korebot.
• The programming environment of the Korebot/robot (standard, version, OS).
• The standard use of Product before the appearance of the problem.
• The description of the problem.
If no answers have been received within two working days, Customer can contact K-
TEAM support by phone or by electronic mail with the full reference of its order and
KoreUSBCam serial number.
K-TEAM shall then, at K-TEAM's sole discretion, either repair such Product or
replace it with the equivalent product without charging any technical labour fee and repair
parts cost to Customer, on the condition that Customer brings such Product to K-TEAM
within the period mentioned before. In case of repair or replacement, K-TEAM may own
all the parts removed from the defective Product. K-TEAM may use new and/or
reconditioned parts made by various manufacturers in performing warranty repairs and
replacement of the Product. Even if K-TEAM repairs or replaces the Product, its original
warranty term is not extended.
This limited warranty is invalid if the factory-applied serial number has been altered
or removed from the Product.

KoreUSBCam User Manual rev 1.2 18
This limited warranty covers only the hardware and software components contained
in the Product. It does not cover technical assistance for hardware or software usage and it
does not cover any software products contained in the Product. K-TEAM excludes all
warranties expressed or implied in respect of any additional software provided with Product
and any such software is provided "AS IS" unless expressly provided for in any enclosed
software limited warranty. Please refer to the End User License Agreements included with
the Product for your rights with regard to the licensor or supplier of the software parts of
the Product and the parties' respective obligations with respect to the software.
This limited warranty is non-transferable.
It is likely that the contents of Customer's flash memory will be lost or reformatted in
the course of the service and K-TEAM will not be responsible for any damage to or loss of
any programs, data or other information stored on any media or any part of the Product
serviced hereunder or damage or loss arising from the Product not being available for use
before, during or after the period of service provided or any indirect or consequential
damages resulting therefore.
IF DURING THE REPAIR OF THE PRODUCT THE CONTENTS OF THE FLASH
MEMORY ARE ALTERED, DELETED, OR IN ANY WAY MODIFIED, K-TEAM IS
NOT RESPONSIBLE WHATEVER. CUSTOMER'S PRODUCT WILL BE RETURNED
TO CUSTOMER CONFIGURED AS ORIGINALLY PURCHASED (SUBJECT TO
AVAILABILITY OF SOFTWARE).
Be sure to remove all third parties' hardware, software, features, parts, options,
alterations, and attachments not warranted by K-TEAM prior to Product service. K-TEAM
is not responsible for any loss or damage to these items.
This warranty is limited as set out herein and does not cover, any consumable items
(such as batteries) supplied with the Product; any accessory products which is not contained
in the Product; cosmetic damages; damage or loss to any software programs, data, or
removable storage media; or damage due to (1) acts of God, accident, misuse, abuse,
negligence, commercial use or modifications of the Product; (2) improper operation or
maintenance of the Product; (3) connection to improper voltage supply; or (4) attempted
repair by any party other than a K-TEAM authorized module service facility.
This limited warranty does not apply when the malfunction results from the use of the
Product in conjunction with any accessories, products or ancillary or peripheral equipment,
or where it is determined by K-Team that there is no fault with the Product itself.

KoreUSBCam User Manual rev 1.2 19
K-TEAM EXPRESSLY DISCLAIMS ALL OTHER WARRANTIES THAN
STATED HEREINBEFORE, EXPRESSED OR IMPLIED, INCLUDING WITHOUT
LIMITATION IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE TO THE FULLEST EXTENT PERMITTED BY LAW.
Limitation of Liability: IN NO EVENT SHALL EITHER PARTY BE LIABLE TO
THE OTHER FOR ANY INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES RESULTING FROM PERFORMANCE OR FAILURE TO PERFORM
UNDER THE CONTRACT, OR FROM THE FURNISHING, PERFORMANCE OR USE
OF ANY GOODS OR SERVICE SOLD OR PROVIDED PURSUANT HERETO,
WHETHER DUE TO A BREACH OF CONTRACT, BREACH OF WARRANTY,
NEGLIGENCE, OR OTHERWISE. SAVE THAT NOTHING HEREIN SHALL LIMIT
EITHER PARTY'S LIABILITY FOR DEATH OR PERSONAL INJURY ARISING
FROM ITS NEGLIGENCE, NEITHER PARTY SHALL HAVE ANY LIABILITY TO
THE OTHER FOR INDIRECT OR PUNITIVE DAMAGES OR FOR ANY CLAIM BY
ANY THIRD PARTY EXCEPT AS EXPRESSLY PROVIDED HEREIN.

KoreUSBCam User Manual rev 1.2 20
K-Team S.A.
Rue Galilee 9
1400 Yverdon-les-bains
Switzerland