Application /Product Knowledge
picoScan100: AI-Ready Integration Context

Article No: KA-10756
Version: 1.1
Subject to change without notice
A knowledge base designed to be injected into AI coding agents.
Related Products

This page contains an agent-consumable knowledge base for integrating SICK LiDAR sensors from the picoScan100 family. Copy the Markdown below into an AI coding assistant's context window to get guided, protocol-accurate integration support without external lookups. The document covers quick-start, all device capabilities, Compact format streaming, REST API authentication, WebSocket events, CoLa A/B, configuration endpoints, backup/restore, firmware update, and troubleshooting.
Raw knowledge base (Markdown) - copy into agent context
# picoScan100 Integration Knowledge for AI Agents

**Purpose:** Drop this document into an AI agent's context as a single-shot
reference. The agent can then guide integration work - device setup, data
streaming, configuration, safety zone programming, firmware updates - without
external lookups.

**Scope:** picoScan120 and picoScan150. Protocol-level facts and pseudocode
only; no language-specific syntax. Assumes latest firmware version and all
licenses are installed.

---

## Section 1 - Quick-Start

- **Factory IP address:** 192.168.0.1, subnet /24
- **Factory IP mode:** static (DHCP disabled by default)
- **Physical readiness indicator:** solid green LED = operational
- **Web configuration interface:** <http://192.168.0.1/> (Angular-based, no
  plug-in needed)
- **Default scan data port:** UDP 2115 (host-side receive)
- **Windows network note:** the host network interface used for sensor
  communication must be set to the "Private" profile. If it is "Public",
  incoming UDP packets are blocked by the Windows firewall. Use
  `Get-NetConnectionProfile` / `Set-NetConnectionProfile` in PowerShell to
  change it (run as Administrator).

---

## Section 2 - Device Capabilities

A new user with the device on their desk should read this section first. It
answers "what can this sensor actually do?" before diving into protocols.

### 2A - Scan Configuration

**Performance Profiles** (`PerformanceProfileNumber`) picoScan150 ships with 11
pre-defined profiles (0-10). Each profile is a tested combination of scan
frequency, angular resolution, and maximum measurable range. Selecting a profile
is the primary way to match the sensor to an application:

- High frequency profiles: fast-moving object detection, response time critical
- High resolution profiles: accurate geometry, edge/contour work
- Long-range profiles: sparse large-area monitoring (>20 m)

**Long Range Mode** (`EnableLongRangeMode`) Extends the maximum detection
distance by applying a distance scaling factor. The trade-off is reduced angular
resolution. Use for sparse large-area or perimeter monitoring where per-point
accuracy matters less than range.

**Sensitivity Mode** (`SensitivityMode`) Adjusts the detection threshold.
Lowering sensitivity prevents false "blooming" returns when the beam hits highly
retro-reflective surfaces (safety tape, reflectors). Raising it allows detection
of low-reflectance or distant targets.

**Standby / Auto-start** (`mStandby`, `AutoStartMeasure`) Standby stops the
motor entirely (zero power, no scanning). AutoStartMeasure, when enabled,
resumes measurement automatically after every power cycle without requiring an
explicit `mStartMeasure` call.

### 2B - Measurement Data Outputs

| Data stream                                       | Format                     | Default port | Notes                            |
| ------------------------------------------------- | -------------------------- | ------------ | -------------------------------- |
| 2D scan (distance + intensity)                    | Compact type 1, UDP or TCP | 2115         | Primary output; segmented frames |
| IMU (acceleration, angular velocity, orientation) | Compact type 2, UDP        | 7503         | Bosch BHI360 integrated          |
| Encoder position                                  | Compact type 4, UDP        | 7504         | External encoder                 |

Each stream is independently enabled and has its own destination IP/port
configuration.

### 2B-i - On-Device 3D Point Cloud (not streaming)

The scan merger is **not** a live data stream. It accumulates 2D scan frames
into a 3D point cloud on-board and stores the result as a PCD file on the
device. The file is retrieved via a one-shot REST download - there is no
continuous data push.

**Scan Merger** (`ScanMergerEnabled`, `ScanMergerSource`, `ScanMergeTrigger`)
Uses either the encoder angle or the IMU orientation as the rotation reference.
The result is stored as a PCD file on the device and downloaded via REST.

| Item      | Detail                               |
| --------- | ------------------------------------ |
| Format    | PCD file on-device                   |
| Retrieval | REST download (not a UDP/TCP stream) |

### 2C - On-Device Zone Detection

The device supports up to 48 independent evaluation groups. Each group is
independently typed, configured, activated, and readable via REST or digital
output pin.

**Field Evaluation - Zone Detection** (`EvaluationGroupType = 0`) Define a 2D
polygon zone (by uploading coordinates or via teach-in mode). On every scan the
device checks whether any measurement point falls inside the zone. Output per
zone: binary state (free = 0, occupied = 1). Result available via REST
(`FieldEvaluationResult`) and optionally wired to a digital output pin.

- Up to 20 zones simultaneously
- This is the on-device object detection function - zone entry/exit only; no
  moving-object tracking, no bounding boxes, no velocity estimation

> **Important:** There is no REST endpoint to _create_ a new evaluation group.
> `SetFieldEvaluationContour` can only _modify_ a group that already exists on
> the device. Before any REST-based zone management is possible, groups must be
> created by one of these two methods:
>
> 1. **Teach-in via UI (primary method)** - open SOPASair
>    (`http://<device-ip>/`) or SOPAS ET, draw the zone contour interactively,
>    and save.
> 2. **Parameter backup restore** - restore a `.json` backup that already
>    contains the desired groups (e.g. a template with 10 dummy contours). The
>    REST API can then overwrite contours and activate groups at runtime.
>
> Once groups exist on the device, `SetFieldEvaluationContour` /
> `ActivateEvaluationGroup` manage them via REST without touching the UI.

**Perpendicular Distance** (`EvaluationGroupType = 1`) Instead of a binary
in/out result, computes the perpendicular distance from scan points to the
boundary line of the configured zone. Outputs per zone: minimum distance,
maximum distance, and the 3D coordinates of the closest and farthest points.
Updated every scan. Read via REST (`perpendicularDistanceResult`) or via
WebSocket event push.

**Detection History** (internal ring buffer) A time-stamped log of zone state
transitions. Visible in the SOPASair web UI only. NOT accessible via the REST
API.

### 2D - Data Filters

| Filter                 | API key                        | What it does                                              |
| ---------------------- | ------------------------------ | --------------------------------------------------------- |
| Particle filter        | `LFPparticle`                  | Removes single-beam spike returns (dust, rain, insects).  |
| Interval filter        | `LFPintervalFilter`            | Keeps every Nth beam, discards the rest.                  |
| Moving average         | `LFPmovingAveragingFilter`     | Averages each beam's distance across N consecutive scans. |
| Echo selection         | `FREchoFilter`                 | Selects first/last/strongest echo on multi-return beams.  |
| Fog filter             | `MCSenseLevel`                 | Controls echo separation ability.                         |
| Angle range filter     | `LFPangleRangeFilter`          | Crops output to a defined angular window.                 |
| Radial distance filter | `LFPradialDistanceRangeFilter` | Min/max distance cutoff.                                  |
| Cubic area filter      | `LFPcubicareafilter`           | 3D bounding box; drops points outside.                    |

### 2E - Contamination Monitoring

7 sectors, per-sector enable, configurable strategy/threshold/cover type.

- `ContaminationData` - per-sector severity array (7 values)
- `ContaminationResult` - global warning/error flags
- `ContaminationConfig` - full configuration

### 2F - Digital I/O

Up to 6 configurable pins (InOut1-InOut6), each independently input or output.
Output sources: Device ready signal or a specific field evaluation zone result.

- `InputState`, `OutputState`, `PortState` - read state
- `SetOutput` - write an output pin
- `PortConfiguration` - full pin configuration

### 2G - Temperature Alarm

Configurable upper/lower thresholds.

- `CurrentTempDev` - live temperature (deg C)
- `temperatureAlarmStatus` - alarm state (boolean)
- `temperatureAlarmConfiguration` - threshold configuration

### 2H - Mounting and Coordinate System

- `SensorPosition` - x, y, z (mm), yaw, pitch, roll (degrees) stored on device
- `rosFrameId`, `rosParentFrameId`, `rosNamespace` - read by ROS 2 driver at
  startup

### 2I - Security and Connectivity

- HTTPS/TLS port 443; HTTP port 80 remains active unless disabled
- CoLa A/B: TCP ports 2111/2112; disable via `EtherAuxEnabled`
- All REST writes require challenge-response authentication
- Three user levels: Maintenance, Authorized Client, Service (only Service
  enabled by default)
- WebSocket event API: real-time push for zone results, temperature, device
  state, I/O, etc.

### 2J - Device Management

- Firmware update: REST file upload (.spk.signed)
- Parameter backup/restore: full config download/upload via REST
- Factory defaults, application defaults, soft reset, reboot: REST methods
- Find Me: POST /api/FindMe - blinks LEDs for 5 s
- `LFTchecksum` - four MD5 hashes for integrity verification
- Diagnosis dump: generate and download full diagnostic archive

### 2K - Time Synchronization

| Mode            | API key / value               | Notes                                       |
| --------------- | ----------------------------- | ------------------------------------------- |
| Off             | `TSCRole = 0`                 | Device uses internal clock only             |
| NTP client      | `TSCRole = 1`, `TSCTCSrvAddr` | Syncs to an NTP server on the network       |
| NTP server      | `TSCRole = 2`                 | Device acts as NTP source for others        |
| PTP (IEEE 1588) | Hardware-level                | Improves multi-sensor timestamp correlation |

- `LSPdatetime` - read current device date/time
- `LSPsetdatetime` - set date/time manually
- All scan segment timestamps originate from the device clock; accurate time
  sync is required for multi-sensor fusion or latency analysis.

---

## Section 3 - Device Discovery

Send a 24-byte UDP broadcast frame to 255.255.255.255:30718. All SICK AutoIP
devices on the subnet reply with their network configuration.

Request frame (24 bytes):

```txt
Offset  Size  Content
0       1     0x00 (start marker)
1       1     0x10 (command: scan request)
2       4     random 32-bit Request ID
6       4     sender IPv4 address
10      4     sender subnet mask
14      10    padding zeros
```

Response TLV tags (4-byte ASCII): | Tag | Field | Size | |---|---|---| | EIPa |
Device IP address | 4 bytes | | ENMa | Subnet mask | 4 bytes | | EDGa | Default
gateway | 4 bytes | | EDhc | DHCP flag (0=static, 1=DHCP) | 1 byte | | EMAC |
MAC address | 6 bytes |

Tag value starts 2 bytes after the start of the ASCII tag string.

Alternative: SOPAS ET

---

## Section 4 - RSSI / Intensity Scaling

Device generates 8-bit RSSI internally.

| Format             | Bit depth | Conversion                              |
| ------------------ | --------- | --------------------------------------- |
| Compact type 1     | 16-bit    | 16bit = (8bit / 255) \* 65535           |
| MSGPACK            | 16-bit    | 16bit = (8bit / 255) \* 65535           |
| LMDscandata (CoLa) | 8-bit     | no conversion; 254 = reflector detected |

In 16-bit output, low byte always equals high byte (e.g., 0xe6e6). This is
expected behavior.

---

## Section 5 - Compact Format Data Streaming

### 5.1 Transport

- UDP unicast (default): ScanDataEthSettings { Protocol, IPAddress, Port }
- UDP multicast: same API, multicast group address
- TCP: device connects as client to configured

### 5.2 Frame envelope

```txt
Offset  Size  Content
0       4     Magic: 0x02020202
4       4     Command ID / telegram type (little-endian)
8       4     Payload length
12      N     Payload
12+N    4     CRC32 (covers entire frame, little-endian)
```

Telegram types: 1=scan data, 2=IMU, 4=encoder

### 5.3 Type 1 scan data hierarchy

```txt
ScanData
  Module[]
    MetaData
      segmentIndex              -- 0-14 typical for picoScan100 family
      frameSequenceNumber       -- shared by all segments of one full scan
      distanceScalingFactor     -- multiply raw integer by this to get metres
      EchoContent (bitmask)     -- which echo fields are present
      BeamContent (bitmask)     -- which beam fields are present
    RowMetaData[]
      firstBeamAzimuth, lastBeamAzimuth, verticalAngle
      firstBeamTimestamp, lastBeamTimestamp
    Column[]
      Beam[]
        azimuth
        properties              -- bit 0=reflector, bit 1=blooming
        Echo[]
          distance              -- integer; multiply by distanceScalingFactor for metres
          intensity             -- 16-bit RSSI
```

Segmented streaming: 5 or 10 segments, depending on performance profile, per
full 276-degree frame. All segments share frameSequenceNumber; differ by
segmentIndex. Collect all segments before processing. Check EchoContent and
BeamContent bitmasks before reading optional fields.

### 5.4 MSGPACK format

Same semantics as Compact, MessagePack binary encoding. Select via
ScanDataFormat = 2.

### 5.5 Resources

- Kaitai .ksy definitions: <https://github.com/SICKAG/KataiStructDescriptions>
- Format specification PDF:
  <https://cdn.sick.com/media/docs/3/23/623/technical_information_data_format_description_en_im0104623.pdf>

---

## Section 6 - REST API

### 6.1 Base URL

```txt
http[s]://<device-ip>/api/<EndpointName>

GET  /api/<VariableName>
Response: { "header": { "status": 0, "message": "Ok" }, "data": { "<VariableName>": <value> } }
```

### 6.2 Challenge-response authentication (required for every POST)

```txt
1. POST /api/getChallenge  { "data": { "user": "<UserLevel>" } }
   Response: { nonce, opaque, realm, salt }

2. hash = SHA256( user + ":" + realm + ":" + SHA256(password) + ":" + nonce + ":" + salt + ":" + endpointName )
   (omit salt if absent)

3. POST /api/<VariableName>
   Header: { user, response: hash, nonce, opaque, realm }
   Body:   { "data": { "<VariableName>": <newValue> } }
```

Nonce changes per request - repeat step 1 before every POST.

Reference implementation (Python):
<https://github.com/SICKAG/sick_scan_rest_client>

### 6.3 User levels

| Level             | Default  |
| ----------------- | -------- |
| Maintenance       | Disabled |
| Authorized Client | Disabled |
| Service           | Enabled  |

### 6.4 OpenAPI specifications

- picoScan150: <https://www.sick.com/de/en/downloads/media/swp678507>
- picoScan120: <https://www.sick.com/de/en/downloads/media/swp684461>

### 6.5 Session token

POST /api/CreateSessionToken (challenge-response) -> { token, ttl } Use header
X-Session-Token: <token> on subsequent requests.

---

## Section 7 - WebSocket Event API (firmware 2.3.0+)

Endpoint: `ws://<device-ip>/apievents` — requires `permessage-deflate`
compression extension.

```json
// Subscribe
{ "type": "register",     "event": "<EventName>", "clientId": 1 }

// Confirmation
{ "type": "confirmation", "event": "<EventName>", "clientId": 1 }

// Incoming event
{ "type": "event",        "event": "<EventName>", "data": { ... } }

// Error
{ "type": "error",        "event": "<EventName>", "message": "..." }

// Deregister
{ "type": "deregister",   "event": "<EventName>", "clientId": 1 }
```

Wait 200 ms between consecutive register calls.

| Event                         | Description                                      |
| ----------------------------- | ------------------------------------------------ |
| `DeviceStatus`                | Device operational state (9 possible values)     |
| `SCdevicestate`               | Safety controller state                          |
| `InputState`                  | State of all digital input pins                  |
| `OutputState`                 | State of all digital output pins                 |
| `PortState`                   | Port-level state (preferred over OutputState)    |
| `ContaminationData`           | Per-sector contamination severity (7 sectors)    |
| `ContaminationResult`         | Global contamination warning/error flags         |
| `InertialMeasurementUnit`     | Live IMU data                                    |
| `FieldEvaluationResult`       | Zone detection results for all evaluation groups |
| `UpdateState`                 | Firmware update progress                         |
| `perpendicularDistanceResult` | Min/max perpendicular distance per active zone   |
| `temperatureAlarmStatus`      | Temperature alarm state                          |
| `CurrentTempDev`              | Live temperature in deg C                        |
| `LSPdatetime`                 | Current device date and time                     |

Reconnect strategy: detect close event, wait, reconnect, re-register all
subscriptions.

---

## Section 8 - HTTPS / TLS

- Port 443 (HTTP 80 stays active unless disabled)
- Mutual TLS NOT supported (server-side certificate only)

Upload: POST /api/setCertificateBundle (multipart form-data: certificate_bundle
PEM + private_key PEM, Service auth) Status: GET /api/httpsStatus Remove: POST
/api/removeCertificateBundle (Service auth)

On Windows: OS certificate store is used automatically if CA is already trusted.

---

## Section 9 - CoLa A/B Protocol

Enable: POST /api/EtherAuxEnabled (or via web UI)

CoLa A: TCP 2111, ASCII Frame: STX + "s" + CommandType + " " + VariableName + "
" + [Value] + ETX Commands: RN (read), WN (write), MN (method), EA (event/data
stream)

CoLa B: TCP 2112, binary 0xFEFEFEFE + 4-byte length + command bytes + CRC

LMDscandata: one full 270-degree scan per frame (not segmented); 8-bit RSSI;
ASCII values

CoLa password hash:

1. Encode password as ISO 8859-15 bytes
2. MD5 of those bytes -> 16 bytes
3. Split into four 4-byte groups; XOR each group to one byte
4. Concatenate 4 bytes as big-endian 32-bit integer
5. sMN SetPassword <userLevelId> <hash>

All variables and methods available via the REST API are also accessible via
CoLa A or CoLa B. The full telegram syntax and variable names are documented in
the device operating instructions.

---

## Section 10 - Configuration Endpoint Reference

All GETs: no auth. All POSTs: challenge-response. All writes: RAM only until
WriteEeprom.

General: GET/POST LocationName, FindMe (POST), RebootDevice (POST), SoftReset
(POST), LoadFactoryDefaults (POST), LoadApplicationDefaults (POST), WriteEeprom
(POST)

Scan: mStartMeasure (POST), mStopMeasure (POST), mStandby (POST),
AutoStartMeasure, PerformanceProfileNumber (picoScan150 only), ScanConfig,
EnableLongRangeMode, SensitivityMode

Data output: ScanDataEnable, ScanDataEthSettings, ScanDataFormat (1=Compact
2=MSGPACK), ImuDataEnable, ImuDataEthSettings, EncoderDataEnable,
EncoderDataEthSettings, EtherCoLaScanMode

Filters: LFPparticle, LFPintervalFilter, LFPmovingAveragingFilter, FREchoFilter,
MCSenseLevel, LFPangleRangeFilter, LFPradialDistanceRangeFilter,
LFPcubicareafilter

Field evaluation: FieldEvaluationResult, FieldEvaluationGroupState,
EvaluationGroupType, ActivateEvaluationGroup (POST), SetFieldEvaluationContour
(POST), GetFieldEvaluationContour (POST), StartTeachIn (POST), StopTeachIn
(POST), perpendicularDistanceResult, EnableDetectionHistory, EvaluationsToLog,
ResetDetectionHistory (POST)

Contamination: ContaminationData, ContaminationResult, ContaminationConfig

I/O and encoder: InputState, OutputState, PortState, PortConfiguration,
SetOutput (POST), EncSetting, EncResolution, ActualEncPosition1Enable

Network: EtherIPAddress, EtherAddressingMode (0=static 1=DHCP), EthernetUpdate
(POST), EtherAuxEnabled (POST)

Time: TSCRole (0=off 1=NTP client 2=NTP server), TSCTCSrvAddr, LSPdatetime,
LSPsetdatetime (POST)

Mounting: SensorPosition { x, y, z, yaw, pitch, roll }, rosFrameId,
rosParentFrameId, rosNamespace

Diagnostics: DeviceStatus, CurrentTempDev, temperatureAlarmConfiguration,
temperatureAlarmStatus, OpHours, LFTchecksum { MD5SumOK, MD5LinuxRoot, MD5App,
MD5Calibration, MD5Parameters }, DoDiagnosisDump (POST), GetDiagnosisDumpInfo

Security: httpsStatus, setCertificateBundle (POST), removeCertificateBundle
(POST), getChallenge (POST), EnableUserLevel (POST), changePassword (POST)

---

## Section 11 - Parameter Backup and Restore

1. POST /api/CreateSessionToken (challenge-response) -> token
2. POST /api/CreateParameterBackup X-Session-Token: <token>
3. GET /api/parameterbackup X-Session-Token: <token> -> save file
4. PUT /api/parameterbackup X-Session-Token: <token>, body = file
5. POST /api/RestoreParameterBackup X-Session-Token: <token> -> device reboots

---

## Section 12 - Firmware Update

1. POST /api/CreateSessionToken (challenge-response) -> token
2. POST /api/RunFirmwareUpdate multipart/form-data, field "updatePackage" =
   .spk.signed
3. GET /api/UpdateState every 2-5 s { progress: 0-100, state:
   0=idle/1=in-progress/2=complete/3=error }
4. Device reboots automatically on state 2 (allow 2-5 min total)
5. GET /api/FirmwareVersion to verify

Keep UDP socket open during firmware update and reboot.

---

## Section 13 - Integrity Verification

GET /api/LFTchecksum MD5SumOK - overall pass/fail MD5LinuxRoot - OS filesystem
MD5App - application firmware MD5Calibration - factory calibration (should never
change in field) MD5Parameters - current config (changes on every write, even
before WriteEeprom)

Take before/after snapshots to identify which subsystem changed.

---

## Section 14 - Integration Approaches

| Approach              | Language      | Link                                                       |
| --------------------- | ------------- | ---------------------------------------------------------- |
| sick_perception_sdk   | C++17         | <https://github.com/SICKAG/sick_perception_sdk>            |
| ScanSegmentAPI        | Python        | <https://github.com/SICKAG/ScanSegmentAPI>                 |
| ScanSegmentDecoding   | Python        | <https://github.com/SICKAG/ScanSegmentDecoding>            |
| ScanSegmentAPICSharp  | C#            | <https://github.com/SICKAG/ScanSegmentAPICSharp>           |
| sick_scan_rest_client | Python        | <https://github.com/SICKAG/sick_scan_rest_client>          |
| sick_scan_xd          | ROS 2         | <https://github.com/SICKAG/sick_scan_xd>                   |
| Kaitai Struct         | Any           | <https://github.com/SICKAG/KataiStructDescriptions>        |
| SOPAS ET              | GUI (Windows) | <https://www.sick.com/search?text=SOPAS+ET>                |
| SOPASair              | Web browser   | `http://<device-ip>/` — built-in web UI, no install needed |

---

## Section 15 - ROS Integration

Two distinct approaches exist for ROS integration. Choose based on CPU budget
and ROS version requirements.

### 15A - Native ROS 2 (DDS publisher on device)

The device can act as a native ROS 2 DDS participant and publish scan data
directly onto the ROS 2 network without any intermediary host process.

| Item          | Detail                                                                                     |
| ------------- | ------------------------------------------------------------------------------------------ |
| ROS version   | ROS 2 only                                                                                 |
| Transport     | DDS (device publishes directly onto the ROS 2 domain)                                      |
| Topics        | `sensor_msgs/PointCloud2`, `sensor_msgs/LaserScan`                                         |
| CPU on host   | Minimal - no conversion process needed on host                                             |
| Configuration | Set `rosFrameId`, `rosParentFrameId`, `rosNamespace` via REST; enable DDS output on device |
| Prerequisite  | ROS 2 domain ID must match; DDS discovery must reach the device's network interface        |

This is the lowest-latency, lowest-host-CPU approach. The device handles
segmentation, assembly, and message serialization internally.

### 15B - sick_scan_xd driver (host-side conversion)

`sick_scan_xd` is a ROS 2 driver that runs as a node on the host. It receives
the raw Compact type 1 UDP stream, assembles segments into full frames, converts
distance/intensity data to ROS message types, and publishes them.

| Item          | Detail                                                    |
| ------------- | --------------------------------------------------------- |
| ROS version   | ROS 2 only                                                |
| Transport     | Compact type 1 UDP received on host; driver converts      |
| Topics        | `sensor_msgs/PointCloud2`, `sensor_msgs/LaserScan`, IMU   |
| CPU on host   | Higher - segment assembly and format conversion on host   |
| Configuration | Driver config file sets device IP, scan port, topic names |
| Repository    | <https://github.com/SICKAG/sick_scan_xd>                  |

---

## Section 16 - Common Integration Patterns (pseudocode)

### 15.1 Start scan data stream

1. POST /api/ScanDataEthSettings { destIpAddress, destPort: 2115,
   transmissionType: "UDP" }
2. POST /api/ScanDataEnable { enable: true }
3. POST /api/WriteEeprom
4. Bind UDP socket on host at port 2115
5. Receive Compact frames; check magic 0x02020202; decode type 1
6. Collect segments by frameSequenceNumber; combine all 15 into one full frame

### 15.2 Switch performance profile (picoScan150 only)

1. POST /api/PerformanceProfileNumber { profileNumber: 0-10 }
2. POST /api/WriteEeprom

### 15.3 Configure and activate a zone

> **Prerequisite:** Evaluation groups cannot be created via REST. The group
> referenced by `evaluationId` must already exist on the device - created by
> teach-in via the SOPASair UI or by restoring a parameter backup that contains
> pre-configured groups. Only then can the steps below modify and activate it.

1. POST /api/SetFieldEvaluationContour { evaluationId: 1-48, contour:
   [{x,y},...] }
2. POST /api/EvaluationGroupType { groupId: 1-48, type: 0 }
3. POST /api/ActivateEvaluationGroup { groupId: 1-48, activate: true }
4. POST /api/WriteEeprom
5. Poll GET /api/FieldEvaluationResult OR subscribe WebSocket
   "FieldEvaluationResult"

### 15.4 Teach-in a zone

1. Clear the area, POST /api/StartTeachIn
2. Hold environment static during teach-in
3. POST /api/StopTeachIn

### 15.5 3D point cloud with encoder axis

1. Configure encoder: EncSetting, ActualEncPosition1Enable, EncoderDataEnable,
   EncoderDataEthSettings
2. POST /api/WriteEeprom
3. Receive type 1 (scan) + type 4 (encoder) on same socket
4. Correlate by frameSequenceNumber; rotate 2D point (x,y) by encoder angle
   theta: x*3d = x * cos(theta), y*3d = y, z_3d = x * sin(theta)
5. Accumulate into 3D point cloud

### 15.6 Subscribe to WebSocket events

1. Connect ws://<device-ip>/apievents (permessage-deflate required)
2. For each event: send register message, wait 200 ms
3. Dispatch on message type; on close: reconnect after 2-5 s, re-register all

---

## Section 17 - Troubleshooting

| Symptom                                    | Cause                                        | Fix                                                                      |
| ------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------ | ----------- |
| No scan data arriving                      | Windows "Public" network profile or firewall | Set NIC to Private; add UDP inbound rule for port 2115                   |
| First recv() after reconnect returns error | ICMP port-unreachable buffered               | Keep socket open across reboot; apply SIO_UDP_CONNRESET ioctl on Windows |
| POST returns 401 / Access Denied           | Stale nonce or wrong user level              | Re-run challenge-response; verify user level enabled                     |
| POST returns 429                           | REST rate limit hit                          | Exponential back-off                                                     |
| Missing scan segments                      | UDP packet loss                              | Increase NIC buffer; consider TCP transport                              |
| Config lost after reboot                   | WriteEeprom not called                       | Always POST /api/WriteEeprom after changes                               |
| Field evaluation zone always state 0       | Zone not activated                           | POST /api/ActivateEvaluationGroup { activate: true }                     |
| WebSocket events stop                      | Connection dropped                           | Detect close; reconnect after 2-5 s; re-register                         |
| Device not found                           | Unknown IP                                   | Use AutoIP broadcast discovery (Section 3) or SOPAS ET                   |
| LMDscandata not streaming                  | EtherAuxEnabled not set                      | POST /api/EtherAuxEnabled or enable via web UI                           |
| HTTPS refused                              | No certificate uploaded                      | POST /api/setCertificateBundle (Service auth)                            |
Keywords:
picoScan100, Compact format, REST API, WebSocket events, CoLa A/B, UDP streaming, field evaluation zones, firmware update, challenge-response authentication, device discovery
Create request
picoScan100: AI-Ready Integration Context

Related Products

Table of Contents

Was this article helpful?

picoScan100: AI-Ready Integration Context

Related Products

Table of Contents

Thanks for your feedback!

Was this article helpful?
