Build a Rhizotron! (SoilCam)

25OCT2017 - Thanks to Dušan for the suggested changes:
- Using an SD Card preinstalled with NOOBS doesn't necessarily make this process easier.
- sudo apt-get command for installing much of the software was no longer working. This has been updated, please let me know if it doesn't work (in step 3)

This guide is for anyone who has ever rolled over a log to see what lies underneath. What happens when you're not looking? Watch the video above, then dig in (hehe) to this guide and build your own Rhizotron* (SoilCam)!

How does one capture video underground? Waterproof and bury a normal document scanner. Combine a Raspberry Pi Computer and a few amazing software tools to automate the scanning and creation of a time-lapse video!

The Raspberry Pi uses a Linux Operating System (Raspbian), an OS that it and much of the software written for makes automating tasks much easier! If you have never used the Linux OS, or don't feel terribly comfortable with technology fear not! The Pi is designed to make learning easy, you may want to spend some time reading up on the Pi, the terminal, and various linux commands before proceeding. The videos in the following steps are intended for people new to Linux. For those already familiar with, you can probably skim through the pictures.

Like all things in life, you can almost always find help and inspiration with projects like these at your local makerspace / hackerspace!

Cost (Next step covers materials in depth)
$0 - $150, depending on what equipment you need to purchase.

Power & Placement
Where will you setup? If outside, how will you get power/data to it? Check for existing Phone line or Cable access holes. If inside, you can use a large dirt filled pot or 5 gallon bucket located near a power outlet.

Time
The build takes a few hours, but once complete capturing enough data to make longer videos can easily take days, weeks, even months!

Why watch soil?!
Nearly a third of the world's living organisms exist within the soil, and almost none of them have been identified or recorded! It's a huge mystery down there that's full of life, death, procreation, and decomposition. So much of it happens on such a small physical scale and large time scale that capturing it can be difficult. If you've watched the intro video, some of the footage is played back well over 10000x the speed it normally happens!

I would love to see a SoilCam up and running in your yard, beach, bog, tundra, dune, etc. There's a whole world that's almost completely unexplored. Build one, and please share your images and videos!

Click on the next step to start building, or check out http://soilcam.blogspot.com for more footage!

- Josh

* Rhizotron? What an AWESOME word. "Rhizotron (from Ancient Greek: rhízōma "mass of roots", from rhizóō "cause to strike root") is a laboratory constructed underground in order to study the soil and its interactions with plants and animals" - wikipedia

Material List
- $40 Raspberry Pi (Tested with Model B, and Model B 2, 3 should work fine)
- $15 SD Card (Class 10: 16 or 32 GB.)
- $16 Powered USB Hub (Tested with a 4 Port Plugable)
- $10 Ethernet Cable (Tested with Ethernet, WiFi should work fine)
- $25 Scanner (see details below)
- $2 USB Cable for Scanner
- $2 Flathead Screwdriver (Optional, it's only used to pry scanner lid off)
- $10 Aquarium Grade Silicone (No anti-fungal properties)
- $15 Neutral Cure Silicone (optional)
- Plastic Spoon, or something to help smooth out the silicone
- Toothpicks, or something to help get silicone into the cracks
- $1 Rubbing Alcohol
- $1 MicroFiber/Lens/Non Scratching Cloth
- 4 x Clothes-pins (something to use as temporary stand-offs)
- Paper Towels
- Small Shovel (Optional, your hands may work fine)
- Bucket / Pot that can hold the scanner + dirt (IF you're burying this inside)
- Thin sheet of cardboard size of scanner (Cereal box backs work great)

What Scanner to Purchase?
This guide is written for a Canon Lide 20, 110, or 200/210. With a minor modification you can get it working with almost any SANE compatible scanner. See this link for a list of scanners that will likely work, and check the last two pages of this guide for some info on making minor modifications. Please note that of the ~8 scanners I have buried, all died within 6 months (approximately 18,000 scans). Half of them died within a few weeks.

What Scanners to Avoid?
If it's not listed/or incompatible in the prior link you should avoid it.
If it's one of the bigger multi-function scanner/printer/fax/copiers, avoid avoid!
I've avoided non-usb powered scanners due to higher power/voltage concerns.

New or Used? Where to Buy From?
I prefer used, but that comes with a risk of reduced longevity.
Ebay, Craigslist, Amazon, Nextdoor, Freecycle, Family are all great sources.

Silicone, what to get?
Silicone (used in bathrooms/windowsills, not "silicon" as in silicon valley/integrated circuits;) comes in a few different forms. I've primarily used Aquarium Sealant Silicone which does not contain any of the anti-fungal properties that the silicone used in your bathroom does. Fungus plays an important role in nature that we don't want to interfere with. So purchase this if you can! We do use a very tiny amount of Neutral Cure (non-acid curing) silicone for this project, and you can feel comfortable using the Aquarium stuff in its place if you'd rather save the money!

Before we tear apart our scanner and cover it in silicone let's make sure it works. The pictures above cover the steps on a Mac. The process is very similar if you are testing on a Windows machine.

If you are testing from your Raspberry Pi you should get SANE/ScanImage up and running, follow the next couple steps in this instructable (not the images above) to get your Pi communicating with your Scanner, then come back here and finish the testing.

Running a quick test with your scanner
First make sure your scanner works as it normally should. Testing 'new' scanners on a Windows or Mac OS computer is generally easy:
- Plug the (hopefully USB) cable in from your Scanner to your Computer.
- On a Mac, click on the Apple Menu and choose "System Preferences", then open the "Printers & Scanners" utility. Now double click on the scanner. If this does not work for you, go to the manufacturers web site and download their scanner software.
- On a PC, click on the Start Menu/Bar and search for "Scan", open the utility "Windows Fax & Scan". Once it opens, click on "New Scan" and then "Preview". If the software can not find your scanner, go to the manufacturers web site and download their scanner software.
- Scan something! Hand, Magazine, Book, etc. to make sure everything is working.

Older scanners (Lide 20) may require installation of SANE to get working. You can install SANE on Windows or Mac, or you can continue with the next two steps of this guide and do test with your Pi.

Testing scanner in funky positions
Most scanners are intended to be placed on a flat level table.
- Not buried underground.
- Not with 50 lbs of weight resting on them
- Not oriented in a vertical or horizontal position

This guide covers mounting the scanner in the vertical (portrait) position. Before burying, run some additional tests to see if the scanner will work in similar positions:

- Laying Flat with added weight. Try adding a few heavy books on top.
- Lean scanner (without weights) against a wall vertically (portrait).
- Lean scanner (without weights) against a wall horizontally (landscape).

If you hear loud clicking noises, or sounds that you did not hear while running the scanner normally, remove the weight and/or lay the scanner back flat down. If it fails any of the above tests, it does not mean things aren't going to work, but you will have to test/play to figure out how you may orient your scanner so that it will work.

The initial video is a detailed breakdown of almost everything for getting a headless Raspberry Pi setup on a Mac. If you just want a brief overview skip ahead to the pictures. But first:

Read through the Material List, Time Requirement, and Quick Notes before proceeding, especially if you are new to linux! Commands can be copied from the steps below. Not on a Mac? Try using the video, images, and steps below as a guide. You should be able to find instructions specific to your OS in the links.

Material List
- Internet connected computer to download OS
- $40 Raspberry Pi (Tested with Model B, and Model B 2)
- $15 SD Card (Class 10, 16 or 32 GB preferred)
- $16 Powered USB Hub (Tested with a 4 Port Plugable)
- $10 Ethernet Cable (Tested with Ethernet, WiFi will work as well)

Time Requirement

10-20 minutes of actual work, and about 1-2 hours with waiting.

Quick Notes
Headless? That usually means you are running a computer without a dedicated Keyboard, Mouse, or Monitor. This guide covers running a Raspberry Pi 'headless'. If you do have a keyboard/monitor/mouse connected and can follow this guide from your Raspberry Pi, skip over step 5 below, no need to use SSH.

If you want to spend a little extra money and save time, it may help to purchase an SD Card with Raspbian already installed, then follow the directions here, starting with the "First Boot" section. When done, return to the video at the 10 minute mark, or step #9 "Update your Raspberry Pi's OS & Software" below. You may still need to follow step #4 to get your Pi's IP address.

Starting from Scratch

Where you see the "#" symbol, copy the text AFTER that. For shorter commands, get comfortable typing them out! For longer commands, copying and pasting may be better.

1. Download the Raspbian OS via the Raspberry Pi downloads
   1. Don't use the lite edition. Torrent or Zip? Zip if you are unsure.

   Follow the Raspberry Pi installation guide to:
   1. Unzip the downloaded file
   2. Write the Raspbian .img file to your SD Card

2. Connect your Pi
   1. Insert SD Card
   2. Connect ethernet cable to Pi & your Router
   3. Connect Power to Pi to boot up.
3. Get the IP address of your Raspberry Pi, follow these instructions
   
   
   
4. If you are running your Pi headless, connect to it via ssh. Make sure to read section 3 about enabling ssh on a headless Pi!
   
   1. username: pi
   2. password: raspberry
5. Setup the basics with the command:
   
   1. # sudo raspi-config
      1. Expand the File System
      2. Change user password
      3. Boot to Console or Desktop (this guide uses just the console)
      4. Internationalization Options (Locale, TimeZone, Keyboard Layout)
      5. Finish/Exit and Restart
6. What is "sudo", see here
   
   
   
7. Log back in to your Pi
   
   
   
8. Update your Raspberry Pi's OS & Software
   1. # sudo apt-get update
   2. # sudo apt-get upgrade
   3. For more instructions/info, read here
      
      
      
9. Download a bunch of software to install Apache2, SANE, ImageMagick, and av-tools with the command:
   1. # sudo apt-get -y install apache2 sane sane-utils libsane-extras imagemagick libav-tools
   2. Apache2 is very popular web server platform. We use it so you can easily access images and videos taken with your Scanner
   3. SANE is a wonderful software project that makes it easy to connect to thousands of different scanners, many no longer supported by their manufacturers.
   4. ImageMagick is a crazy extensive suite of programs allowing you to create and manipulate images. We use it to convert, resize, and timestamp our images.
   5. AV-tools is similar to ImageMagick, but intended for video processing. We use it to combine the images we capture into a time-lapse video.
10. Verify Apache2
    1. Type in the IP address of your PI into a web browser. A web page loads that says "It Works!"
11. Make a web directory accessible to the Pi user account
    1. # cd ~/
    2. # mkdir public_html
    3. # sudo a2enmod userdir
    4. # sudo service apache2 restart
    5. You have created a directory (folder) in your Pi's home directory called "public_html", the a2enmod userdir command allows the apache2 web server to serve pages from that directory
12. Test that this works, type http://your.ip.address/~pi/ into a web browser.
    1. It should load an empty directory.
13. Add the "pi" user to the scanner user group by running the command:
    1. # sudo usermod -a -G scanner pi
    2. This allows the user "pi" to access a scanner without using the "sudo" command.
14. That's all! If you want to shutdown your raspberry pi, type the command:
    1. # sudo shutdown -h now

You're done! Next step, we will install and automate a simple script to scan images, timestamp and generate videos using the images.

The initial video covers in detail how to setup your Pi for Scanning. For a quick overview see the pictures immediately after it. But first:

Read through the Material List and Time Requirement before proceeding. Commands can be copied from the Basic Steps section below.

Material List
- $40 Raspberry Pi (Tested with Model B, and Model B 2)
- $15 SD Card (Class 10, 16 or 32 GB preferred)
- $16 Powered USB Hub (Tested with a 4 Port Plugable)
- $10 Ethernet Cable (Tested with Ethernet, WiFi will work as well)
- SANE Supported Scanner (Canon Lide 20, 110, 200/210 confirmed working)
- USB Cable to connect Pi to Scanner.

Time Requirement
- 20 - 30 minutes

Quick Notes
Not much to say yet. This should be pretty straight forward (famous last words...)

Basic Steps
Where you see the "#" symbol, copy the text AFTER that. For shorter commands, get comfortable typing them out! For longer commands, copying and pasting may be better.

1. Connect Hub to Pi, Ethernet to Pi, Power to Pi, and Scanner to Hub
   
   
2. If you haven't done so already, log out and log back in to your Pi.
   
   
3. Download the SoilCam Script using git
   1. # cd ~/
   2. # git clone https://github.com/SoilCam/SoilCam.git
      
      
4. Read the SoilCam Readme
   1. # cd ~/SoilCam
   2. # cat README.md
5. Run the script
   1. # ./soilcam.sh
      1. Read the usage info. The dash followed by a letter (-u, -t, -v, -s, etc.) are commands that we can send to the scanner script.
         
         
6. Run the script to scan!
   1. # ./soilcam.sh -s
      1. It will ask you if you want to create some directories, answer "y"
7. If it fails to create the directories, asking you to create a directory, do so:
   1. # mkdir ~/public_html
8. Run the script to try again!
   1. # ./soilcam.sh -s
      
      1. An older scanner may take a couple minutes to complete the scan, and some scanners may require a reboot and/or logging off and back in before being recognized.
9. If the scan fails, see the troubleshooting section (last step in this guide)
   
   
10. See if the image was saved
    1. # ls ~/public_html/images/original
       1. This is the (mostly) unmodified jpg. Full resolution, no timestamp.
       2. This will stay until you delete/move it.
    2. # ls ~/public_html/images/processing
       1. This is a lower res timestamped image.
       2. It will be used for generating a timelapse video and then deleted.
11. Check the web server to see if the images are visible:
    1. Point a web browser to http://your.ip.address/~pi/
       1. Check the images/original and images/processing directories
12. Make another scan! Shift the object on the scanner first.
    1. # ./soilcam.sh -s
13. Check the web server to see if the new images are visible
    1. Point a web browser to: http://your.ip.address/~pi/
       1. Check the images/processing directory
14. Generate an amazing two frame video out of these two scans!
    1. # ./soilcam.sh -t
15. Check to see if the video was created:
    1. # ls ~/public_html/videos
16. Browse to: http://your.ip.address~/pi/videos
    1. You should be able to play this video in your browser
17. Difference between -t and -v
    1. ./soilcam.sh -t creates a video, but does NOT delete the temp images
    2. ./soilcam.sv -v creates a video and then deletes the temp images
       1. I use this command to generate a video (see next section) after 24 hours have passed. One the video has been made the resized/timestamped video is deleted, but the originals are still safe.
18. Automate using CRON
    1. # crontab -e
    2. Choose option 2 for Nano, unless you know how ed or vim work.
    3. Use the down arrow to scroll to the bottom
    4. Type: */15 * * * * /home/pi/SoilCam/soilcam.sh -s
       1. Runs the soilcam script every 15 minutes (0, 15, 30, 45)
       2. Saves two images, one in /original and one in /processing
    5. Hit enter to go to a new line
    6. Type: 5 0 * * * /home/pi/SoilCam/soilcam.sh -v
       1. Runs the soilcam script 5 minutes after midnight every day
       2. Generates a video out of all images in /processing
       3. Deletes all images in /processing/ after video is processed
    7. Hit Ctrl-X, and then Y to confirm yes to save.
       1. Hit enter to save with the existing name.
19. Check cron jobs
    1. # crontab -l
    2. You should see the same file you just edited, this command just reads it out.
20. Check the date/time
    1. # date
21. Wait until the time hits either 00, 15, 30, or 45 minutes after the hour.
    1. The scanner should start running at those time periods.

Once you've verified that these test images are working, you can use the 'rm' command to delete any images or videos. For more information on the 'rm' command many others, see the raspberry pi site here: https://www.raspberrypi.org/documentation/linux/usage/commands.md

You're done with the scripting part, next up we need to seal our scanner! Shutdown your Pi if needed (sudo shutdown -h now)

Head's up, this will probably ruin your scanner! At least for normal use.

The video quickly covers the entire process in time-lapse mode, the pictures after summarize the video. Read through the Material List, Quick notes, and Safety section below. Check the steps at the bottom if needed.

Material List
- Scanner (Lide 20, 110, or 200/210 Tested)
- USB Cable to connect Scanner to Pi.
- $2 Flathead Screwdriver (Optional, it's only used to pry scanner lid off)
- $10 Aquarium Grade Silicone (No anti-fungal properties)
- $15 Neutral Cure Silicone (optional)
- Plastic Spoon, or something to help smooth out the silicone
- Toothpicks, or something to help get silicone into the cracks
- $1 Rubbing Alcohol
- $1 MicroFiber/Lens/Non Scratching Cloth
- 4 x Clothes-pins (something to use as temporary stand-offs)
- Paper Towels

Quick Notes
We use two types of Silicone here. The super important one is the Aquarium Grade Silicone. A lot of the silicone you buy has anti fungal properties (intended for use in bathrooms). We don't want to kill off fungus, so let's avoid using that. The other silicone "Neutral Cure", other wise known as "non acid curing" is only used on the base of the USB plug where it connects to the scanner. "Acid Cure" Silicone may react with the metal of the USB plug. It's such a small amount it's hard to justify spending $10, and it will probably be fine if you use the Aquarium Grade for this.

Safety
1. Read over the directions for your Silicone. Safety First, follow their directions!
2. Snapping the lid off your scanner could result in sharp flying plastic pieces. Safety glasses are pretty awesome.

The Process
The video is a much better medium for understanding what's going on here, but the basic steps are:

1. Open the windows! Ventilation is good.
2. Lay Paper Towels down below where the scanner will sit.
   1. Don't get silicone stuck to your work table : )
3. Open the lid of your scanner.
   
   
4. If needed, use the flathead screwdriver to gently pry off the lid.
   1. Some scanners don't require prying, check first!
5. Check for cracks, openings, screws, etc.
   1. Take a close and careful look all around your scanner. Any space where water can get in, we need to seal with silicone. If there are any large gaps, you may need more than just silicone.
6. Clean the scanner off with a bit of rubbing alcohol and cloth.
   
   1. This will help with silicone adhesion. Clean it good!
7. Check the locking mechanism
   1. Some scanners have a lock that holds the scanner in place
   2. Make sure that it is in the UNLOCKED position
8. Seal all front/back/side edges with Aquarium Silicone
   1. Use the spoon to smush in and smooth out Silicone
9. Seal the USB Plug where it attaches to the Scanner
   1. Place a bead of Neutral Cure silicone around the plastic end of the plug
   2. Insert plug into Scanner
   3. Use toothpick to push Silicone down in and around the plug
   4. Clean up with Paper Towel
   5. Fill in rest of the receptacle with Aquarium Silicone
   6. Clean up with Paper Towel
10. Seal the bottom of the scanner
    1. Screws, Locking Mechanism, etc.
11. Place a few of the standoffs down on your table
    1. Space them so the silicone on the bottom of the scanner will not touch
12. Flip the scanner over so the top glass is facing up
    
    
13. Seal the point where the glass meets the plastic
    
    
14. Seal any remaining cracks/holes on the top
    
    
15. Double check sides/back/front/top for any missed points.
    
    
16. Use rubbing alcohol and cloth to clean off any excess silicone on the glass
    
    
17. Let cure overnight (Or what the Silicone Instructions recommend)

Wash hands if needed!

Next up: Burying your scanner!

If burying outside, mark off the area so someone doesn't step on it!

The video quickly covers the entire process in time-lapse mode, the pictures after summarize the video. Read through the Material List and Quick notes before proceeding. Check the steps at the bottom if needed.

Material List
- Scanner with USB Cable Attached
- Fully Configured Raspberry Pi w/SD Card
- Network Cable for Pi, connected to Pi + Internet
- Powered Hub connected to Pi
- Power Supply for Pi, connected.
- Small Shovel (or hands to dig)
- Somewhere or something (bucket) to bury the Scanner in : )
- Thin sheet of cardboard, ~same length/width of scanner

Quick Notes
- Before burying, remember to check how you're getting Power to it.
- If burying outside, be aware of people who may step on it, mow the lawn, etc.
- - Seriously. There's a lot of glass here, you don't want that in someone's foot!

The Process

1. Run a test scan with the Pi, is the scanner still working?
   1. # cd ~/SoilCam/
   2. # ./soilcam.sh -s
2. Dig a hole for the scanner:
   1. An inch or two wider than the scanner
   2. An inch or two thicker than the scanner
   3. As deep as you want it to be
3. Place the cardboard sheet over the glass of the scanner
   
   
4. Place the scanner into the hole
   
   
5. Run another test scan
   
   
6. Loosely fill in the space around the scanner about halfway up with soil
   1. Do not compact soil
      
      
7. Run another test scan
   
   
8. Fill up the hole until the glass is buried
   1. Do not compact soil
   2. The top of the scanner and the cardboard sheet should be visible
9. Remove the cardboard sheet.
   
   
10. Run a final test scan
    1. Check the test scan. Hopefully you see beautiful things!
11. Add more soil if appropriate, do not compact soil!
    
    
12. Problems? See the next few pages of this guide for troubleshooting.

That's it. If you finished the automation part of the prior step you should be generating a new image every 15 minutes. If you don't want to wait that long, continue running scans with the "./soilcam.sh -s" command. Just avoid trying to start a scan close to the automated time.

Next step: There are a few things we can play with. Using ImageMagick to zoom in on certain areas of images, combining videos, and some tips on using alternate scanners. See the next page for details!

If you get a SoilCam up and running I would love to see the results! Shoot me an email: joshdont@gmail.com or make a post here in the comments.

Flip / Flopping images vertically or horizontally

The Scanning part of the script

Auto combine videos

Manually combine videos

Higher resolution images

Failed to Scan Problems

Software Info

Sharing Videos

Flip / Flopping the image vertically or horizontally

Are your images flipped upside down, or flopped horizontally?

Connect to Pi / Login
# cd ~/SoilCam/
# nano soilcam.sh -c
Hit "Ctrl W" to search for a word, type "scanimage" then hit the enter key.
Scroll to the right, look for the text "-flip" and "-flop"
"-flip" flips the image vertically
"-flop" flops the image horizontally

If your image is upside down in your scan, remove the "-flip" command, then
Hit "Ctrl-X" to save, hit "y" to confirm, and hit "enter" to confirm the file name and exit.

What part of the script starts the scan?

/usr/bin/scanimage --mode Color --format tiff --resolution 300 -x 210 -y 295 | /usr/bin/convert -flip -flop - $imgloc1/$file

We first run the program scanimage, this is what communicates with our scanner. We tell it we want it to make a color scan in the TIFF image file format. We specify a resolution of 300 lines per inch, and the region we should scan should extend 210 mm on the X axis (side to side), and 295 on the Y axis. (Top to bottom of scanner). After that we pipe (send) the data (image) from the scan using the "|" character to the software tool "convert", where we tell it to flip the image vertically, flop it horizontally, and finally save it as a jpeg. The $imgloc1 text is a variable that when the script runs is replaced with the directory we want to save the image in (~/public_html/images/original). The $file text is another variable that gets replaced by the prefix "sc_" followed by the current date and time.

Automagically Combining Videos

Daily videos can be combined into a monthly video by running the command:

# ./soilcam.sh -c

This command is intended to be run daily, and will work well if you either schedule it as a cronjob (crontab -e), or modify the soilcam.sh script to call the combinevideo function at the end of the processvideo function.

What -c does: Looks for any file in the ~/public_html/videos/ directory starting with "sc_" (thus ignoring any temporary video files you created), followed by yesterday's date in year/month form. For example: if today is May 24th, 2016, it will look for any file matching sc_201605*.ts. This works well if you are running the process daily. However if videos aren't combined for a few days into a new month, the script will not go back and compile videos from a prior month. (see the next section for manually combining)

Monthly videos are stored in the directory ~/public_html/videos/combined/

Daily *.ts files are deleted when this command runs! It will NOT delete the .mp4 files.

Manually Combining Videos

# cat filename1.mpeg.ts >> filename2.mpeg.ts

This will combine two of the mpeg.ts files. Cat "concatenates" one file to another, adding the first file called to the end of the second file. We use the .ts format because it works well with this behavior. I do not believe the same operation will work with a .mp4 file. But .mp4 files are easy to play on almost any modern computer! So we need to change the final format of our combined file by typing:

# avconv -y -isync -i filename2.mpeg.ts -c copy filename2.mp4

What if you want to combine a whole directory of files? A simple for loop usually works well, and is utilized in the soilcam.sh script. Check out the soilcam.sh file for an example of this. Scroll down (almost to the bottom) and look at the "combinevideo" section. See this link for more info on for loops

Higher Resolution Images

Following these instructions may break the soilcam.sh script, though should not be difficult to fix : ) I haven't tested this with the latest version of the script : )

I've found that scanning at 300 DPI works well, but there's so much more you can see if you can scan at a higher resolution! First, see what resolutions your scanner supports by typing

# scanimage -h

That will report back a bunch of commands that scanimage and your specific scanner support. Keep in mind:
- Most scanners only support a few specific resolutions, for example: (150, 300, 600, 1200, 2400).
- Higher resolution scans take longer to scan, which means quicker moving objects will become more blurry.
- Higher resolution scans use more disk space. A single 300 DPI (dots per inch) JPG image may take up 3 or 4 Megabytes of data. Not a lot unless you take a scan every 15 minute for a month straight. That's approximately 8 Gigabyte of data. Now you see why we want a larger SD Card ; ) A 600 DPI scan could easily take up 4x this amount!

Ready to change resolutions? Open up the soilcam.sh script in your favorite editor.

# nano ./soilcam.sh

Hit Ctrl-W to search for the term "scanimage" and then hit enter

Use the right arrow key to scroll over until you see the text "--resolution 300", change the "300" to your desired resolution.

Hit Ctrl-X, then Y, then the Enter key to save and exit.

Troubleshooting / Different scanner / Script fails to start a scan

First, find the scanner on this page, make sure it's listed as compatible. If it's not listed there, do a google search for your scanner model and "linux" or "scanimage". See if other people have had success.

If you do find that it's compatible, but the soilcam.sh script is failing there are a few quick things we can check.

1. Type "scanimage -L", if no scanners were identified, check the next two items.
3. Is the USB cable plugged in to your scanner?
4. Is the USB cable then plugged into a powered usb hub, which is then connected to your Pi?
5. Is the scanner turned on (most USB only scanners do not have on/off switches)
6. Type "sudo scanimage -L".
- If this works, try running the script with sudo: "sudo ./soilcam.sh -s"
- - If that works, try adding the pi user to the scanner group again "sudo usermod -a -G scanner pi"
7. The command we use to initiate a scan may contain arguments that are not compatible with your scanner. We currently run the command: "/usr/bin/scanimage --mode Color --format tiff --resolution 300 -x 210 -y 295"
- type "scanimage --help" to get a list of valid commands for your scanner.
- Check for:
- - "--resolution" We set to 300, some scanners may not support this resolution.
- - "--mode Color" Some scanners may not support this command.
- - "-x" and "-y", set at 210 and 295 respectively. Some scanners may not support this command, or may be unable to scan out to 295mm

Scanimage
We use SANE (Scanner Access Now Easy) to communicate with our scanners. You can find information about SANE here: http://www.sane-project.org/docs.html, or by typing "man sane" or "man scanimage". The name of the program we use is called "scanimage". Learning a few basic commands for scanimage (type "scanimage -h" in your terminal) will allow you to to make higher resolutions scans, scan specific areas, etc.

ImageMagick
Is a suite of image editing programs, more information on this can be found here: http://www.imagemagick.org/, or by typing "man convert". We primarily use the tool convert (type "convert -h" in your terminal) to resize and place a timestamp on the image. It's capable of much more!

AVConv / AV-Tools
Is a suite of video processing programs, we are using it to process jpg images into a timelapse video. More information on the software can be found here: https://libav.org/avconv.html, or by typing "man avconv"

Sharing Videos

It would be great to share your images or videos, and there's an infinite number of ways to do this. So far I've been uploading videos to youtube and tagging them with the word "SoilCam". You can easily use a web browser to manually upload videos from your Raspberry Pi to Youtube. But there are a number of programs that can do this in a more hands off way. So far I've been using the youtube-upload script:

1. Head over to: https://github.com/tokland/youtube-upload
2. Follow their instructions to download and install
3. Follow their instructions to setup the appropriate Authentication information
4. Use the command "./soilcam.sh -u" to upload the video that was processed yesterday (this will not work if you try this the first day you have your scanner setup), and the first time you run this command it will have you goto a URL to further authenticate. I am not super clear on this part, you may have to do this again from time to time.
5. After you have confirmed that the manual process works. Use CRON to upload the prior days video automagically. Type "crontab -e" in your terminal to open the cron editor. Add the command "15 0 * * * /home/pi/SoilCam/soilcam.sh -u" at the end. This will run the upload part of the script every day 15 minutes after midnight.
6. You will likely want to edit some of the description / title information:
cd ~/
nano soilcam.sh -c
hit "ctrl-w" to start a search, look for "youtube-upload" hit enter. Then hit ctrl-w and enter again.
Modify the title, category, tags, and if needed credentials/secrets fields.
hit "ctrl-x" to save, hit "y" to confirm, and hit "enter" to save with the same file name and exit.

Sharing Images

TBD! If you post them on any social media, tag them #Soilcam ? : ) I haven't shared much of the original images. I've briefly stored some on google drive and S3. Possibly imgur? Hmmmm. What do you think?

Lots of things to think about!

How will you control it?
There's great support for a huge number of scanners using SANE (free) or VueScan. Check to make sure your control software/hardware is compatible with the scanner you intend to use.

CIS or CCD based scanner:
CIS can only scan items within a mm or two of the platter, require less power, bulk, and are generally cheaper.
CCD can scan a few mm away from the platter, require more power, bulk and $

Older Scanners, USB, SCSI, Firewire?
Most scanners made in the last decade provide data and power via USB. Older USB 1.0 scanners will typically scan and transfer data VERY slowly. Non USB scanners may prove difficult to connect to modern equipment. The Raspberry Pi does not have a Parallel, SCSI, or Firewire port

Power
5v? 120v? How will you get power to it? What will provide the power? Will you be running the power inside, outside? Running power outside can be dangerous!

Positioning
Most of these scanners are designed to work flat on your desk. What happens when you turn it on its side? Landscape, Portrait? Some will scan fine, others will make terrible noises and the gearing will not function properly to move the scanner

Will it Crush?
There's a LOT of pressure underground, and it will likely only increase over time! How much pressure before the scanner deforms and can no longer scan?

Scanning Resolutions
There are scanners out there that support up to 9600 lines per inch, that's incredible! Keep in mind that (usually), this is intended for scanning film (a very small area), and that a 9600 DPI image takes up a TON of space.

A ton of people helped make this instructable a reality.

Linux! Trying to do this on certain more popular platforms would have required much more work.

Open Source Software powers most of this project and makes life much easier and more affordable. Thanks ImageMagick, AVConv, SANE, and BASH!

The Raspberry Pi also makes this project easier, more affordable, and requires much less energy than a typical computer.

Larry Works donated the first scanner for this project!

All Hands Active for providing so many great resources. Hackerspaces are amazing places!

Maker Works for the same reason. Seriously, check out your local hacker/makerspace if you haven't already.

Alec! helped review an old version of the soilcam script and provided a million pointers that helped simplify things significantly.

David Scheltema provided much encouragement to build a guide.

Alan McWaters gave much insight on waterproofing, and more on a possible heavier duty version of this.

Nicole, who welcomes these activities in her own backyard : )

John for providing the first Raspberry Pi!

Books! The World Beneath our Feet is a wonderful book that just scratches the surface (teehee) of how amazing soil and its inhabitants are.