TinyLiDAR on a Pi?

Hello again!

Well now that you've spent some quality time with tinyLiDAR and your Arduino - your Raspberry Pi maybe feeling a bit lonely ;)

The pi has an I2C port right? So why not hook it up and try it on there?! Good plan, but if you've already tried - you may have noticed the data looks a bit strange.

Yes, the pi has built in 1.8K pull-ups already so you will have to cut the I2C pads on tinyLiDAR to get the 4.7K pull-ups out of circuit - see reference manual for details. But this is not the reason for the strange data.

It is because the pi's I2C bus is not exactly up to spec. It's been like this since the pi was first introduced due to the Broadcom chip set. From the very beginning they haven't properly supported an I2C feature called "clock stretching".

You can read more about this h/w bug here.

As you may know, the I2C bus consists of 3 wires. These are for clock (SCL), data (SDA) and common ground. The clock and data lines are of open-collector/open-drain type which means they need pull-up resistors connected to a positive supply rail to give them a logic high. To get a logic low, any device on the bus can pull down the line to common ground.

As per the I2C standard, the Master device is the one that supplies the clock signal on the SCL line but if this rate is too fast then the Slave device is allowed to slow it down by simply holding down the clock line until its ready to deal with the information. This is what we call "clock stretching".

Officially, clock stretching was listed as an optional feature in the I2C standard but it is a very common feature that’s necessary for most "intelligent" slaves that need some extra time to provide sensor data etc.

To deal with this I2C h/w bug, we found a nice little free library called "pigpio". It's a very popular, fast and lightweight library written in C. It runs as a background daemon for the Raspberry Pi and allows us to control the I2C as well as any GPIO easily from python. The library treats the I2C ports more like GPIO and thereby has bypassed the I2C clock stretching bug. Like all software on the pi, the pigpio library is only just a simple "include" away so let's go!

Setup Pi
Enable SSH to login with Putty
Install pigpio library
Get tinyLiDAR zip file
Unzip and run from Putty

Optional:

Setup SublimeText with WinSCP

For our Raspberry Pi 3, we used the standard New Out Of the Box Software (NOOBS Lite v2.4) operating system. It contains a default version of Python already installed for us ready to code with. You can download the OS from here.

Once installed on a micro SD card you have to connect a keyboard and monitor so you can login to the pi for the first time:

Username: pi
Password: raspberry

Then you can start a secure shell server (SSH) with these commands:

sudo systemctl enable ssh
sudo systemctl start ssh

Next we will need the IP address of the pi on your network so we can login with PuTTY. To get this, just type:

hostname -I 

And look for an IPv4 format address (For our setup it was: 192.168.0.27)

The above steps will allow the pi to run "headless" which means you won't need to type on this keyboard again and there is also no need for a video monitor anymore. We will be logging in thru the network via a secure SSH connection going forward. The above command causes the SSH server to launch automatically every time the pi is powered on. This is convenient for us while we are coding but it could be a security risk later (being paranoid is good) so when you are ready, you can disable this auto start SSH feature using this command:

sudo systemctl disable ssh 

This command should be typed at the keyboard connected to the pi of course.

PuTTY is a terminal program which is required to issue commands from the PC to the pi so you should grab the latest copy from here.

Install and start up PuTTY. You will need to type in the IP address from above at the Host Name entry and use the default SSH settings. Give the session any name you want and hit save. Then hit load and click OPEN to start a session.

It should get you to the login screen for the pi. Use your same username and password that you used earlier.

Now, the only thing we need to install after this would be the pigpio library and we can do this by using the following commands.

Tip: You can simply copy [ctrl+c] and paste [mouse right click] these and any other commands into the PuTTY terminal

sudo apt-get update
sudo apt-get install pigpio python-pigpio python3-pigpio

So here's a tip that may help save some time in your code development world. We really hate the unix based text editors. The user interface is normally clumsy and the fonts suck. GNU nano is almost bearable but none are as refined as SublimeText that you can download from here

We have a windows based development environment and love to use this text editor whenever possible. So the tip here is in setting up your system to be able to use this professional text editor natively on your windows desktop to directly code on your headless pi.

How? Using a free app called WinSCP that you can download from here

WinSCP is a secure file transfer program that gives a graphical representation of the files present on your rpi kind of like what you see in file manager on your windows PC.

So go ahead and install the above two programs as well now.

Next you will have to make a few adjustments to make them all work properly.

For WinSCP, you can click on NEW Site. We will use the default SFTP settings and you only need to enter the IP address (for Host name) of your pi and the login name (for User name). You can choose to leave the password empty if you like - it will prompt you for the password each time you login.

Next, click the Advanced button and then click on the left side for Environment Shell settings. On the right side change the "Default" pull down to the "sudo su -" option. This will allow changes to be written to your pi without permission errors when you hit save from SublimeText.

Set SublimeText to be Default Editor in WinSCP

To do this, click the Tools button on the WinSCP Login settings screen where you started your NewSite dialog. The two screen shots shows how this is configured, but basically you will click to configure the Editors preference and Add an Editor which will be an External editor. You can then browse for the .exe file of where this editor is located on your computer.

Once done, go ahead and login with WinSCP and with PuTTY.

Now we're all set we can start our tinyLiDAR code.

Make a directory called tinyLiDAR under your home/pi directory.

You can do this by doing a right click on the right side of the WinSCP screen and choose New / Directory.

Now at the PuTTY terminal you can type

cd t 

and press tab to let it autocomplete your command to get to the tinyLiDAR directory.

Once here type the following:

wget https://microelectronicdesign.s3.amazonaws.com/rpi_tinyLiDAR_TerminalGui.zip

to get the files directly from our server. We can then unzip them by typing

unzip r 

and press tab to autocomplete the name again

To run it, just type

python tlgui.py

And your tinyLiDAR will be responding to your every command on the pi :)

Go ahead and have a look under the hood by double clicking on any of the code files from WinSCP. They are the ones with a .py extension. The files should open up in SublimeText directly on your PC. Change whatever you like and then hit save. Your changes will be saved directly to your pi.

When ready, you run it again by using the up arrow key for the last typed command or just type it in again and press enter:

python tlgui.py

You may have notice the Terminal GUI layout looks a bit nicer than the Arduino version. It's because PuTTY supports unicode characters, so we were able use some extra cursor control characters to make it look more refined.

There's also an added command here (compared to the Arduino version) which is "dc" for the Continuous Read function. Try it out and see what you think.

That's all!

Thanks for reading and enjoy hacking on the pi :)