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:
- http://www.hokuyo-aut.jp/02sensor/07scanner/download/pdf/UTM-30LX-EW_protocol_en.pdf
- https://www.hokuyo-aut.jp/02sensor/07scanner/download/pdf/UST_protocol_en.pdf
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