IFM O3X1 Series Manual

Programmers Guide
Interface description
3D Camera
O3X100
706447 / 00 12 / 2018
UK

3D camera O3X1xx
2
Contents
1. Preliminary note...................................................................4
1.1 Symbols used .................................................................4
1.2 Safety instructions .............................................................4
1.3 Further documents .............................................................4
2. System requirements...............................................................4
2.1 Software .....................................................................4
2.2 Hardware and accessories .......................................................4
3. Required Ports....................................................................5
4. XML-RPC Interface ................................................................5
4.1 Sample XML-RPC command .....................................................5
4.2 XML-RPC Objects .............................................................6
4.2.1 Main Object...............................................................7
4.2.2 Session Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
4.2.3 EditMode Object ...........................................................7
4.2.4 DeviceConfig Object........................................................7
4.2.5 Device/NetworkConfig Object.................................................7
4.2.6 TimeConfig Object .........................................................7
4.2.7 Application Config Object ....................................................7
4.2.8 Application/Imager Config Object ..............................................8
5. Process Interface..................................................................9
5.1 Protocol structure ..............................................................9
5.2 Receiving Images .............................................................10
5.3 Image data ..................................................................10
5.3.1 Chunk type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
5.3.2 Available chunk types......................................................11
5.3.3 Pixel format..............................................................12
5.4 Additional Information for CONFIDENCE_IMAGE ....................................13
6. XML-RPC Command Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
6.1 Parameter API ...............................................................14
6.2 Main Object..................................................................15
6.3 Session Object ...............................................................19
6.4 Edit Mode Object .............................................................21
6.5 Device Config Object ..........................................................21
6.6 Device/Network Config Object ...................................................23
6.7 Time Config Object ............................................................24
6.8 Application Config Object .......................................................25
6.9 Application/Imager Config Object .................................................27
6.10 Exposure modes.............................................................29

3
3D camera O3X1xx
UK
Licences and trademarks
Microsoft®, Windows®, Windows 7®, Windows 8®, Windows 8.1®and Windows 10®are registered
trademarks of Microsoft Corporation.
Adobe® and Acrobat® are registered trademarks of Adobe Systems Inc.
All trademarks and company names used are subject to the copyright of the respective companies.
This device contains (maybe modified) open source software which is subject to special licensing terms.
For copyright information and licensing terms please refer to: www.ifm.com/int/GNU
For software subject to the GNU General Public License or the GNU Lesser General Public License the
source code can be requested against payment of the copying and shipping costs.

3D camera O3X1xx
4
1. Preliminary note
This document describes the software interfaces of the O3X1xx 3D camera.
1.1 Symbols used
►Instructions
> Reaction, result
[…] Designation of keys and buttons
"…" Name of display text
→Cross-reference
Important note
Non-compliance may result in malfunction or interference.
Information
Supplementary note
1.2 Safety instructions
Please read the operating instructions prior to set-up of the device. Ensure that the device is suitable for
your application without any restrictions.
If the operating instructions or the technical data are not adhered to, personal injury and damage to
property can occur.
1.3 Further documents
●Operating instructions
●Interface description
The documents can be downloaded at:
www.ifm.com
2. System requirements
2.1 Software
Windows 7 (32/64 bit), Windows 8.1 (32/64 bit), Windows 10 (32/64 bit)
2.2 Hardware and accessories
Hardware:
– Camera of the O3X1xx product family
– PC with x86 or x64 type processor
– Screen: min. 1024 x 768 pixels, 32 bit colour depth
– Ethernet interface
The Ethernet interface can be retrofitted with an USB-to-Ethernet adapter.
Accessories:
– Power supply 24 V, 1.6 A, min. peak current 2.4 A
You will find further information about available accessories at:
www.ifm.com

5
3D camera O3X1xx
UK
3. Required Ports
The following ports are required for the camera configuration using XML-RPC and for receiving data on
the process interface. They must not be blocked by a firewall or router.
●TCP/HTTP: 80
●TCP: 50010
If the ifm Vision Assistant is used, the following additional ports must also be available:
●UDP: 3321
●TCP/HTTP: 8080
4. XML-RPC Interface
In case the device should not be configured by the ifm Vision Assistant, the XML-RPC interface can be
used instead.
General information about XML-RPC is found on the website http://xmlrpc.scripting.com/spec
To send a command via the XML-RPC interface the command is in a special layout. In this command,
linefeeds and carriage returns are essential.
Every command which is sent via the XML-RPC interface must end with carriage return <CR> and
linefeed <LF>.
Several commands will use different URLs in the XML-RPC header.
Preferably use the ifm3Dlib for access to the device under Linux. The library has been tested and is
the reference implementation for C++. The library is supported by ifm electronic and the company
Lovepark Robotics.
A detailed example is available on the web at:
https://github.com/ifm/ifm3d-examples/blob/master/file_io/ex-file_io.cpp
4.1 Sample XML-RPC command
All following XML-RPC commands will have this type of layout:
POST /RPC3 HTTP/1.0<CR><LF>
User-Agent: Frontier/5.1.2 (WinNT)<CR><LF>
Host: betty.userland.com<CR><LF>
Content-Type: text/xml<CR><LF>
Content-length: 181<CR><LF>
<CR><LF>
<?xml version="1.0"?><CR><LF>
<methodCall><CR><LF>
<methodName>examples.getStateName</methodName><CR><LF>
<params><CR><LF>
<param><CR><LF>
<value><i4>41</i4></value><CR><LF>
</param><CR><LF>
</params><CR><LF>
</methodCall><CR><LF>

3D camera O3X1xx
6
The following example contains one O3X1xx command:
POST /api/rpc/v1/com.ifm.efector/ HTTP/1.1<CR><LF>
Host: 192.168.0.69<CR><LF>
Content-Type: text/xml<CR><LF>
User-Agent: Python-xmlrpc/3.4<CR><LF>
Content-Length: 160<CR><LF>
<CR><LF>
<?xml version='1.0'?> <CR><LF>
<methodCall><CR><LF>
<methodName>getParameter</methodName><CR><LF>
<params><CR><LF>
<param><CR><LF>
<value><string>Name</string></value><CR><LF>
</param><CR><LF>
</params><CR><LF>
</methodCall><CR><LF>
4.2 XML-RPC Objects
To communicate and to configure the device via XML-RPC the XML-RPC commands have to use
different XML-RPC objects. Different commands need different XML-RPC objects (see XML-RPC
command references).
The interface of O3X1xx is structured in an object-oriented way. Some of the objects are available all
the time, others are only available after bringing the device into a special mode by calling a method
on an already available object. This mechanism is used to create system requirements (e.g. password
protection).
It could be necessary to send heartbeats so that there will be no session timeout.
The following diagram should give an overview how objects are related to each other and which methods
must be called to make others available:
Main API
Session
EditMode
ApplicationConfig
requestSession(...)
DeviceConfig
NetworkConfig
ImagerConfig
TimeConfig

7
3D camera O3X1xx
UK
4.2.1 Main Object
Object-URI: /api/rpc/v1/com.ifm.efector/
This is the main object of RPC. It contains methods to open a session. Most of its methods are only
getters, because it should be possible to protect editing with a password.
4.2.2 Session Object
Object URI e.g.: /api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/
The URL part “d21c80db5bc1069932fbb9a3bd841d0b” is the session ID. It is returned by the command
"requestSession" of the main object. If the command "requestSession" is called without a user-defined
session ID, which can be passed as a parameter, a random session ID is generated automatically.
4.2.3 EditMode Object
Object URI e.g.: /api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/
4.2.4 DeviceCong Object
Object-URI e.g.: /api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/device/
4.2.5 Device/NetworkCong Object
Object URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/device/network/
4.2.6 TimeCong Object
Object URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/device/time/
4.2.7 Application Cong Object
Object URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/application/
Main API
Session
EditMode
ApplicationConfig
cancelSession(...) removes itself from RPC. Session will also
be removed, if heartbeat(...) is not called at the right time

3D camera O3X1xx
8
4.2.8 Application/Imager Cong Object
Object URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/application/imager_001/
As there is only one imager config on the device, the ID must be fixed to "001". Data of this object is
persistently saved when calling "save" on the application config object. The imager config RPC object
has multiple sub-types. Only parameters relevant for a specific type are available while it is active. They
are based on frequency (extending the distance) and integration intervals (extending the measurement
details).
Type names, based on ifm Vision Assistant draft:
●upTo02m_low
●upTo02m_moderate
●upTo03m_low
●upTo03m_moderate
●upTo07m_low
●upTo07m_moderate
●upTo15m_low
●upTo15m_moderate
●upTo30m_low
●upTo30m_moderate

9
3D camera O3X1xx
UK
5. Process Interface
The process interface is used during the normal operation mode to get operational data (e.g. 3D images,
process values) from the O3X1xx.
5.1 Protocol structure
This protocol conforms to the version 3 of the O2V/O2D products.
Structure of the protocol:
<Ticket><length>CR LF <Ticket><content>CR LF
Abbreviation Description ASCII code (dec) ASCII code (hex)
CR Carriage Return 13 D
LF Linefeed 10 A
< > Marking of a placeholder
(e.g. <code> is a placeholder for code)
[ ] Optional argument
(possible but not required)
Command Description
<content> It is the command (e.g. trigger the unit).
<ticket> It is a character string fixed to 0000. The device will reply with the same ticket number.
<length> It is a character string beginning with the letter 'L' followed by 9 digits. It indicates the
length of the following data (<ticket><content>CR LF) in bytes.
It is not possible to send commands.

3D camera O3X1xx
10
5.2 Receiving Images
For receiving the image data a TCP/IP socket communication is established. The default port number is
50010. After opening the socket communication, the O3X1xx device will automatically (if the device is in
free run mode) send the data through this socket to the TCP/IP client (PC).
PCIC output per frame. The following data is submitted in this sequence:
Component Content
Ticket „0000“
Start sequence String "star" (4 bytes)
Normalised amplitude image
Output format: 32-bit floating point number
1 image
Distance image
Output format: 32-bit floating point number.
Unit: m.
1 image
Combined XYZ image
Output format: 32-bit floating point number.
Unit: m.
1 image
Confidence image
Output format: 8-bit unsigned integer
1 image
Grayscale image
Output format: 32-bit floating point number
1 image
Stop sequence String "stop" (4 bytes)
Ticket signature <CR><LF>
Only configured images will be displayed.
5.3 Image data
For every image there will be a separate chunk. The chunk is part of the response frame data of the
process interface.
The header of each chunk contains different kinds of information. This information is separated into bytes.
The information contains e.g. the kind of image which will be in the “PIXEL_DATA” and the size of the
chunk.
5.3.1 Chunk type
Offset Name Description Size [byte]
0x0000 CHUNK_TYPE Defines the type of the chunk. For each distinct chunk
an own type is defined.
4
0x0004 CHUNK_SIZE Size of the whole image chunk in bytes. After this count
of bytes the next chunk starts.
4
0x0008 HEADER_SIZE Number of bytes starting from 0x0000 until PIXEL_
DATA.
4
0x000C HEADER_VERSION Version number of the header 4
0x0010 IMAGE_WIDTH Image width in pixel 4
0x0014 IMAGE_HEIGTH Image height in pixel 4
0x0018 PIXEL_FORMAT Pixel format 4
0x001C TIME_STAMP Time stamp in microseconds 4
0x0020 FRAME_COUNT Frame count according to algorithm output 4
0x0024 STATUS_CODE Errors on the device 4