Skip to content

Sensors API

sensors

Nectar SDK - Sensors module.

DistanceFilter

Bases: Protocol

Stateful filter mapping a raw distance reading to a processed value.

A filter may suppress a reading entirely by returning None.

process 

process(raw_distance: float) -> Optional[float]

Process one raw reading and return the filtered distance.

reset 

reset() -> None

Clear internal state.

DistanceSensor

Bases: Protocol

One-shot distance sensor.

Implementations should be non-blocking: read returns the latest valid measurement available right now, or None if no fresh valid reading is ready (e.g. partial frame, bad checksum, low signal).

read 

read() -> Optional[float]

Return the latest distance in meters, or None if unavailable.

close 

close() -> None

Release any underlying resources (serial port, file handle, etc.).

TFLuna 

TFLuna(port: str, baudrate: int = 115200, timeout: float = 0.02, min_strength: int = 100)

Benewake TF-Luna serial driver.

Parameters:

Name Type Description Default
port str

Serial device path (e.g. "/dev/ttyUSB0").

 required
baudrate int

Default 115200 (TF-Luna factory setting).

 115200
timeout float

Serial read timeout in seconds. Small non-zero value avoids busy-polling while still keeping :meth:read snappy. Default 0.02.

 0.02
min_strength int

Minimum signal strength to accept a frame. Frames below this or equal to 0xFFFF are discarded per Benewake's data sheet. Default 100.

 100

read 

read() -> Optional[float]

Drain the serial buffer and return the latest valid distance in meters.

Returns None when no full valid frame is currently buffered

close 

close() -> None

Close the underlying serial port.

ObstacleMaskFilter 

ObstacleMaskFilter(obstacle_height_m: Optional[float] = None, *, max_change_m: float = 0.3, avg_window: int = 10, estimate_lock_s: float = 0.2, timeout_s: Optional[float] = 5.0)

Mask rangefinder samples while the beam is over an obstacle.

Parameters:

Name Type Description Default
obstacle_height_m float

Vertical thickness of the obstacle in meters. None (default) enables auto-estimation from the entry drop magnitude. A positive value locks the height to that constant.

 None
max_change_m float

Magnitude of sample-to-baseline drop that triggers entry, and the magnitude of recovery above entry_raw that triggers exit. Default 0.30 m (at 50 Hz this excludes any physically achievable descent rate).

 0.3
avg_window int

Number of recent samples averaged for the entry baseline. Default 10.

 10
estimate_lock_s float

Refinement window after entry during which entry_raw may be updated downward. After this elapses the height is frozen until exit. Ignored when obstacle_height_m is set. Default 0.2 s.

 0.2
timeout_s float

Maximum time to remain in the masked state before forcing a reset. None disables the safety. Default 5.0 s.

 5.0
Notes

The entry baseline is only updated outside the masked state, so a long masked period does not corrupt the average. While masked, raw samples are not pushed into the rolling window.

is_masking property 

is_masking: bool

Whether the filter is currently masking readings.

estimated_height_m property 

estimated_height_m: Optional[float]

Current obstacle-height estimate, or None outside the masked state.

process 

process(raw_distance: float) -> Optional[float]

Apply the mask to a raw reading.

Parameters:

Name Type Description Default
raw_distance float

Raw rangefinder reading in meters. None is not accepted; callers should skip invalid samples upstream.

 required

Returns:

Type Description
float

The filtered distance in meters.

reset 

reset() -> None

Clear all internal state.

RangefinderPublisher 

RangefinderPublisher(sensor: DistanceSensor, connection: MavlinkConnection, *, sensor_id: int = 0, sensor_type: int = MAV_DISTANCE_SENSOR_LASER, orientation: int = MAV_SENSOR_ROTATION_PITCH_270, min_distance_m: float = 0.05, max_distance_m: float = 8.0, covariance_cm: int = 0, rate_hz: float = 50.0, filter: Optional[DistanceFilter] = None)

Bridge a :class:DistanceSensor to MAVLink DISTANCE_SENSOR.

Parameters:

Name Type Description Default
sensor DistanceSensor

Source of raw distance readings in meters.

 required
connection MavlinkConnection

Open MAVLink endpoint to the FCU.

 required
sensor_id int

MAVLink sensor id (0-7). ArduPilot maps this to RNGFND<id+1>_*. Default 0.

 0
sensor_type int

MAVLink MAV_DISTANCE_SENSOR enum. Default LASER.

 MAV_DISTANCE_SENSOR_LASER
orientation int

MAVLink MAV_SENSOR_ORIENTATION enum. Default PITCH_270 (downward).

 MAV_SENSOR_ROTATION_PITCH_270
min_distance_m float

Minimum range the sensor can report, in meters. Default 0.05.

 0.05
max_distance_m float

Maximum range the sensor can report, in meters. Default 8.0.

 8.0
covariance_cm int

Measurement covariance hint in centimeters (0-254). 0 means "unknown / use ArduPilot defaults". Default 0.

 0
rate_hz float

Publishing rate. Default 50.

 50.0
filter DistanceFilter

Pre-publish filter. None means publish raw readings.

 None
Notes

A background thread is created on :meth:start. The thread sleeps on a :class:threading.Event, so :meth:stop is responsive.

is_running property 

is_running: bool

Whether the background loop is active.

start 

start() -> None

Start the background read/filter/publish loop.

stop 

stop(timeout: float = 2.0) -> None

Signal the loop to exit and join the thread.