Using Sensors

NOTE: This documentation is for a kernel that has not been officially released. If you want to try it out, grab the latest test image.

Overview

One of the goals of ev3dev is to support as many sensors as possible. If you have a sensor that does not work, let us know about it.

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.

Analog Sensors

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. 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 a generic interface.

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.

LEGO NXT Color Sensor

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

I2C Sensors

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).

UART Sensors

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.

Usage

The Mindstorms Sensor class

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.

root@ev3dev:/sys/class/msensor/sensor0# ls
bin_data	 dp	num_values  type_id  value0  value3  value6
bin_data_format  mode	port_name   uevent   value1  value4  value7
device		 modes	subsystem   units    value2  value5

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.

root@ev3dev:/sys/class/msensor/sensor0# cat modes
COL-REFLECT COL-AMBIENT COL-COLOR REF-RAW RGB-RAW COL-CAL
root@ev3dev:/sys/class/msensor/sensor0# cat mode
COL-REFLECT
root@ev3dev:/sys/class/msensor/sensor0# echo COL-COLOR > mode
root@ev3dev:/sys/class/msensor/sensor0# cat 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.

root@ev3dev:/sys/class/msensor/sensor0# cat num_values # mode is still COL-COLOR
1
root@ev3dev:/sys/class/msensor/sensor0# cat 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
root@ev3dev:/sys/class/msensor/sensor0# echo RGB-RAW > mode
root@ev3dev:/sys/class/msensor/sensor0# cat num_values
3
root@ev3dev:/sys/class/msensor/sensor0# cat 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

Analog Sensor Considerations

NXT Analog sensors, for the most part, cannot be autodetected. The exceptions are the LEGO NXT Light Sensor and the LEGO NXT Touch Sensor. The remaining sensors use a common msensor interface. There are two modes NXT-ANALOG-0 and NXT-ANALOG-1. The only difference between the two is that when you set the mode to NXT-ANALOG-1, the GPIO connected to pin 5 will be set high. Some sensors use this to measure a different value. See the individual sensor documentation below to see if a sensor supports more than one mode.

The sensor value is read using the value0 attribute. It reads the voltage from the analog/digital converter (0..5V). User programs will have to be told what sensor is attached and how to scale the voltage to a usable value.

I2C Sensor Considerations

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:

root@ev3dev:/sys/class/msensor# ls
sensor0 sensor1
root@ev3dev:/sys/class/msensor# cd sensor1
root@ev3dev:/sys/class/msensor/sensor1# cat modes
NXT-US-CM NXT-US-IN NXT-US-SI-CM NXT-US-SI-IN NXT-US-LIST

I2C/S sensors are not autodetected because there is no standard way to detect them. There are just too many possibilities. But, they are easy to load manually and you can write udev rules to load them automatically if you want. Most of 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.

List of Sensors

Manufacturer	Mfg. P/N	Name	Connection Type	Auto- detected	Driver (Module)
CODATEX		Codatex RFID Sensor
Dexter Industries
HiTechnic	NAA1030	NXT Angle Sensor	I2C/M	Y	ht‑naa1030 (nxt‑i2c‑sensor)
	NAC1040	NXT Acceleration / Tilt Sensor	I2C/M	Y	ht‑nac1040 (nxt‑i2c‑sensor)
	NBR1036	NXT Barometric Sensor	I2C/M	Y	ht‑nbr1036 (nxt‑i2c‑sensor)
	NCO1038	NXT Color Sensor V2	I2C/M	Y	ht‑nco1038 (nxt‑i2c‑sensor)
	NEO1048	NXT EOPD	Analog/NXT	Y*	(nxt‑analog‑sensor)
	NFS1074	NXT Force Sensor	Analog/NXT	Y*	(nxt‑analog‑sensor)
	NGY1044	NXT Gyro Sensor	Analog/NXT	Y*	(nxt‑analog‑sensor)
	NIL1046	NXT IRLink Sensor	I2C/M	Y	ht‑nil1046 (nxt‑i2c‑sensor)
	NIS1070	NXT PIR Sensor	I2C/M	Y	ht‑nis1070 (nxt‑i2c‑sensor)
	NIR1032	NXT IRReceiver Sensor	I2C/M	Y	ht‑nir1032 (nxt‑i2c‑sensor)
	NMC1034	NXT Compass Sensor	I2C/M	Y	ht‑nmc1034 (nxt‑i2c‑sensor)
	NMS1035	NXT Magnetic Sensor	Analog/NXT	Y*	(nxt‑analog‑sensor)
	NSK1042	NXT IRSeeker V2	I2C/M	Y	ht‑nsk1042 (nxt‑i2c‑sensor)
	NSX2020	NXT Sensor Multiplexer	I2C/M	Y	ht‑nsx2020 (nxt‑i2c‑sensor)
	NTX1060	NXT Touch Sensor Multiplexer	Analog/NXT	Y*
	SPR2010	NXT SuperPro Prototype Board	I2C/M	Y	ht‑spr2010 (nxt‑i2c‑sensor)
	???	NXT Color Sensor (v1)	I2C/M	Y	ht‑nco (nxt‑i2c‑sensor)
LEGO / LEGO Education	9668	Energy Display	I2C/M	Y	lego‑9668 (nxt‑i2c‑sensor)
	9694	NXT Color Sensor	Special	Y	nxt‑color‑sensor
	9749	NXT Temperature Sensor	I2C/S	N	tmp275 (lm75)
	9843	NXT Touch Sensor	Analog/NXT	Y	nxt‑analog‑sensor (touch‑sensor)
	9844	NXT Light Sensor	Analog/NXT	Y	nxt‑analog‑sensor (nxt‑light‑sensor)
	9845	NXT Sound Sensor	Analog/NXT	Y*	(nxt‑analog‑sensor)
	9846	NXT Ultrasonic Sensor	I2C/M	Y	lego‑9846 (nxt‑i2c‑sensor)
	45504	EV3 Ultrasonic Sensor	UART	Y
	45505	EV3 Gyro Sensor	UART	Y
	45506	EV3 Color Sensor	UART	Y
	45507	EV3 Touch Sensor	Analog/EV3	Y	ev3‑analog‑sensor (touch‑sensor)
	45509	EV3 Infrared Sensor	UART	Y
LogIT		NXT Sensor Adapter
mindsensors.com	LightSensorArray	Light Sensor Array	I2C/M	Y	ms‑light‑array (nxt‑i2c‑sensor)
	MagicWand	Magic Wand Kit	I2C/S	N	pcf8574 (gpio‑pcf857x)
	PCF8574-Nx	Sensor building kit for NXT with PCF8574 IC	I2C/S	N	pcf8574 (gpio‑pcf857x)
	PCF8591-Nx	Sensor building kit for NXT with PCF8591 IC	I2C/S	N	pcf8591 (pcf8591)
	RTC-Nx-v3	Realtime Clock for NXT	I2C/S	N	ds1307 (rtc‑ds1307)
Vernier		NXT Sensor Adapter

\* Analog/NXT sensors are detected but cannot be differentiated, so a generic interface is provided. Additional drivers may be required (although none exist yet).