SICK Telegram listing Operating instructions

Brand: SICK

Model: Telegram listing

Type: Operating instructions

T E C H N I C A L I N F O R M A T I O N

Telegram Listing LiDAR-LOC

LiDAR Localization Software

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

Product described

LiDAR-LOC with localization controller and 2D LiDAR sensor

Manufacturer

SICK AG

Erwin-Sick-Str. 1

79183 Waldkirch

Germany

Legal notes

This work is protected by copyright. The associated rights are reserved by SICK AG. Reproduction of this docu-

ment or parts of this document is only permissible within the limits of the legal provisions of copyright law. Any

modification, abridgment, or translation of this document is prohibited without the express written permission

of SICK AG.

The trademarks mentioned in this document are the property of their respective owners.

Original document

This document is an original document of SICK AG.

About this document 
8024818 / 19NW / 2020-10-19 | SICK   TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC 
3
 
Subject to change without notice 
Contents 
About this document ................................................................................................................ 5 
1  Function of this document ............................................................................................................... 5 
LiDAR-LOC CoLa telegrams ..................................................................................................... 6 
1  Example Start Sequence .................................................................................................................. 6 
2  Switching states ................................................................................................................................ 8 
2.1  Command: IsSystemReady .......................................................................................................... 8 
2.2  Command: LocState ...................................................................................................................... 9 
2.3  Command: LocStartLocalizing .................................................................................................. 10 
2.4  Command: LocStop .................................................................................................................... 11 
2.5  Command: LocStopAndSave .................................................................................................... 12 
3  Basic configuration ......................................................................................................................... 13 
3.1  Command: DevSetLidarConfig.................................................................................................. 13 
3.2  Command: DevSetIMUActive .................................................................................................... 15 
3.3  Command: LocSetMap ............................................................................................................... 16 
3.4  Command: LocInitializePose ..................................................................................................... 17 
3.5  Command: LocSetPose .............................................................................................................. 18 
3.6  Command: LocForceUpdate ...................................................................................................... 19 
3.7  Command: LocSetReflectorsForSupportActive ...................................................................... 20 
3.8  Command: LocSetOdometryActive .......................................................................................... 21 
3.9  Command: LocSetOdometryPort ............................................................................................. 22 
3.10  Command: LocSetRestrictYMotion .......................................................................................... 23 
3.11  Command: LocSetAutoStartActive ........................................................................................... 24 
3.12  Command: LocAutoStartSavePose .......................................................................................... 25 
3.13  Command: LocSetAutoStartSavePoseInterval ....................................................................... 26 
3.14  Command: SavePermanent ...................................................................................................... 27 
3.15  Command: LocRequestTimestamp ......................................................................................... 28 
3.16  Command: LocSetRingBufferRecordingActive ...................................................................... 29 
3.17  Command: LocSaveRingBufferRecording............................................................................... 30 
4  Result Output Configuration .......................................................................................................... 31 
4.1  Command: LocSetResultPort .................................................................................................... 31 
4.2  Command: LocSetResultMode ................................................................................................. 32 
4.3  Command: LocSetResultPoseEnabled .................................................................................... 33 
4.4  Command: LocSetResultEndianness ....................................................................................... 34 
4.5  Command: LocSetResultPoseInterval ..................................................................................... 35 
4.6  Command: LocRequestResultData .......................................................................................... 36 
5  Debugging ........................................................................................................................................ 37 
5.1  Command: GetSoftwareVersion ............................................................................................... 37 
5.2  Command: DevGetLidarState ................................................................................................... 38 
5.3  Command: LocMapState ........................................................................................................... 39 
5.4  Command: LocMap..................................................................................................................... 40 

1 About this document

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.5.5 Command: LocResultState ....................................................................................................... 41

2.5.6 Command: LocResultPort .......................................................................................................... 42

2.5.7 Command: LocResultMode ....................................................................................................... 43

2.5.8 Command: LocResultEndianness ............................................................................................ 44

2.5.9 Command: LocOdometryPort ................................................................................................... 45

2.5.10 Command: LocAutoStartActive................................................................................................. 46

2.5.11 Command: LocAutoStartSavePoseInterval ............................................................................ 47

2.5.12 Command: LocRingBufferRecordingActive ............................................................................ 48

1 About this document

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

1 About this document

1.1 Function of this document

This document lists the telegrams to communicate with LiDAR-LOC. The full operating instructions stated

below is explicitly required for the use of LIDAR-LOC:

 Operating instructions (8025192)

 Hardware Integration (8025193)

Descriptions of the commands, the parameters and the expected response after sending a telegram with

the compact command language CoLa-A (Command Language ASCII) are described here.

Telegrams, which are part of the SICK LiDAR Localization ROS driver, are marked with the following sign:



The full description of the ROS driver can be found here:

 https://github.com/SICKAG/sick_lidar_localization

Note

Some commands may change during SICK development processes. Please always use the lat-

est version of the “Telegram Listing” document.

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2 LiDAR-LOC CoLa telegrams

2.1 Example Start Sequence

The simplified start sequence (Figure 1) can be used if the localization system was previously configured

via SOPASair or CoLa Methods (sMN DevSetLidarConfig, sMN LocSetMap and sMN SavePermanent).

Changes of CoLa Methods sMN DevSetLidarConfig and sMN LocSetMap are only persistent after calling

sMN SavePermanent.

Figure 1: Simplified start sequence (CoLa commands and results are written in blue.)

Start

Check if System Ready

sMN IsSystemReady

Check LocState

sRN LocState

BOOTING

IDLE

Initialize Pose

sMN LocInitializePose

Initialization

Finished

True

Ack ErrorFalse

LOCALIZING

Auto Start

Delay

Error or False

Delay

Start Localization

sMN LocStartLocalizing

True

Ack ErrorFalse

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

The advanced start sequence (Figure 2) can be used if the LiDAR sensor of the localization system were

previously configured via SOPASair or CoLa Methods, but the map needs to be changed after start-up.

If you switch maps during operation, SICK recommends you to check the correct map is loaded. Request

the name of the map that is currently loaded by using the CoLa command sRN LocMap.

Figure 2: Advanced start sequence (CoLa commands and results are written in blue, external

checkings are written in green)

Start

Check if System Ready

sMN IsSystemReady

Check LocState

sRN LocState

BOOTING

Check Map State

sRN LocMapState

IDLE

Check Map Name

sRN LocMap

MAP_NAME == Expected

True

Start Localization

sMN LocStartLocalizing

Initialization

Finished

True

Load Map

sMN LocSetMap

False

True, True

Ack Error

False

Configure LiDAR(s)

sMN DevSetLidarConfig

True, False

False, False

True, False

False, False

Check Map Name

sRN LocMap

MAP_NAME == Expected

LOCALIZING

True

False

Stop Localization

sMN LocStop

True

Ack Error

False

Auto Start

Delay

Error or False

Delay

True, True

Initialize Pose

sMN LocInitilaizePose

Ack ErrorFalse

True

Start Localization

sMN LocStartLocalizing

Ack ErrorFalse

True

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.2 Switching states

2.2.1 Command: IsSystemReady

Checks if the localization controller is booted and ready to process CoLa-A commands. An error code or a

false return value means that the localization controller is still booting and loading LiDAR-LOC.

Request Write

Telegram syntax: sMN IsSystemReady

Telegram part

Description

Type

Range/Value

Command type

Method by name

String

sMN

Command

String

IsSystemReady

Example:

Check if the system is ready.

Telegram:

sMN IsSystemReady

Response

Telegram syntax: sAN IsSystemReady

Telegram part

Description

Type

Range/Value

Command type

Response (Method by name)

String

sAN

Command

String

IsSystemReady

State

The system is ready for COLA communication.

Bool_1

0 false: Localization controller

is booting or LiDAR-LOC is

1 true: Localization controller

is ready for CoLa-A com-

mands

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.2.2 Command: LocState

Read the current state of the localization.

Request Write

Telegram syntax: sRN LocState

Telegram part

Description

Type

Range/Value

Command type

Read variable by name

String

sRN

Command

String

LocState

Example:

Read localization state.

sRN LocState

Response

Telegram syntax: sRA LocState

Telegram part

Description

Type

Range/Value

Command type

Response (Read variable by name)

String

sRA

Command

String

LocState

State

Localization state

Enum

0 (BOOTING)

1 (IDLE)

2 (LOCALIZING)

3 (DEMO_MAPPING)

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.2.3 Command: LocStartLocalizing

If all prerequisites are met, start the localization.

Request Write

Telegram syntax: sMN LocStartLocalizing

Telegram part

Description

Type

Range/Value

Command type

Method by name

String

sMN

Command

String

LocStartLocalizing

Example:

If all prerequisites are met, start the localization.

sMN LocStartLocalizing

Response

Telegram syntax: sAN LocStartLocalizing

Telegram part

Description

Type

Range/Value

Command type

Response (Method by name)

String

sAN

Command

String

LocStartLocalizing

Result

The system started localizing.

Bool_1

0 failed

1 success

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.2.4 Command: LocStop

Stop the localization or the demo mapping and return to IDLE state.

Request Write

Telegram syntax: sMN LocStop

Telegram part

Description

Type

Range/Value

Command type

Method by name

String

sMN

Command

String

LocStop

Example:

Stop the localization or the demo mapping.

sMN LocStop

Response

Telegram syntax: sAN LocStop

Telegram part

Description

Type

Range/Value

Command type

Response (Method by name)

String

sAN

Command

String

LocStop

Result

The localization or demo mapping stopped.

Bool_1

0 failed

1 success

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.2.5 Command: LocStopAndSave

Note

This function is deprecated.

Please, use the new automatic start functions LocSetAutoStartActive and either LocAuto-

StartSavePose or LocSetAutoStartSavePoseInterval.

Stop the localization and return to IDLE state. The current pose and map are saved for the next system

start. The system automatically goes into LOCALIZING state after restart.

Request Write

Telegram syntax: sMN LocStopAndSave

Telegram part

Description

Type

Range/Value

Command type

Method by name

String

sMN

Command

String

LocStopAndSave

Example:

Stop the localization and save before restart.

sMN LocStopAndSave

Response

Telegram syntax: sAN LocStopAndSave

Telegram part

Description

Type

Range/Value

Command type

Response (Method by name)

String

sAN

Command

String

LocStopAndSave

Result

The localization stopped and settings are

saved before restart.

Bool_1

0 failed

1 success

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.3 Basic configuration

2.3.1 Command: DevSetLidarConfig

Configure a 2D LiDAR sensor.

Request Write

Telegram syntax: sMN DevSetLidarConfig

Telegram part

Description

Type

Range/Value

Command type

Method by name

String

sMN

Command

String

DevSetLidarConfig

index

Index of the sensor you want to configure.

UInt_8

[0,1]

minRange

Beams with a range that is lower than this

distance will be discarded.

UInt_32

[mm]

maxRange

Beams with a range that is greater than this

distance will be discarded.

UInt_32

[mm]

minAngle

Beams with an angle that is lower than this

threshold will be discarded.

UInt_32

[-180 000,180 000] [mdeg]

maxAngle

Beams with an angle that is greater than

this threshold will be discarded.

UInt_32

[-180 000,180 000] [mdeg]

X position relative to vehicle coordinate sys-

tem.

UInt_32

[-50 000,50 000] [mm]

Y position relative to vehicle coordinate sys-

tem.

UInt_32

[-50 000,50 000] [mm]

yaw

Yaw angle relative to vehicle coordinate sys-

tem.

UInt_32

[-180 000,180 000] [mdeg]

upsideDown

Indicates if the sensor is mounted upside-

down.

Bool_1

0 false

1 true

IP address of the sensor. Must be in the

same subnet as the port of the localization

controller to which the sensor is connected.

String

Max length = 15

Port

CoLa-A port of the sensor that is used for

communication. This is usually 2111 or

2122.

UInt_16

[0, 65 535]

Interface Type

The interface type for the connection be-

tween LiDAR-LOC and the sensor.

Enum

0 TCP

Reserved

Reserved field set to 0

UInt_8

active

This sensor is used for localization. The sen-

sor with the index 0 always must be 1 (true).

Bool_1

0 false

1 true

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

Example:

Configure first sensor with the following parameters:

 LiDAR index: 0

 min range: 0.3 m

 max range: 100 m

 min angle: -180 deg

 max angle: 180 deg

 mounting pose x: 1 m

 mounting pose y: -0.3 m

 mounting pose yaw: -45 deg

 mounting pose upside down: false

 IP: 192.168.0.30

 port: 2122

 interface type: TCP

 Reserved: 0

 active: true

sMN DevSetLidarConfig +0 +300 +100000 -180000 +180000

+1000 -300 -45000 0 +12 192.168.0.30 +2122 0 0 1

The prefix of the string with the IP address is the length of the string, in this case 12 characters.

Response

Telegram syntax: sAN DevSetLidarConfig

Telegram part

Description

Type

Range/Value

Command type

Response (Method by name)

String

sAN

Command

String

DevSetLidarConfig

Set Result

The arguments were valid and have been

configured.

Bool_1

0 failed

1 success

Executed

Result

The sensor driver started and received data.

Failed could mean the sensor is under the

specified IP address not reachable.

Bool_1

0 failed

1 success

Example:

Value description

 Set result: 1

 Executed result: 0 (e.g. under the specified IP address no sensor could be reached)

Response:

sAN DevSetLidarConfig 1 0

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.3.2 Command: DevSetIMUActive

Enable or disable the support of the SIM10xx internal IMU to enhance the robustness of the contour local-

ization algorithm.

IMPORTANT

This configuration should only be used if both, the sensor and the controller, are rigidly mounted

to a vehicle and not for demo cases.

Request Write

Telegram syntax: sMN DevSetIMUActive

part

Description

Type

Range/Value

Command

type

Method by name

String

sMN

Command

String

DevSetIMUActive

State

The localization uses the IMU for en-

hanced robustness.

Bool_1

0 false

1 true

Example:

Set the IMU for support active.

sMN DevSetIMUActive 1

Response

Telegram syntax: sAN DevSetIMUActive

part

Description

Type

Range/Value

Command

type

Response (Method by name)

String

sAN

Command

String

DevSetIMUActive

Executed

Result

The IMU configuration has been set.

Bool_1

0 failed

1 success

Example:

The IMU support has been set according to the request.

sAN DevSetIMUActive 1

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.3.3 Command: LocSetMap

Load a map.

Request Write

Telegram syntax: sMN LocSetMap

Telegram part

Description

Type

Range/Value

Command type

Method by name

String

sMN

Command

String

LocSetMap

mapFileName

The file name of the map that you want to

load.

String

Max length 255

Example:

Load a map with the following parameters:

 Map file name: our_hall.smap

sMN LocSetMap +13 our_hall.smap

The prefix of the string with the map file name is the length, in this case 13 characters.

Response

Telegram syntax: sAN LocSetMap

Telegram part

Description

Type

Range/Value

Command type

Response (Method by name)

String

sAN

Command

String

LocSetMap

Set Result

The arguments were valid and have been

configured.

Bool_1

0 failed

1 success

Executed

Result

The map is loaded.

Bool_1

0 failed

1 success

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.3.4 Command: LocInitializePose

Sets the initial pose and automatically adjust the pose to match the measured scan data in the loaded

map. LocInitializePose is a combined command of LocSetPose and LocForceUpdate.

Note

The localization has to be started already with LocStartLocalizing to use this telegram.

Request Write

Telegram syntax: sMN LocInitializePose

Telegram part

Description

Type

Range/Value

Command type

Method by name

String

sMN

Command

String

LocInitializePose

Pose

X coordinate

Int_32

[mm]

Y coordinate

Int_32

[mm]

Yaw Angle

Int_32

[-180 000,180 000] [mdeg]

Uncertainty

Translation Uncertainty [mm]

The rotational uncertainty is fixed to ± 10 deg.

UInt_16

[300, 5 000] [mm]

Example:

Set the pose with the following parameters:

 X coordinate: 10.3 m

 Y coordinate: -5.2 m

 Yaw Angle: 30 deg

 Translation Uncertainty: 1 m

sMN LocInitializePose +10300 -5200 +30000 +1000

Response

Telegram syntax: sAN LocInitializePose

Telegram part

Description

Type

Range/Value

Command type

Response (Method by name)

String

sAN

Command

String

LocInitializePose

Result

The initial pose is set and the measured

scans could be matched against the map. A

failure reasons is, for example, a pose qual-

ity below 80% after several automatic unsuc-

cessful matches.

Bool_1

0 failed

1 success

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.3.5 Command: LocSetPose

Initialize the vehicle pose of the localization.

Request Write

Telegram syntax: sMN LocSetPose

Telegram part

Description

Type

Range/Value

Command type

Method by name

String

sMN

Command

String

LocSetPose

Pose

X coordinate

Int_32

[mm]

Y coordinate

Int_32

[mm]

Yaw Angle

Int_32

[-180 000,180 000] [mdeg]

Uncertainty

Translation Uncertainty [mm]

The rotational uncertainty is fixed to ± 10 deg.

UInt_16

[300, 5 000] [mm]

Example:

Set the pose with the following parameters:

 X coordinate: 10.3 m

 Y coordinate: -5.2 m

 Yaw Angle: 30 deg

 Translation Uncertainty: 1 m

sMN LocSetPose +10300 -5200 +30000 +1000

Response

Telegram syntax: sAN LocSetPose

Telegram part

Description

Type

Range/Value

Command type

Response (Method by name)

String

sAN

Command

String

LocSetPose

Result

The initial pose is set.

Bool_1

0 failed

1 success

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.3.6 Command: LocForceUpdate

Forces an update of the localization.

The preferred solution to improve the pose quality, is to slightly rotate the vehicle on the spot or move the

vehicle around the area by up to 5 meters.

Note

Use the manual update cautiously. The vehicle may localize in a wrong position.

Request Write

Telegram syntax: sMN LocForceUpdate

Telegram part

Description

Type

Range/Value

Command type

Method by name

String

sMN

Command

String

LocForceUpdate

Example:

sMN LocForceUpdate

Response

Telegram syntax: sAN LocForceUpdate

Telegram part

Description

Type

Range/Value

Command type

Response (Method by name)

String

sAN

Command

String

LocForceUpdate

Result

The localization is updated

Bool_1

0 failed

1 success

2 LiDAR-LOC CoLa telegrams

8024818 / 19NW / 2020-10-19 | SICK TECHNICAL INFORMATION | TELEGRAM LISTING LIDAR-LOC

Subject to change without notice

2.3.7 Command: LocSetReflectorsForSupportActive

Enable or disable the mapped reflectors for localization to enhance the robustness of the contour localiza-

tion algorithm.

Request Write

Telegram syntax: sMN LocSetReflectorsForSupportActive

part

Description

Type

Range/Value

Command

type

Method by name

String

sMN

Command

String

LocSetReflectorsForSupportActive

State

The localization uses the mapped re-

flectors.

Bool_1

0 false

1 true

Example:

Set the reflectors for support active.

sMN LocSetReflectorsForSupportActive 1

Response

Telegram syntax: sAN LocSetReflectorsForSupportActive

part

Description

Type

Range/Value

Command

type

Response (Method by name)

String

sAN

Command

String

LocSetReflectorsForSupportActive

Result

The reflector configuration has been

set.

Bool_1

0 failed

1 success

Example:

The reflector configuration has been set..

sAN LocSetReflectorsForSupportActive 1

Page is loading ...

SICK Telegram listing Operating instructions

SICK Telegram listing Operating instructions

SICK Telegram listing Operating instructions

Related papers

Other documents