Botanicalls

The following instructions for Botanicalls Twitter DIY were published in February 2008. For updated instructions and information about the new Botanicalls Kits, please visit the Botanicalls Kit page.


Botanicalls Twitter answers the question: What's up with your plant? It offers a connection to your leafy pal via online Twitter status updates that reach you anywhere in the world. When your plant needs water, it will post to let you know, and send its thanks when you show it love. 

Twitter is social software that asks a simple question: What are you doing?

Botanicalls is a system that was developed to allow plants to place phone calls for human help. When a plant on the Botanicalls network needs water, it can call a person and ask for exactly what it needs. When people phone the plants, the plants orient callers to their habits and characteristics. Call 212.202.8348 to hear more about each of the plants.




WHAT YOU NEED


(1) awesome plant

(this is an ornamental pepper grown from seed)

PARTS:

(1) 2N2222A or 2N3904 transistor
(1) 100 Ohm resistor

(1) 10K Ohm resistor

(1) LED

(2) galvanized nails, preferably hot dipped

(1) small breadboard

(1) Adafruit XPort shield

(1) XPort or XPort Direct

(1) Arduino USB board

(1) 9V DC power adapter

hook up wire  in assorted colors

solder

USB A to B cable

USB A to miniB cable

USB Serial FTDI adapter (optional)

Ethernet cable

EQUIPMENT:

soldering iron

helping hands

computer with ZTerm or HyperTerminal and Arduino
Twitter account


MOISTURE PROBES
You will need 2 nails that will act as soil moisture probes. You can use any kind of conductive nail that you have lying around, but we recommend using galvanized, hot dipped nails, which are more resistant to corrosion.

    

-Wrap the wire around the nail and be sure to take the time to heat up the nail as opposed to just heating up with wire and spreading the solder on the wire alone.  This prevents the wire from fusing with the nail and provides an opportunity for the wire to slip off of the nail.

-You'll know that the wire is hot once you touch the solder to the nail and it begins to flow. 

-Work your way around the entire nail connecting the wire.


Note: We are still looking for a better metal that doesn't degrade because of electrolysis.  If you have any suggestions please shoot them our way.




WIRING
Connect the Arduino's 3.3V power and ground to both buses of the breadboard.

Connect 3.3V power to the AREF pin on the Arduino. This provides a reference voltage for the moisture sensor.
Connect the positive leg of the LED to Arduino digital pin 13. The negative (shorter) leg of the LED connects to the ground bus.

Soil moisture sensing (transistor) circuit connected to XPort shield. The transistor has three leads coming out of the bottom they are called:

1: emitter
2: base
3: collector

It's important that each lead is connected properly, so take care with this step and double-check your setup befor applying power to the circuit. The emitter is connected to Arduino analog pin 0, and also via a 10K Ohm resistor to the ground bus. The base is wired to  one of the moisture probe nails. The other moisture probe nail is connected via a 100 Ohm resistor to the 3.3 V power bus. Finally, the collector pin of the transistor is connected directly to the 3.3 V power bus.
transistor

transistorUse this schematic to help understand the moisture circuit connections.


Connections between XPort and Arduino Shield:

XPort TX to Arduino digital pin 3
XPort RX to Arduino digital pin 2
XPort Reset to Arduino digital pin 4
XPort DTR to Arduino digtal pin 5
XPort CTS to Arduino digital pin 6
XPort RTS to Arduino digital pin 7

Attach and connect USB-serial FTDI adaptor for debugging. (This step is optional.) The GND pin connects to the ground bus, the RX pin connects to Arduino digital pin 1. (These photos show the TX pin connected to Arduino digital pin 0, but this connection is not required.) Do not connect anything to the 3.3V pin on the USB-serial adaptor!

You'll need to configure your XPort's Channel 1 to use Flow 02 and ConnectMode D4.
Check out the excellent XPort tutorial on LadyAda.net for more information on connecting with and setting up your XPort.

You also may want to reference the XPort User Guide on the Lantronix documentation web site.

SOFTWARE

Plug in your power supply and Ethernet cable then connect the USB cables to your computer. Your board is now set up for downloading code to the Arduino, and for seeing the debug output in a terminal program like HyperTerm or ZTerm.
Download the Arduino environment for your computer system from the Arduino site. Arduino is a free, cross-platform and open-source electronics prototyping system created and maintained by a worldwide network of physical computing enthusiasts. 
Download the Botanicalls Twitter Code Example and unzip the archive. The unzipped Botanicalls Twitter folder should be put in the Arduino documents directory (MyDocuments\Arduino on Windows or  Documents:Arduino on the Mac). It will now appear when you select Sketchbook from the File menu in Arduino.



Open the BotanicallsTwitter sketch in Arduino. You'll need to make at least one change before uploading the code:

  • Update the line that begins with #define USERNAMEPASS "username:password" with the real username and password for your Twitter account, separated by a :

You may also want to change some other settings. The Botanicalls system operates based on a variety of moisture thresholds. These will vary by plant, soil composition and even your own personal horticultural style. Start with the default values, and adjust until you are happy with the system's behaviors:

This line defines the value between 0 and 1023 below which the plant is in need of water:
  • #define MOIST 450 

This line defines the value between 0 and 1023 that defines an urgent state of dryness:
  • #define DRY 350  

This line defines the moisture value between 0 and 1023 that represents a proper watering.
  • #define SOAKED 600

Finally, this line defines the positive change in moisture level that indicates a watering event has occurred.
  • #define WATERING_CRITERIA 100

The plant's Twitter messages are defined in the "checks" tab. The Arduino has very limited RAM memory for text strings, so keep these messages very short. If they get to long you'll overflow the memory stack and the system will begin to behave erratically.

There are a variety of other settings that can easily be changed to suit your taste including sampling intervals, quantity of samples, Arduino pin connections and so forth. These are documented in the comments for each setting.

When you are ready to upload the code, select the correct serial port and board type on the Tools menu, then select Upload to I/O Board from the File menu. (You may need to disconnect the wire from the Arduino digital pin 0 that connects to the USB-serial adapter's TX port to avoid an error message. We don't use this connection in the basic example anyway.)
Once the code is uploaded, your system is ready to go. Monitor the USB-serial FTDI connection in a terminal program like HyperTerm or ZTerm with the following settings:
  • 9600 baud
  • 8 data bits
  • 1 start bit
  • No parity
  • No flow control of any kind (neither hardware handshaking or Xon/Xoff should be enabled).

When you power up the system you should see a message "Botanicalls starting..." Next you will see a series of moisture readings, interspersed occasionally with a watering detection reading. By touching the nails together, you can simulate a high level of soil moisture. By moving them apart, you will simulate a high level of dryness. Use this procedure to test the system. When BotanicallsTwitter has a message to send, you will see a series of Twitter connection messages, followed by a long string of HTML responses. A final message will let you know if the twitter message was sent successfully or not. Check your Twitter account to see if the message arrived properly. If it did, feel free to do a little happy dance–you've made a Botanicalls!


INSTALLING SYSTEM
With the system tested, it's time to hook up a plant. Neither the debug output or the Arduino USB connection is needed for day-to-day operation of the Botanicalls Twitter system, so those connections can be removed. The moisture probes made with the nails should be inserted into the plant's soil about midway between the rim of the pot and the plant. Space them about an inch (3 cm) apart. Be sure to check the nails periodically to monitor for excessive corrosion, and to make sure that the solder connections are still strong.

Now that you've got Botanicalls up and Twittering, you'll want to know what to expect. The system code provides five different status updates, based upon current conditions:
  1. When the moisture level of the plant's soil drops below the satisfactory threshold, it will send a status update that the plant needs to be watered.
  2. If the soil moisture drops below a critical level the plant will twitter that it is urgently in need of watering.
  3. Any rapid rise in soil moisture will be detected as a watering event. The plant will then determine if the soil moisture has risen to the desired level for a proper watering. If it has, then it will twitter its thanks.
  4. If a watering event occurs, but the soil moisture has not reached the desired level, the plant will twitter to report that it was watered, but not sufficiently.
  5. Likewise, if a watering event occurs, but the plant was not in need of water yet, the plant will twitter to complain that it is being over watered.

Remember to place the setup were your green pal will get the proper amount of light and to fertilize its soil on a regular basis. With proper care, your plant will be twittering away for many years to come.


***

We'd love to see how you use Botanicalls Twitter.
Please tag any photos of your setup on flickr with the tag: Botanicalls_Twitter.

If you have questions or comments,
email the Botanicalls team at: support [at] botanicalls [dot] com.


Botanicalls Twitter DIY