IFM Electronic O3X100 Programmer's Manual
Programmers Guide
Interface description
3D Camera
O3X100
UK
706447 / 00 12 / 2018
3D camera O3X1xx
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
2
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.
3
3D camera O3X1xx
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
4
3D camera O3X1xx
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
UK
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>
5
3D camera O3X1xx
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
requestSession(...)
Session
EditMode
DeviceConfig
ApplicationConfig
NetworkConfig
TimeConfig
ImagerConfig
6
Main API
cancelSession(...) removes itself from RPC. Session will also
be removed, if heartbeat(...) is not called at the right time
Session
EditMode
ApplicationConfig
4.2.1 Main Object
3D camera O3X1xx
UK
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 DeviceCong Object
Object-URI e.g.: /api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/device/
4.2.5 Device/NetworkCong Object
Object URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/device/network/
4.2.6 TimeCong Object
Object URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/device/time/
4.2.7 Application Cong Object
Object URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/application/
7
3D camera O3X1xx
4.2.8 Application/Imager Cong 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
8
3D camera O3X1xx
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.
UK
It is not possible to send commands.
9
Loading...