Texas Instruments OPT3001EVM User manual

OPT3001EVM Linux Getting Started Guide
Felipe Balbi
August 18, 2014

This page is intentionally left blank

Contents
1 Scope 1
2 Introduction 2
2.1 OPT3001 ............................... 2
2.2 BeagleBoneBlack .......................... 2
2.3 LinuxKernel ............................. 2
3 Hardware Platform 3
4 The Linux Kernel 5
4.1 Writing Our DeviceTree . . . . . . . . . . . . . . . . . . . . . . . 5
4.2 Downloading The Correct Version . . . . . . . . . . . . . . . . . 6
4.3 Kernel Configuration . . . . . . . . . . . . . . . . . . . . . . . . . 7
5 Usage 13
6 Conclusion 15
ii

Chapter 1
Scope
This document will describe the necessary steps to connect OPT3001EVM to
a BeagleBone Black development platform.
By the end of this User’s Guide, the reader should be able to verify function-
ality of the OPT3001 device and get results from light measurements.
1

Chapter 2
Introduction
2.1 OPT3001
The OPT3001 is an ideal sensing device for measuring ambient light. Mea-
surements can be made from 0.01 lux up to 83k lux without selecting full-scale
ranges by using the built-in, full-scale setting feature. This capability allows
light measurement over a 23-bit effective dynamic range.
The spectral response of the ambient light sensor is tightly matched to the
photopic response of the human eye and has significant infrared rejection. This
tightly matched response offers accurate lux readings of different spectral sources,
even under dark glass.
The digital operation is flexible for system integration. Measurements can
be either continuous or single-shot. The control and interrupt system features
autonomous operation, allowing the processor to sleep while the sensor searches
for appropriate wake-up events.
The low power consumption and low power-supply voltage capability make
this device ideal for battery-powered applications.
2.2 Beagle Bone Black
Beagle Bone Black is an Open Source Hardware Software Development Plat-
form using Texas Instruments’ AM335x System-on-Chip device.
It provides an easy to use Software Development Platform based on an ARM
Cortex-A8 CPU together with many other peripherals integrated into the die.
2.3 Linux Kernel
The Linux Kernel was created by Linus Torvalds back in 1991. It’s a General
Purpose Operating System which works in many different architectures includ-
ing, but not limited to, x86, ARM, ARC, Power, MIPS, and Alpha.
2

Chapter 3
Hardware Platform
For the purpose of this Getting Started Guide, we will be using OPT3001EVM
Rev B and Beagle Bone Black Rev A5C.
The picture below shows a simple way of connecting OPT3001EVM to the
Beagle Bone Black using a standard 100 mil spacing breadboard.
Connected like that, OPT3001 will show on Beagle Bone Black’s I2C Bus 2
1. The following section will describe all the necessary steps to get OPT3001
working on our Beagle Bone Black.
1note that I2C Bus numbers start at 0, so I2C Bus 2 is the third I2C Bus on Beagle Bone
Black
3

CHAPTER 3. HARDWARE PLATFORM 4
Figure 3.1: connecting opt3001evm to beagle bone black

Chapter 4
The Linux Kernel
4.1 Writing Our DeviceTree
Now that we have OPT3001EVM connected to our Beagle Bone Black, we
need to tell Linux about it. Recent Linux Kernel release utilize Open Firmware
as the methodology for firmware to tell the Operating System about devices
which sit under non-enumerable buses. The language used by Open firmware is
known as DeviceTree
With a DeviceTree source such as below, we can tell Linux that we have
an OPT3001 device sitting under I2C Bus 2 and can be accessed through I2C
address 0x44.
/* arch/arm/boot/dts/am335x-boneblack.dts */
&i2c2 {
status = "okay";
pinctrl-names = "default";
pinctrl-0 = <&i2c2_pins>;
clock-frequency = <400000>;
light@44 {
status = "okay";
pinctrl-names = "default";
pinctrl-0 = <&light_pins>;
compatible = "opt3001";
reg = <0x44>;
interrupts-extended = <&gpio1 28 IRQ_TYPE_LEVEL_HIGH>;
};
};
Note that we have two undefined pinctrl DeviceTree nodes. Let’s define them:
/* arch/arm/boot/dts/am335x-boneblack.dts */
5

CHAPTER 4. THE LINUX KERNEL 6
&am33xx_pinmux {
i2c2_pins: i2c2_pins {
pinctrl-single,pins = <
0x178 (PIN_INPUT | SLEWCTRL_FAST | MUX_MODE3) /*
uart1_ctsn.i2c2_sda */
0x17c (PIN_INPUT | SLEWCTRL_FAST | MUX_MODE3) /*
uart1_rtsn.i2c2_scl */
>;
};
light_pins: light_pins {
pinctrl-single,pins = <
0x78 (PIN_INPUT | MUX_MODE7) /* gpmc_ben1.gpio1_28
*/
>;
};
};
4.2 Downloading The Correct Version
At the time of this writing OPT3001 driver is still not merged in the Mainline
1Linux Kernel tree. Because of that we have provided git branches for all Linux
Kernel versions starting with v3.14 all the way to v3.17.
On each of those branches, you will find the same OPT3001 driver together
with Beagle Bone Black devicetree changes for easy start.
Depending on which Linux Kernel version you’re using, download the correct
branch as per table below:
Linux Version GIT URL
v3.14 git://git.kernel.org/pub/scm/linux/kernel/git/balbi/usb.git opt3001-v3.14
v3.15 git://git.kernel.org/pub/scm/linux/kernel/git/balbi/usb.git opt3001-v3.15
v3.16 git://git.kernel.org/pub/scm/linux/kernel/git/balbi/usb.git opt3001-v3.16
v3.17 git://git.kernel.org/pub/scm/linux/kernel/git/balbi/usb.git opt3001-v3.17
To download any of those branches a certain level of knowledge about the git
version control system is required but the short version is below 2.
$ git clone git://git.kernel.org/pub/scm/linux/kernel/git/balbi/usb.git
linux
cloning into ’linux’...
remote: counting objects: 3802743, done.
remote: compressing objects: 100% (582455/582455), done.
remote: total 3802743 (delta 3207582), reused 3785375 (delta 3190275)
receiving objects: 100% (3802743/3802743), 801.20 mib | 1.84 mib/s, done.
resolving deltas: 100% (3207582/3207582), done.
1Linux Kernel tree maintained by Linus Torvalds
2we are assuming the reader already has git installed in their system

CHAPTER 4. THE LINUX KERNEL 7
checking connectivity... done.
checking out files: 100% (47441/47441), done.
$cd linux
$ git reset --hard opt3001-v3.14
4.3 Kernel Configuration
After downloading the Kernel sources, we need to configure it for our setup.
We will start by running:
$ make ARCH=arm CROSS_COMPILE=arm-linux- omap2plus_defconfig
hostcc scripts/basic/fixdep
hostcc scripts/kconfig/conf.o
shipped scripts/kconfig/zconf.tab.c
shipped scripts/kconfig/zconf.lex.c
shipped scripts/kconfig/zconf.hash.c
hostcc scripts/kconfig/zconf.tab.o
hostld scripts/kconfig/conf
#
# configuration written to .config
#
This first command will select all common configuration for Texas Instru-
ments’ SoCs, including AM335x. Now we need to enable OPT3001 driver. For
that, we will run:
$ make arch=arm cross_compile=arm-linux- menuconfig
You should see a screen such as below in Figure 4.1.
After that, let’s enable the industrial i/o framework and opt3001 driver, please
follow the steps below and refer to the Screen Captures, if necessary.
1. navigate to Device Drivers and press ENTER (see figure 4.2);
2. navigate to Industrial I/O support (see figure 4.3);
(a) press M3(see figure 4.4); or
(b) press Y4(see figure 4.5);
3. navigate to Light sensors and press ENTER (see figure 4.6);
4. navigate to Texas Instruments OPT3001 Light Sensor (see figure 4.7);
(a) press M(see figure 4.8); or
(b) press Y(see figure 4.9);
3M will compile a dynamically linked module
4Y will link the binary statically to the kernel image

CHAPTER 4. THE LINUX KERNEL 8
5. exit menuconfig by following all ¡Exit¿ buttons;
6. when asked if you want to save the new configuration, choose ¡Yes¿ (see
figure 4.10).

CHAPTER 4. THE LINUX KERNEL 9
Figure 4.1: linux kernel configuration main window
Figure 4.2: Navigating to Device Drivers
Figure 4.3: Navigating to Industrial I/O support

CHAPTER 4. THE LINUX KERNEL 10
Figure 4.4: Industrial I/O support after pressing M on the keyboard
Figure 4.5: Industrial I/O support after pressing Y on the keyboard
Figure 4.6: Navigating to Light sensors

CHAPTER 4. THE LINUX KERNEL 11
Figure 4.7: Navigating to Texas Instruments OPT3001 Light Sensors
Figure 4.8: OPT3001 after pressing M on the keyboard
Figure 4.9: OPT3001 after pressing Y on the keyboard

CHAPTER 4. THE LINUX KERNEL 12
Figure 4.10: Exitting menuconfig

Chapter 5
Usage
After booting up and logging in to our Beagle Bone Black running Linux, we
will navigate to the directory where files created by our OPT3001 Device Driver
are located. To do that, please run:
# cd /sys/bus/iio/devices/iio\:device0
# ls
dev \verb|in_illuminance_integration_time| power
events \verb|integration_time_available| subsystem
\verb|in_illuminance_input| name uevent
In order to get a single-shot Light measurement, all we have to do is read
in_illuminance_input file.
# cat \verb|in_illuminance_input|
7.800000
We can also setup thresholds and have events fire when such thresholds are
reached. In order to illustrate that we will make use of iio_event_monitor, a
tool which can be found at drivers/staging/iio/Documentation/iio_event_monitor.c.
Let’s setup some thresholds:
# cd events
# ls
\verb|in_illuminance_thresh_falling_en|
\verb|in_illuminance_thresh_falling_hysteresis|
\verb|in_illuminance_thresh_falling_value|
\verb|in_illuminance_thresh_rising_en|
\verb|in_illuminance_thresh_rising_hysteresis|
\verb|in_illuminance_thresh_rising_value|
# echo 200 > \verb|in_illuminance_thresh_falling_value|
# echo 500 > \verb|in_illuminance_thresh_rising_value|
# echo 1 > \verb|in_illuminance_thresh_fallin_en|
# \verb|iio_event_monitor /dev/iio\:device0|
Event: time: 946685148546403596, type: illuminance, channel: 0, evtype:
thresh, direction: rising
13

CHAPTER 5. USAGE 14
Event: time: 946685149344980019, type: illuminance, channel: 0, evtype:
thresh, direction: falling
Event: time: 946685157295473266, type: illuminance, channel: 0, evtype:
thresh, direction: rising
Event: time: 946685162934369540, type: illuminance, channel: 0, evtype:
thresh, direction: falling
Event: time: 946685165222147843, type: illuminance, channel: 0, evtype:
thresh, direction: rising
Event: time: 946685166824180824, type: illuminance, channel: 0, evtype:
thresh, direction: falling

Chapter 6
Conclusion
During this short Guide we have wired OPT3001EVM to a Beagle Bone Black
using a standard breadboard, we downloaded and compiled the Linux Kernel
and also verified that OPT3001 driver functions as expected.
15

This page is intentionally left blank