Welcome to hokuyolx’s documentation!¶

This module aims to implement communication protocol with Hokuyo laser rangefinder scaners, specifically with the following models: UST-10LX, UST-20LX, UST-30LX. It was tested only with UST-10LX but should work with others as well. For protocol specifications please refer to the following documents:

Usage example:

>>> from hokuyolx import HokuyoLX
>>> laser = HokuyoLX()
>>> timestamp, scan = laser.get_dist() # Single measurment mode
>>> # Continous measurment mode
>>> for timestamp, scan in laser.iter_dist(10):
...     print(timestamp)

For further information please refer to HokuyoLX class documentation

Installation¶

You can install hokuyolx using pip:

$ sudo pip install hokuyolx

Or for Python 3:

$ sudo pip3 install hokuyolx

Module contents¶

class hokuyolx.HokuyoLX(activate=True, info=True, tsync=True, addr=None, buf=512, timeout=5, time_tolerance=300, logger=None, convert_time=True)¶

Class for working with Hokuyo laser rangefinders, specifically with the following models: UST-10LX, UST-20LX, UST-30LX

Methods

__init__(activate=True, info=True, tsync=True, addr=None, buf=512, timeout=5, time_tolerance=300, logger=None, convert_time=True)¶

Creates new object for communications with the sensor.

Parameters:

activate : bool, optional

Switch sensor to the standby mode? (the default is True)

info : bool, optional

Update sensor information? (the default is True)

tsync : bool, optional

Perform time synchronization? (the default is True)

addr : tuple, optional

IP address and port of the sensor (the default is (‘192.168.0.10’, 10940))

buf : int, optional

Buffer size for recieving messages from the sensor (the default is 512)

timeout : int, optional

Timeout limit for connection with the sensor in seconds (the default is 5)

time_tolerance : int, optinal

Time tolerance before attempting time synchronization in milliseconds (the default is 300)

logger : logging._logger instance, optional

Logger instance, if none is provided new instance is created

convert_time : bool

Convert timestamps to UNIX time?

activate()¶

Switches the sensor to the measurement state and starts the measurement process by lighting (activating) the laser. Valid in the standby state.

Returns:

code : int

Command status code

description : str

Command status description

Examples

>>> laser.laser_state()
(0, 'Standby state')
>>> status, description = laser.activate()
>>> status
0
>>> description
'Normal. The sensor is in measurement state and the laser was lighted.'
>>> laser.laser_state()
(3, 'Single scan state')

close()¶: Disconnects from the sensor closing TCP socket

get_angles(start=None, end=None, grouping=0)¶

Returns array of angles for given start, end and grouping parameters and according to the sensor parameters stored inside object.

Parameters:

start : int, optional

Position of the starting step (the default is None, which implies self.amin)

end : int, optional

Position of the ending step (the default is None, which implies self.amax)

grouping : int, optional

Number of grouped steps (the default is 0, which regarded as 1)

Returns:

ndarray

List of angles in radians

Examples

>>> laser.get_angles()
array([-1.17809725, -1.17591558, -1.17373392, ...,  1.17373392,
    1.17591558,  1.17809725])

get_dist(start=None, end=None, grouping=0)¶

Measure distances for the given parameters

Parameters:

start : int, optional

Position of the starting step (the default is None, which implies self.amin)

end : int, optional

Position of the ending step (the default is None, which implies self.amax)

grouping : int, optional

Number of grouped steps (the default is 0, which regarded as 1)

Returns:

timestamp : int

Timestamp of the measurment

scan : ndarray

Array with measured distances

get_filtered_dist(start=None, end=None, grouping=0, dmin=None, dmax=None)¶

Measure distances for the given parameters and perform basic filtering. Returns array with angles and distances.

Parameters:

start : int, optional

Position of the starting step (the default is None, which implies self.amin)

end : int, optional

Position of the ending step (the default is None, which implies self.amax)

grouping : int, optional

Number of grouped steps (the default is 0, which regarded as 1)

dmin : int, optional

Minimal distance for filtering (the default is None, which implies self.dmin)

dmax : int, optional

Maximum distance for filtering (the default is None, which implies self.dmax)

Returns:

timestamp : int

Timestamp of the measurment

scan : ndarray

Array with measured distances and angles

get_filtered_intens(start=None, end=None, grouping=0, dmin=None, dmax=None, imin=None, imax=None)¶

Measure distances and intensities for the given parameters and perform basic filtering. Returns array with angles, distances and intensities.

Parameters:

start : int, optional

Position of the starting step (the default is None, which implies self.amin)

end : int, optional

Position of the ending step (the default is None, which implies self.amax)

grouping : int, optional

Number of grouped steps (the default is 0, which regarded as 1)

dmin : int, optional

Minimum distance for filtering (the default is None, which implies self.dmin)

dmax : int, optional

Maximum distance for filtering (the default is None, which implies self.dmax)

imin : int, optional

Minimum intensity for filtering (the default is None, which disables minimum intensity filter)

imax : int, optional

Maximum distance for filtering (the default is None, which disables maximum intensity filter)

Returns:

timestamp : int

Timestamp of the measurment

scan : ndarray

Array with measured angles, distances and intensities

get_intens(start=None, end=None, grouping=0)¶

Measure distances and intensities for the given parameters

Parameters:

start : int, optional

Position of the starting step (the default is None, which implies self.amin)

end : int, optional

Position of the ending step (the default is None, which implies self.amax)

grouping : int, optional

Number of grouped steps (the default is 0, which regarded as 1)

Returns:

timestamp : int

Timestamp of the measurment

scan : ndarray

Array with measured distances and intensities

iter_dist(scans=0, start=None, end=None, grouping=0, skips=0)¶

Generator for taking continous measurment of distances. If scan is equal to 0 infinite number of scans will be taken until laser is switched to the standby state.

Parameters:

scans : int, optional

Number of scans to perform (the default is 0, which means infinite number of scans)

start : int, optional

Position of the starting step (the default is None, which implies self.amin)

end : int, optional

Position of the ending step (the default is None, which implies self.amax)

grouping : int, optional

Number of grouped steps (the default is 0, which regarded as 1)

skips : int, optional

Number of scans to skip (the default is 0, 0 means all scans will be yielded, 1 - every second, 2 - every third, etc.)

Yields:

timestamp : int

Timestamp of the measurment

scan : ndarray

Array with measured distances

iter_filtered_dist(scans=0, start=None, end=None, grouping=0, skips=0, dmin=None, dmax=None)¶

Generator for taking continous measurment of distances with additional filtering. If scan is equal to 0 infinite number of scans will be taken until laser is switched to the standby state.

Parameters:

with_intensity : bool

Measure with intensities or only distances

scans : int, optional

Number of scans to perform (the default is 0, which means infinite number of scans)

start : int, optional

Position of the starting step (the default is None, which implies self.amin)

end : int, optional

Position of the ending step (the default is None, which implies self.amax)

grouping : int, optional

Number of grouped steps (the default is 0, which regarded as 1)

skips : int, optional

Number of scans to skip (the default is 0, 0 means all scans will be yielded, 1 - every second, 2 - every third, etc.)

dmin : int, optional

Minimal distance for filtering (the default is None, which implies self.dmin)

dmax : int, optional

Maximum distance for filtering (the default is None, which implies self.dmax)

Yields:

timestamp : int

Timestamp of the measurment

scan : ndarray

Array with measured angles and distances

iter_filtered_intens(scans=0, start=None, end=None, grouping=0, skips=0, dmin=None, dmax=None, imin=None, imax=None)¶

Generator for taking continous measurment of distances and intensities with additional filtering. If scan is equal to 0 infinite number of scans will be taken until laser is switched to the standby state.

Parameters:

with_intensity : bool

Measure with intensities or only distances

scans : int, optional

Number of scans to perform (the default is 0, which means infinite number of scans)

start : int, optional

Position of the starting step (the default is None, which implies self.amin)

end : int, optional

Position of the ending step (the default is None, which implies self.amax)

grouping : int, optional

Number of grouped steps (the default is 0, which regarded as 1)

skips : int, optional

Number of scans to skip (the default is 0, 0 means all scans will be yielded, 1 - every second, 2 - every third, etc.)

dmin : int, optional

Minimal distance for filtering (the default is None, which implies self.dmin)

dmax : int, optional

Maximum distance for filtering (the default is None, which implies self.dmax)

imin : int, optional

Minimum intensity for filtering (the default is None, which disables minimum intensity filter)

imax : int, optional

Maximum distance for filtering (the default is None, which disables maximum intensity filter)

Yields:

timestamp : int

Timestamp of the measurment

scan : ndarray

Array with measured angles, distances and intensities

iter_intens(scans=0, start=None, end=None, grouping=0, skips=0)¶

Generator for taking continous measurment of distances and intensities. If scan is equal to 0 infinite number of scans will be taken until laser is switched to the standby state.

Parameters:

scans : int, optional

Number of scans to perform (the default is 0, which means infinite number of scans)

start : int, optional

Position of the starting step (the default is None, which implies self.amin)

end : int, optional

Position of the ending step (the default is None, which implies self.amax)

grouping : int, optional

Number of grouped steps (the default is 0, which regarded as 1)

skips : int, optional

Number of scans to skip (the default is 0, 0 means all scans will be yielded, 1 - every second, 2 - every third, etc.)

Yields:

timestamp : int

Timestamp of the measurment

scan : ndarray

Array with measured distances and intensities

laser_state()¶

Return the current sensor state. It is valid during any sensor state.

Returns:

int

Sensor state code

str

Sensor state description

partial_reset()¶

This command forces the sensor to switch to the standby state and performs the following tasks:

Turns off (deactivates) the laser.
Sets the internal sensor timer to zero.
Sets the measurement sensitivity to the default (normal) value.

This is similar to the reset command, except the motor rotational (scanning) speed and the serial transmission speed are not changed. When the sensor is in the abnormal condition state, the partial_reset command is not received.

reboot()¶

This command reboots the sensor and performs the following tasks:

Waits for 1 second, during this time the host system disconnects from the sensor.
The sensor stops all communications.
Turns off (deactivates) the laser.
Sets the motor rotational speed (scanning speed) to the default initialization value.
Sets the serial transmission speed (bit rate) to the default initialization value.
Sets the internal sensor timer to zero.
Sets the measurement sensitivity to the default (normal) value.
Initializes other internal parameters, and waits until the scanning speed is stable.
Switches to standby state.

It is the only state transition command that can be received during abnormal condition state

reset()¶

This command forces the sensor to switch to the standby state and performs the following tasks:

Turns off (deactivates) the laser.
Sets the motor rotational speed (scanning speed) to the default initialization value.
Sets the serial transmission speed (bit rate) to the default initialization value.
Sets the internal sensor timer to zero.
Sets the measurement sensitivity to the default (normal) value.

However, when the sensor is in the abnormal condition state, the reset command is not received.

sensor_parameters()¶: Obtains sensor internal parameters information. This command is valid during any sensor state except the time synchronization state.

sensor_state()¶: Obtains status information of the sensor. This command is valid during any sensor state.

sleep()¶

Switches the sensor to the sleep state. When the sensor receives the sleep command, it stops the current measurement process, switches to the sleep state, turns off (deactivates) the laser and stops the motor. Valid in the standby state or in the measurement state.

Examples

>>> laser.laser_state()
(0, 'Standby state')
>>> laser.sleep()
>>> laser.laser_state()
(5, 'Sleep state')

standby()¶

Stops the current measurement process and switches the sensor to the standby state. Valid in the measurement state or in the measurement and scan response state.

Examples

>>> laser.laser_state()
(3, 'Single scan state')
>>> laser.standby()
>>> laser.laser_state()
(0, 'Standby state')

time_sync(N=10, dt=0.1)¶

Performs time synchronization by doing tsync_get`requests each `dt seconds N times. After that it finds mean time shift, saving it into self.tzero. This value also can be interpreted as the time when the sensor was turned in.

Parameters:

N : int, optional

Number of times to request time from the sensor (the default is 10)

dt : float, optional

Time between time requests (the default is 0.1)

tsync_enter()¶: Transition from standby state to time synchronization state.

tsync_exit()¶: Transition from time synchronization state to standby state.

tsync_get()¶: Get time value for time synchronization

update_info()¶: Updates sensor information stored in the object attributes using sensor_parameters method.

version()¶: Obtains manufacturing (version) information of the sensor. This command is valid during any sensor state.

Submodules¶

hokuyolx.exceptions module¶

Exceptions used in hokuyolx module

exception hokuyolx.exceptions.HokuyoChecksumMismatch¶

Bases: hokuyolx.exceptions.HokuyoException

Exception class which represents checksum mismatch errors inside Hokuyo communication protocol

exception hokuyolx.exceptions.HokuyoException¶

Bases: Exception

Basic exception class for Hokuyo laser scanners

exception hokuyolx.exceptions.HokuyoStatusException(code)¶

Bases: hokuyolx.exceptions.HokuyoException

Exception class which represents unexpected reply status errors inside Hokuyo communication protocol

code = None¶

get_status()¶

Returns status description

Returns:

str

Status description

hokuyolx.statuses module¶

Various statuses, their codes and descriptions used in the hokuyolx