Using Sensors - dlech/ev3dev GitHub Wiki

One of the goals of ev3dev is to support as many sensors as possible. In fact, even if a manufacturer's documentation says that a device does not work with the EV3, chances are it will work with ev3dev. If you have a sensor that is not supported yet, let us know about it by opening an issue on GitHub. For some kinds of sensors adding a driver is trivial. See the contributing page for information on how to write a driver or how to donate hardware to someone who will.

When dealing with sensors in ev3dev, it is useful to know how it communicates with the EV3 brick. This influences what you need to do to read data from your sensor.

These are the simplest type of sensor. The measured value is converted to a voltage (0-5VDC) that is read by the EV3. There are actually two types of analog sensors. We call the first Analog/EV3. These are sensors that were designed specifically for the EV3 and will not work on the NXT because the pinout is different. They contain an ID resistor so that the EV3 can tell different types of sensors apart. The second type is Analog/NXT. These sensors are designed for the NXT, but also work on the EV3. The EV3 cannot differentiate between most of these sensors though, so you have to tell it which one your have or just use the generic driver.

RCX sensors also fall into this category, but do not work with the EV3 - at least not with the converter cable described in the NXT Hardware Developers kit. This is due to a difference in the input port pins between the EV3 and the NXT. If someone wants to research the LEGO 8528 cable or design a new converter cable, we could probably make them work.

The LEGO NXT Color Sensor is in a class of its own. We don't have a driver for it yet.

I2C sensors are sensors that communicate with the intelligent brick via the I2C protocol. In the NXT documentation, they are referred to a "digital" sensors.

These sensors can be sorted into two categories as well: those that were designed using LEGO's guidelines and those that use an off the shelf I2C chip. ev3dev supports both kind of sensors, but only the first type is auto-detected. We will refer to the former as I2C/M (for Mindstorms) and the latter as I2C/S (for Standard).

These are a new type of sensor designed for the EV3 (they don't work with the NXT). They use an UART to send data to the brick. These sensors are a bit "smarter" in that in addition to sending the data of what they measure, they also send information about their capabilities. This means that any new UART sensors should "just work" without us having to write new drivers.

Most sensors are accessed using a device driver class especially for Mindstorms sensors. When you plug a sensor in (assuming it is the auto-detectable type) a sysfs node will be added to /sys/class/msensor. The name of the node will be sensorN where N is incremented for each sensor that is plugged in.

For full details, see Using the Mindstorms Sensor Device Class. For the basics, keep going.

For an example, I will be using the EV3 Color Sensor. If we plug the sensor into any input port, a new device will be added to the msensor class.

$ ls /sys/class/msensor/sensor0/
address          device  modes       port_name     uevent  value1  value4  value7
bin_data         dp      name        power         units   value2  value5
bin_data_format  mode    num_values  subsystem     value0  value3  value6

Each sensor has a number of modes in which in can operate. You can view the available modes with the modes attribute and view/change the current mode using the mode attribute.

$ cat /sys/class/msensor/sensor0/modes
COL-REFLECT COL-AMBIENT COL-COLOR REF-RAW RGB-RAW COL-CAL
$ cat /sys/class/msensor/sensor0/mode
COL-REFLECT
$ echo COL-COLOR > /sys/class/msensor/sensor0/mode
$ cat /sys/class/msensor/sensor0/mode
COL-COLOR

The values measured by the sensor are read through the valueN attributes. The num_values attributes will tell you how many values there are. Values with an index >= num_values will return an error.

$ cat /sys/class/msensor/sensor0/num_values # mode is still COL-COLOR
1
$ cat /sys/class/msensor/sensor0/value*
0
cat: value1: No such device or address
cat: value2: No such device or address
cat: value3: No such device or address
cat: value4: No such device or address
cat: value5: No such device or address
cat: value6: No such device or address
cat: value7: No such device or address
$ echo RGB-RAW > /sys/class/msensor/sensor0/mode
$ cat /sys/class/msensor/sensor0/num_values
3
$ cat /sys/class/msensor/sensor0/value*
4
6
2
cat: value3: No such device or address
cat: value4: No such device or address
cat: value5: No such device or address
cat: value6: No such device or address
cat: value7: No such device or address

In order for a sensor driver to be loaded, there are actually several layers of drivers that have to be in place. The first layer is the port driver. This is what controls the internal circuitry that is connected to the input ports on the EV3. You can find the ports at /sys/bus/legoev3/devices/inX where X is the number of the port. You can actually use this driver to control the port if you don't want to use the default auto-detection of sensors.

The next layer is the host. The host facilitates communications between the port and the sensor. The type of host that is loaded depends on the type of sensor that is connected. There is one for each of the types listed above (Analog/EV3, Analog/NXT, NXT Color Sensor, I2C and UART).

The final layer is the sensor driver itself. These drivers communicate with the lower layers and convert the information received into something more usable, like converting a voltage value to centimeters for a distance sensor.

NXT Analog sensors, for the most part, cannot be auto-detected. The exceptions are the LEGO NXT Light Sensor and the LEGO NXT Touch Sensor. The remaining sensors default to a generic driver (although some may be incorrectly detected as the Light or Touch sensor). To change the driver, we need to use the nxt-analog-host (that's the middle layer). We can also get a list of available drivers from the sensor driver itself.

$ cat /sys/bus/legoev3/drivers/nxt-analog-sensor/sensor_names 
nxt-analog lego-nxt-touch lego-nxt-light lego-nxt-sound ht-nxt-eopd ht-nxt-force
 ht-nxt-gyro ht-nxt-mag ms-nxt-touch-mux
# Tell the EV3 we have a HiTechnic NXT Gyro Sensor
$ echo ht-nxt-gyro > /sys/bus/legoev3/devices/in2\:nxt-analog-host/set_sensor
# Check the kernel messages to see if it worked
$ dmesg | tail -n 4
nxt-analog-host in2:nxt-analog-host: Removed device 'in2:nxt-analog'
msensor sensor1: Unregistered
msensor sensor2: Bound to device 'in2:ht-nxt-gyro'
nxt-analog-host in2:nxt-analog-host: Added new device 'in2:ht-nxt-gyro'

I2C/M sensors should be auto-detected. They will show up in /sys/class/msensors and have the same interface as other sensors.

Example: If we connect an NXT Ultrasonic Sensor to another input port, we should see something like this:

$ ls /sys/class/msensor/
sensor0 sensor2 sensor3
$ cat /sys/class/msensor/sensor3/modes
NXT-US-CM NXT-US-IN NXT-US-SI-CM NXT-US-SI-IN NXT-US-LIST

I2C/S sensors are not auto-detected because there is no standard way to detect them. There are just too many possibilities. But, it is easy enough to load a driver manually and you can write udev rules to load them automatically if you want.These types of sensors do not use /sys/class/msensors because there are already existing drivers in the Linux kernel for many standard I2C chips.

To learn how to manually load I2C devices and many more interesting things about I2C sensors, see Using I2C Sensors. Also be sure to look at the individual sensor documentation using the links in the table below.