IFM Electronic O3D303 Operation Manual
Seite 1 von 72
Operations Manual
3D camera
O3D303
Seite 2 von 72
1 PRELIMINARY NOTE ................................................................ 5
2 SAFETY INSTRUCTIONS ........................................................... 5
3 FUNCTIONS AND FEATURES ...................................................... 5
4 INSTALLATION ....................................................................... 6
4.1 Object distance ................................................................................ 6
4.2 Camera surroundings ....................................................................... 6
4.3 Heat dissipation ............................................................................... 7
5 LED DISPLAY ........................................................................ 8
6 ELECTRICAL CONNECTION........................................................ 9
6.1 Wiring .............................................................................................. 10
7 XML-RPC INTERFACE ............................................................ 11
7.1 Sample XML-RPC command .............................................................. 11
7.2 XML-RPC Objects ............................................................................. 12
7.2.1 Main-Object: ........................................................................... 14
7.2.2 SessionObject ......................................................................... 14
7.2.3 EditMode-Object ...................................................................... 14
7.2.4 DeviceConfig-Object ................................................................ 14
7.2.5 Device/NetworkConfig-Object .................................................... 14
7.2.6 ApplicationConfig-Object (editable application) ........................... 14
7.2.7 App./ImagerConfig-Object (O3D3xx) .......................................... 15
7.2.8 Image-Settings Filter-Parameter ................................................ 15
8 PROCESS INTERFACE .............................................................. 16
8.1 Sending commands .......................................................................... 16
8.2 Receiving images ............................................................................. 18
8.3 Image data ....................................................................................... 20
8.4 Additional information for image data ............................................... 25
8.5 Configuration of PCIC output............................................................ 27
8.6 Sample C++ Code for setting up a socket .......................................... 32
9 XML-RPC COMMAND REFERENCES ............................................ 33
Seite 3 von 72
9.1 "setParameter" must be implemented on all RPC-objects which offer parameter
33
9.2 Main-Object ..................................................................................... 33
9.2.1 "getParameter” ........................................................................ 33
9.2.2 "getAllParameters" .................................................................. 33
9.2.3 "getSWVersion" ....................................................................... 34
9.2.4 "getHWInfo" ............................................................................ 35
9.2.5 "getApplicationList”.................................................................. 35
9.2.6 "requestSession" ..................................................................... 36
9.2.7 "reboot" .................................................................................. 36
9.2.8 "systemCommand” ................................................................... 36
9.3 Session-Object ................................................................................. 37
9.3.1 "heartbeat" ............................................................................. 37
9.3.2 "cancelSession”....................................................................... 37
9.3.3 "exportConfig” ......................................................................... 37
9.3.4 "importConfig” ......................................................................... 38
9.3.5 "exportApplication” .................................................................. 38
9.3.6 "importApplication” .................................................................. 38
9.3.7 "setOperatingMode" ................................................................. 39
9.4 EditMode-Object............................................................................... 40
9.4.1 "factoryReset" ......................................................................... 40
9.4.2 "editApplication" ...................................................................... 40
9.4.3 "stopEditingApplication" ........................................................... 40
9.4.4 "createApplication" .................................................................. 41
9.4.5 "copyApplication" .................................................................... 41
9.4.6 "deleteApplication" .................................................................. 41
9.4.7 "moveApplications" .................................................................. 42
9.5 DeviceConfig-Object ........................................................................ 43
9.5.1 "activatePassword" .................................................................. 43
9.5.2 "disablePassword" ................................................................... 43
9.5.3 "save" .................................................................................... 43
9.5.4 Parameters ............................................................................. 44
9.6 Device/NetworkConfig-Object ........................................................... 49
Seite 4 von 72
9.6.1 "saveAndActivateConfig" .......................................................... 49
9.7 ApplicationConfig-Object ................................................................. 49
9.7.1 "save" .................................................................................... 49
9.7.2 "forceTrigger" .......................................................................... 49
9.7.3 "validate" ................................................................................ 50
9.7.4 Parameters ............................................................................. 51
9.8 App./ImgagerConfig-Object .............................................................. 53
9.8.1 "changeType" .......................................................................... 53
9.8.2 "availableTypes" ...................................................................... 53
9.8.3 Parameters ............................................................................. 54
9.9 Image-Settings Filter-Parameter ....................................................... 61
9.9.1 Parameters ............................................................................. 61
10 PROCESS INTERFACE COMMAND REFERENCE ............................... 63
10.1 t command ....................................................................................... 63
10.2 T? command .................................................................................... 63
10.3 I? command ..................................................................................... 64
10.4 p command ...................................................................................... 65
10.5 a command ...................................................................................... 65
10.6 A? command .................................................................................... 66
10.7 v command ...................................................................................... 67
10.8 V? command .................................................................................... 67
10.9 c command ...................................................................................... 68
10.10 C? command .................................................................................... 68
10.11 S? command .................................................................................... 69
10.12 L? command .................................................................................... 70
10.13 G? command .................................................................................... 71
10.14 H? command .................................................................................... 72
Seite 5 von 72
1 PRELIMINARY NOTE
This document is intended for specialists. These specialists are people who are qualified
by their appropriate training and their experience to see risks and to avoid possible hazards that may be caused during operation or maintenance of the device. The document contains information about the correct handling of the device.
Read this document before use to familiarise yourself with operating conditions and installation. Keep this document during the entire duration of use of the device.
2 SAFETY INSTRUCTIONS
This instruction is part of the device. It contain texts and figures concerning the correct
handling of the device and must be read before installation or use.
Note the safety instructions. Use the device in accordance with its designated use.
The installation and connection must comply with the applicable national and international
standards. Responsibility lies with the person installing the device.
Only the signals indicated in the technical data or on the device label may be supplied to
the connections or wires.
The unit may only be opened by the manufacturer or by a person authorised by the manufacturer.
3 FUNCTIONS AND FEATURES
The O3D303 3D camera is an optical camera equipped with an internal illumination unit
measuring the distance between the camera and the nearest surface point by point.
The data is used to describe the captured scene three-dimensionally.
The data is issued and the device parameters are set via Ethernet.
The unit may only be used under the environmental conditions specified in the data sheet.
The device safety is rated for use under the following environmental conditions:
• Indoor use
• Altitudes up to 2000 m
• Relative air humidity up to max. 90%, non condensing
• Pollution degree 3
Seite 6 von 72
4 INSTALLATION
► Use cables with strain relief.
4.1 Object distance
► Choose the mounting position of the camera so that the object of interest is completely
located within the field of view of the camera. Make allowances for positioning tolerances.
The field of view may be found in the product data sheet. The lateral dimensions of the
camera image increase linearly with the distance from the camera, i.e. the field of view increases with increasing distance.
► The distance between camera and object must not exceed the maximum measuring
range and should be within the operating distance stated in the product data sheet.
► The distance between the camera and the object of interest should be chosen as small
as possible in order to measure the object with maximum resolution.
4.2 Camera surroundings
► For best measurement accuracy the object of interest (C) should be the object closest
to the camera within the field of view (B).
► Objects which are located close to the field of view (area A) may lead to measurement
errors and should be avoided. This also includes mounting posts, clamps, etc.
Seite 7 von 72
► Bright extraneous light such as e.g. sun light incident on the surface of the object of
interest or on the camera lens should be avoided. Only the infrared portion of the light between 800nm and 900nm is critical and should not exceed the sunlight-equivalent of 8klux.
► The camera optics must be kept clean. Avoid installation in heavy polluting areas of a
machine. Mounting the camera facing down may help to reduce collection of dust on the
front window.
► Do not install the camera behind windows. Direct reflection from the camera illumination
back into the camera lens may lead to measurement errors. Such reflections are present
even at very clean glass surfaces.
4.3 Heat dissipation
ATTENTION
Depending on the operating mode, the unit may heat up.
The difference between the unit's surface temperature and the ambient temperature may
not exceed 25 degrees. Take one or several of the following measures:
► Preferably mount camera to large metal parts which are good heat conductors such as
e.g. aluminium. A good thermal contact between camera and camera mounting increases
the dissipation of excess heat. A heat conducting plate is available as separate accessory.
► Allow the circulation of air around the camera to allow thermal convection. Mounting
positions directly under a roof or in cramped areas may lead to heat accumulation.
► Thermal convection may be further improved by using one or two heat dissipators which
are available as separate accessories.
► The camera temperature may also be reduced by reducing the following operation parameters of the camera:
- frame rate
- exposure time
- maximum measurement distance (number of used frequencies)
► Use a contact protection.
Seite 8 von 72
5 LED DISPLAY
LED behaviour, device status
LED 1
Power
(green)
ON: supply voltage available, device ready for operation
flashing (0,5 Hz)
:
No parametrisation available.
flashing (0,5 Hz)
setup mode
LED 2
Out1
(yellow)
ON: switching output 1 is on
flashing (8Hz): short circuit switching output 1
LED 3
Out2
(yellow)
ON: switching output 1 is on
flashing (8Hz): short circuit switching output 2
LED 4
Ethernet
(green)
OFF: no ethernet connection
ON: ethernet connection
flashing: ethernet communication
Other status displayed by LEDs:
- LED 2 and 3 (both yellow) flash simultaneously (8 Hz) internal error
- LED 2 and 3 flash simultaneously (2 Hz) repairable error, please note ethernet error
message
- Sequence flashing LED 1, 2 und 3 device is booting
- Sequence flashing LED 3, 2 und 1 firmware update
Seite 9 von 72
6 ELECTRICAL CONNECTION
ATTENTION
The unit must be connected by a qualified electrician.
Device of protection class III (PC III)
Electric supply via PELV circuits only.
Electric supply must comply with UL61010-1, chap. 9.4 - Limited Energy.
The separation of external circuits must comply with UL61010-2-201, fig. 102.
► Disconnect power before connecting the unit.
Seite 10 von 72
6.1 Wiring
Seite 11 von 72
7 XML-RPC INTERFACE
In case the camera O3D3xx should not be configured by the “ifmVisionAssistant”, the XMLRPC interface can be used instead.
Note: general information about XML-RPC is found on the website
http://xmlrpc.scripting.com/spec
To send a command over the XML-RPC interface the command has to be on a special layout. In this command, linefeeds and carriage returns are essential.
Several commands will use different URL in the XML-RPC header.
7.1 Sample XML-RPC command
All following XML-RPC commands will have this type of layout:
POST /RPC3 HTTP/1.0User-Agent: Frontier/5.1.2 (WinNT)
Host: betty.userland.com
Content-Type: text/xml
Content-length: 181
<?xml version="1.0"?>
<methodCall>
<methodName>examples.getStateName</methodName>
<params>
<param>
<value><i4>41</i4></value>
</param>
</params>
</methodCall
Seite 12 von 72
Following example contains one command of the O3D3xx:
POST /api/rpc/v1/com.ifm.efector/
User-Agent: Frontier/5.1.2 (WinNT)
Host: 192.168.0.69
Content-Type: text/xml
Content-length: 94
<?xml version="1.0"?>
<methodCall>
<methodName>getParameter</methodName>
</methodCall>
7.2 XML-RPC Objects
To communicate and to configure the device over 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 O3D3xx 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 model
system-requirements (e.g. password-protection)
Note: 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:
Seite 13 von 72
Seite 14 von 72
7.2.1 Main-Object:
Object-URI: /api/rpc/v1/com.ifm.efector/
This is the main-object of RPC, it allows to access some basic information and contains
methods for activating edit-mode. Most of its methods are only Getter, because it should be
possible to lock the editing behind a password.
7.2.2 SessionObject
Object-URI e.g.: /api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/
The URL Part “d21c80db5bc1069932fbb9a3bd841d0b” is a sample. If the command "requestSession" from the Main-Object is used without a parameter the C3 sample will generate one and sent this back. It is also possible to define a “Session-Object” by own when it
is used as the parameter of “requestSession”.
7.2.3 EditMode-Object
Object-URI e.g.: /api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/
This object is only available if the device is in edit-OperatingMode. Index of Applications
must be between 1 and 32. The device must only support 32 applications and the indexes
must start at 1.
7.2.4 DeviceConfig-Object
Object-URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/device/
7.2.5 Device/NetworkConfig-Object
Object-URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/device/network/
7.2.6 ApplicationConfig-Object (editable application)
Object-URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/application/
Seite 15 von 72
7.2.7 App./ImagerConfig-Object (O3D3xx)
Object-URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/application/i
mager_001/
As there is only one imger-config on O3D3xx, the ID must be fixed to "001". Data of this
object is persistent saved, when calling "save" on ApplicationConfig-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 measure-details).
type-names, based on GUI-draft (under 5 meter->single Frequency, upto30 meter->double
Freq., more than 30 Meter -> 3Freq.):
under5m_low
under5m_moderate
under5m_high
upto30m_low
upto30m_moderate
upto30m_high
morethan30m_low
morethan30m_moderate
morethan30m_highunder5m_high
7.2.8 Image-Settings Filt er-Parameter
There must be a RPC-object for spatial filter parameters in each imager configuration.
Object-URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/application/imager_001/spatialfi
lter
There must be a RPC-object for temporal filter parameters in each imager configuration.
Object-URI e.g.:
/api/rpc/v1/com.ifm.efector/session_d21c80db5bc1069932fbb9a3bd841d0b/edit/application/imager_001/tempor
alfilter
Data of these objects are persistent saved, when calling "save" on ApplicationConfig-object.
Seite 16 von 72
8 PROCESS INTERFACE
The process interface is used during the normal operation mode for to get operational data
(e.g. 3D-images, process values) from the O3D3xx.
8.1 Sending commands
For sending commands over the process interface, the commands have to be send with a
special protocol and as strings. This protocol conforms to the version 3 of the O2V/O2D
products.
Structure of the protocol:
<Ticket><length>CR LF <Ticket><contents>CR LF
Abbreviation Description ASCII code (dec)
CR Carriage Return
13
LF Linefeed
10
< > Marking of a placeholder (e.g.
<code> is a placeholder for
code)
[ ]
Optional argument (possible
but not required)
<contents> is the command to the device (e.g. trigger the unit).
<ticket> is a character string of 4 digits 0-9, to be interpreted as decimal
number. If a message with a specific ticket is sent to the device, its
reply will contain the same ticket
<length> is a character string beginning with the letter 'L' followed by 9 digits
to be interpreted as decimal number. This figure indicates the length
of the following data (<ticket><contents>CR LF) in bytes.
Seite 17 von 72
Version
input format output format
V1 <Content>CR LF as input
V2 <Ticket><Content>CR LF as input
V3 <Ticket><Length>CR+LF<Ticket><Content>CR
LF
as input
V4 <Content>CR LF <length>CR
LF<Content>CR LF
The default protocolversion is „V3“.
Seite 18 von 72
8.2 Receiving images
For receiving the image data there has to be a TCP/IP socket communication established.
This communication works on the Port 50010. After opening the socket communication the
O3D3XX sample will automatically (if the unit is in free run mode) send the image data
through this socket to the TCP/IP client (PC).
PCIC output per frame. The following data shall be submitted in this sequence:
Component Content
Ticket and length information Please see chapter 8.2
Ticket „0000“
Start sequence String "star" (4 bytes)
normalized amplitude image
output format: 16 Bit Unsigned Integer.
1 image
distance image
output format: 16 Bit Unsigned Integer. Unit is
mm.
1 image
x-image
output format: 16 Bit Signed Integer. Unit ist mm.
1 image
y-image
output format: 16 Bit Signed Integer. Unit ist mm.
1 image
z-image
output format: 16 Bit Signed Integer. Unit ist mm.
1 image
Confidence image
output format: 8 Bit Unsigned Integer
1 image
Diagnostic data
Stop sequence String "stop" (4 bytes)
Ticket finish <CR><LF>
Seite 19 von 72
Diagnostic data output has the following structure:
Illumination Temperature
32-bit signed int 4 bytes
Frontend Temperature 1
32-bit signed int 4 bytes
Frontend Temperature 2
32-bit signed int 4 bytes
i.mx6 Temperature 32-bit signed int 4 bytes
Frametime (planned) 32-bit unsigned
integer
4 bytes
Framerate 32-bit unsigned
integer
4 bytes
All temperature values have the unit 0.1 °C, invalid temperatures have the value 0x7FFF
(32767).
i.mx6 temperature is not measured in C3 sample. Therefor these temperatures have the
value 0x7FFF (32767).
Seite 20 von 72
8.3 Image data
For every image there will be a separate chunk. The chunk is a part of the response frame
data from the process interface. The image data layout of the response is separated to
these points:
The header of each chunk contains different kind 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.
Chunk type:
Offset Name Description Size
[Byte]
0x0000 CHUNK_TYPE
Defines the type of the chunk. For each
distinct chunk type a own type has to be
defined.
4
0x0004 CHUNK_SIZE
Size of the whole image chunck 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
Header
Image data
Chunk
Seite 21 von 72
0x0014 IMAGE_HEIGTH Image height in pixel 4
0x0018 PIXEL_FORMAT Pixel-Format 4
0x001C TIME_STAMP Timestamp in uS 4
0x0020 FRAME_COUNT Frame count according to algorithm output 4
0x0024 PIXEL_DATA
The pixel data in the given type and dimension
of the image.
Padded to 4-Byte boundary.
Seite 22 von 72
Available Chun types
Constant Value Description
USERDATA 0 undefined userdata with arbritrary content
RADIAL_DISTANCE_IMAGE 100
Each pixel of the distance matrix denotes the
ToF distance measured by the corresponding
pixel or group of pixels of the imager. The distance value is corrected by the camera's calibration, excluding effects caused by multipath
and multiple objects contributions (e.g. "flying
pixels"). Reference point is the optical center
of the camera inside the camera housing.
Invalid PMD pixels (e.g. due to saturation)
have a value of zero.
Data type: 16 bit unsigned integer (little endian)
Unit: millimetres
NORM_AMPLITUDE_IMAGE 101
Each pixel of the amplitude matrix denotes the
amount of modulated light (ie the light from the
camera's active illumination) which is reflected
by the appropriate object. Higher values indicate higher PMD signal strengths and thus a
lower amount of noise on the corresponding
distance measurements. The amplitude value
is directly derived from the PMD phase measurements without normalization to exposure
time. In double exposure mode, the lack of
normalization may lead (depending on the
choosen exposure times) to inhomogeneous
amplitude image impression, if the a certain
pixel is taken from the short exposure time and
some of its neighbors are not.
Invalid PMD pixels (e.g. due to saturation)
have an amplitude value of 0.
By the algorithm a float32 normalized Amplitude image is created. Its values range from
94.3 to 0.005, given the current (C3 sample)
minimal and maximal amplitude settings. To
have some room for improvement the scaling
should be done as follows:
Normalized Amplitude Image 16 Bit: IPUint16
Normalized Amplitude Image from algorithm :
IPfloat32
Conversion: IPUint16 = round(65535/100 *
Loading...