Overview

In the future, everything will be connected to the internet. And all restaurants will be Taco Bell!

The “Internet of Things” is the idea of pervasive connections between physical objects and the online world. These connected devices don’t just idly sit around waiting for commands or files…they’re active agents that anticipate your needs and can push or pull data from the internet.

Our Internet of Things Printer is a small, internet-connected thermal printer that can have a daily weather forecast ready before you head out in the morning, a puzzle to work on while riding the subway, provide a list of “tweets” relating to your interests…or any other task you can program!

This second version of the printer is built around the Raspberry Pi, a tiny computer that packs a wallop: more processing power, more RAM and the potent Linux operating system. The new kit has an easier time handling graphics and looks super tidy with its wireless networking:

Parts List

This list covers the current (2017-and-later) version of the kit; older kit is described on the next page.

The Internet of Things Printer Project Pack for Raspberry Pi includes the following items:

Not included with the kit, the following tools and items are also needed for assembly and setup:

  • USB keyboard (and mouse, if installing from NOOBS GUI), maybe a hub as well
  • Monitor (HDMI or composite) and cable
  • USB cable: A to micro B (for powering Raspberry Pi)
  • Small screwdriver
  • Soldering iron and solder
  • Wire cutter and stripper
  • A wireless (WiFi) internet access point
  • Desktop or laptop computer with USB, internet connection and at least one gigabyte of free disk space for downloading and uncompressing software
  • Optional: sticky tape, heat-shrink tubing

Parts List (Pre 2017)

If you have an older version of the kit (purchased before 2017) these are the contents:

The (pre-2017) Internet of Things Printer Project Pack for Raspberry Pi includes the following items:

Not included with the kit, the following tools and items are also needed:

  • 4GB or larger SD card (or microSD card with full-size adapter)
  • SD (or microSD) card reader
  • USB keyboard (and mouse, if installing from NOOBS GUI), maybe a hub as well
  • Monitor (HDMI or composite) and cable
  • USB cable: A to micro B
  • Small screwdriver
  • Soldering iron and solder
  • Wire cutter and stripper
  • A wireless (WiFi) internet access point
  • Desktop or laptop computer with USB, internet connection and at least one gigabyte of free disk space for downloading and uncompressing software
  • Optional: sticky tape, heat-shrink tubing

The SD card will remain installed in the device; the remaining parts from this list are needed only during setup.

Software Prep

We’ll deal with software first, then get into soldering and case assembly later.

The software for this project is built upon the Raspbian Lite operating system, a pared-down version of Linux for the Raspberry Pi.

The current kit comes with a card loaded with NOOBS. This can be used to download and install Raspbian Lite, but you might find it more expedient just to overwrite the card. We’ll provide directions for both approaches.

The older kit did not include NOOBS, so skip ahead to the “Overwriting” section later on this page— it’s the same as starting with a blank card.

Installing From the NOOBS Card

NOOBS has a graphical interface and requires temporarily setting up the Pi like a desktop computer. You’ll need a monitor connected, along with a USB keyboard and mouse (this may also require a USB hub). Insert the card in the Raspberry Pi, then connect a USB micro-B cable from the board’s power connector to a USB power source — a phone charger, hub, or just a USB port on your “main” computer.

When booting the NOOBS card, you’ll briefly see the “rainbow screen” — normally bad news, but it’s okay in this case — the Pi will then reboot and launch the NOOBS installer menu:

First order of business is to connect NOOBS to a wireless network so software can be downloaded. Use the “WiFi networks” icon (top center) to set this up. It’s a fairly straightforward WiFi configurator…select a network from the available list and enter a network password if required.

NOOBS WiFi supports wireless-capable Raspberry Pi boards as well as the “official” Raspberry Pi USB WiFi adapter. Not all third-party adapters are supported. If this presents trouble, you might use the “Overwriting NOOBS” directions below instead.
Installation can not proceed until a WiFi internet connection is established.

With an internet connection now made, select “Raspbian Lite” from the list of available operating systems. Do NOT select “Raspbian with PIXEL” — this contains a whole lot of software we do not need or want!

Click the “Install” icon. This will download Raspbian Lite (about 300 megabytes), install it on the SD card and (after prompting) will reboot into the newly-installed operating system. You can then skip ahead to the “Setup” page.

More information on NOOBS is available in this guide if needed.

Overwriting NOOBS with Raspbian Lite

If you have some prior experience with Raspberry Pi and Linux, you might find this approach simpler…

Start by downloading the latest version of Raspbian Lite from the Raspberry Pi web site.

Do NOT use “Raspbian Jessie with PIXEL” — this contains a whole lot of software we do not need or want! Also, if you’ve previously downloaded Raspbian Lite for other projects, check if a newer version is available. This project relies on some recent features!

Here’s a tutorial explaining how to install the Raspbian software on the SD card (replacing NOOBS), with links to nice GUI apps for Windows and Mac. The first couple of pages can be skipped, as we’re already downloading the right software for this project.

If you ever need to restore the NOOBS card to its original state, this guide explains the whole process.

Raspberry Pi Setup: 1 of 3

OS Install and First-Time Configuration

At this point it is assumed you have a bootable SD card containing the Raspbian Lite software. If not, follow the directions on the “Preparation” page.

The case should NOT be assembled yet. Let’s get the system running before sealing it up.
  1. Connect a monitor and a USB keyboard to the Raspberry Pi (a mouse is not required).
  2. Insert the SD card containing the Raspbian Lite software.
  3. Connect a micro-B USB cable to the power connector on the Raspberry Pi.
  4. Plug the other end of the USB cable into a power source: a mobile phone charger, a powered USB hub, or simply a USB port on your computer.

The Raspberry Pi should now boot, and you’ll see the monitor fill with lots of “Unix stuff.” On first boot, the system may automatically reboot once as part of the setup process. This is normal.

Linux can be daunting to the uninitiated. Don’t worry about messing something up…if all else fails, you can re-format the SD card and begin again.

Within a minute or so you should get a login prompt. Log in as user “pi” and password “raspberry”. Then enter the following command for essential system setup:

sudo raspi-config

Use the up/down arrow keys, tab and return/enter to navigate the config menu:

The following selections are required:

  • Under “Interfacing Options,” select “Serial.” Turn OFF the login shell over serial, and ENABLE the hardware serial port. NO and YES, respectively. This is vital!
  • Under “Interfacing Options,” enable SSH. This permits network access to the Raspberry Pi without a monitor or keyboard attached later.
  • Under “Localisation Options,” select “Change Timezone” and set this up for your location (a correct time zone is required for the time display and other examples to work).

The following are optional but recommended:

  • Change User Password,” because everybody knows the default (“raspberry”).
  • Hostname” to distinguish this system from other Raspberry Pis on the network (default is “raspberrypi,” consider changing to “iotp” or “piprinter” or any descriptive name).
  • Under “Localisation Options,” configure the other options for language, WiFi channels and keyboard. If your keyboard is generating unexpected characters, this is why!
  • Under “Advanced Options,” you can optionally disable overscan compensation if using an HDMI monitor. Though our ultimate goal is to use the Raspberry Pi “headless,” without a monitor, the extra space is welcome during the configuration steps.

Do NOT touch “Overclock” or other esoteric settings. Overclocking can wreak havoc with the serial port we’ll be relying on! Do not overclock.

Tab to "Finish" and press enter, but DO NOT REBOOT YET. We still need to set up the wireless networking. Select “No” when prompted to reboot. Raspi-config will exit to the command line.

Some configuration files will now be edited. Our examples show the “nano” text editor being used, as it’s easiest for the uninitiated. Power users can substitute “vi” or their editor of choice.

Configure Wireless Networking

If you have a WiFi network that broadcasts its SSID (the wireless network name), this is fairly straightforward:

sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

Delete everything in the file, then enter the below text in instead. Check your spelling, everything’s got to be spot-on! Then edit the SSID and password lines to reflect your actual network name and password (keeping the double quotes on both):

country=US
ctrl_interface=DIR=/var/run/wpa_supplicant GROUP=netdev
update_config=1

network={
    ssid="SSID"
    psk="YOUR_PASSWORD"
}

Skip ahead to the “Reboot” section below. This next section pertains only to hidden wireless networks.

Hidden Networks

Hidden WiFi networks are an ongoing point of contention…the following directions may or may not work for your particular network. If this doesn’t seem to work, consider changing your WiFi config to broadcast the SSID; it’s been shown that hidden networks aren’t actually any more secure than visible ones!

The network configuration in this case is a fair bit more complicated. And the slightest typo here, even one character, can prevent the system from joining the network! Again, we strongly recommend using a “broadcast” network, it’s far easier and less error-prone. But if you must…

sudo nano /etc/wpa_supplicant/wpa_supplicant.conf

Delete everything in the file, then enter the below text in instead. Check your spelling, everything’s got to be spot-on! Indent the 'network' section using tabs, not spaces. Then edit the ssid and psk (password) lines to reflect your actual network name and password (keeping the double quotes on both):

ctrl_interface=/var/run/wpa_supplicant
update_config=1
ap_scan=2
eapol_version=1
network={
	ssid="my-network-ssid"
	scan_ssid=1
	mode=0
	proto=WPA2
	auth_alg=OPEN
	pairwise=CCMP
	group=CCMP
	key_mgmt=WPA-PSK
	psk="my-network-password"
}

Reboot

Finally, shut down the system:

sudo shutdown -h now

Wait for the system to report that it’s halted before disconnecting power. It should take about 30 seconds.

Following shutdown, remove the keyboard (if using a Model A board), insert the WiFi adapter and re-connect power (keep the monitor attached for now). With a Model B board, you can keep both the keyboard and WiFi adapter attached until you know the networking is properly configured.

During the boot process, you should see a series of DHCPDISCOVER messages as the system tries to join the wireless network. Eventually (by the fifth or sixth try), you should see a “bound to [address]” message, indicating a successful connection. Write down this address! You may need this later. It's probably going to look like 10.0.1.17 or 192.168.0.6 or similar. If it doesn’t show up, log in with the pi username and run the command ifconfig wlan0 and look for inet addr:10.0.1.8 or similar — that’s the number you may need later.

If the wireless connection doesn’t work, unplug the WiFi adapter and connect the keyboard and double-check the network setup steps above. It might simply be a typo. Correct any mistakes and reboot.

Once WiFi is working, the keyboard and monitor are no longer required. All further configuration can be done remotely via SSH, if you’ve enabled it in raspi-config.

Raspberry Pi Setup: 2 of 3

Wireless networking MUST be functioning before continuing. If your Pi is not on the network yet, work through the prior page to diagnose the issue.

Further configuration of the Raspberry Pi will take place over the network using SSH, not the keyboard and mouse. As you can probably figure by now, we have an in-depth SSH tutorial. In summary:

  • The SSH server should already be enabled on the Raspberry Pi — this was done during the initial raspi-config setup.
  • On Mac or Linux systems, you can use a Terminal or xterm window.
  • For Windows systems, you can download PuTTY.

The terminal command to access the system would be either:

ssh pi@raspberrypi.local

(If you changed the hostname in raspi-config, use that instead, e.g. iotp.local)

Or — if your computer can’t resolve the “.local” address — try the numeric IP address as mentioned on the prior page, e.g.:

ssh pi@10.0.1.10

(Substitute the numeric IP address actually reported by the system during boot.)

You’ll be prompted for a password — either use the password that you set up from raspi-config, or “raspberry” if you left the default. Additionally, the first time connecting you may be prompted regarding a host key for security…enter Y (or click Yes) when prompted.

Update Packages, Install Libraries and Printer Essentials

Once logged in, type the following at the command prompt (if logged in through ssh, you can copy-and-paste from this browser window to the terminal):

sudo apt-get update
sudo apt-get install git cups wiringpi build-essential libcups2-dev libcupsimage2-dev python-serial python-pil python-unidecode

The “update” step refreshes the list of available software packages and takes a couple of minutes.

The “install” step downloads and installs a number of packages…this may take 20 minutes or so.

Install Printer Driver

The printer does not need to be connected yet. We can prepare the system the same regardless.

cd
git clone https://github.com/adafruit/zj-58
cd zj-58
make
sudo ./install

Your thermal printer may have arrived with a test page in the box or the paper bay. If not, or if you threw that away, you can generate a new one by installing a roll of paper and holding the feed button while connecting power.

Look for the baud rate that’s printed near the bottom of the page. This is typically either 9600 or 19200 baud. This is important…you’ll need to know the correct value for your printer.

To set up this printer as the system default, we’ll be typing two lines similar to the following (but not necessaryily identical…read on)…

sudo lpadmin -p ZJ-58 -E -v serial:/dev/serial0?baud=9600 -m zjiang/ZJ-58.ppd
sudo lpoptions -d ZJ-58

On the first line, change the “baud” value to 9600 or 19200 as required for your printer. The rest of the line should be typed exactly as it appears above. Likewise for the second line, which needs no changes.

Finish Up

Shut down the system. We'll work on the case and wiring next, then return to the final software configuration later.

sudo shutdown -h now

After about 30 seconds, you can disconnect the USB power cable.

Remove the SD card and WiFi adapter, and get your soldering iron ready…

Soldering

These steps cover the current (2017-and-later) kit. For the older kit, skip to the next page.

Some soldering steps take place close to pieces of the case. Be very careful where you set your soldering iron so as not to damage the plastic parts! Also watch out for flux spatter.

During the soldering and assembly process, certain parts will become “tethered” together by wires…always pick up and move these parts together, don’t let pieces hang by the wires…this could damage parts or solder joints.

Prepare Wires

In the plastic baggie accompanying the thermal printer should be two cables, a bit over a foot long. The power cable has two conductors: red and black. The data cable has three conductors: green, yellow and black.

Cut the red/black power cable in half. This cable has a different plug at each end. We want to keep the wider of the two plugs for the printer; the other can be discarded or tossed in your spare bits drawer.

The data cable (green/yellow/black) is NOT cut, only the power cable!

Use wire cutters to clip the side “wings” off the plug at one end of the data cable.

Do not cut any of these wires! Just trim the plastic.

Next, grab the female/female jumper wires and cut off the connector at one end of each of the following colors:

  • 2 Black
  • 1 Red
  • 1 Yellow
  • 1 Green

But my kit didn’t come with any female/female jumper wires!

You might have the older (pre-2017) version of this kit. Skip to the next page for wiring directions.

After cutting, you should have:

  • A three-conductor (green/yellow/black) data cable with plugs at both ends, about 14 inches long.
  • A two-conductor (red/black) power cable with a wide plug at one end, about 7" long.
  • Five jumper wires about 6" long, each with a female connector at one end.

Prepare Button

Don’t be confused by the colors here. This sequence is three of the jumper wires, not the serial data cable!

Looking at the back of the button, with the pins arranged in a “smile,” the functions from left to right are:

  • LED +
  • NC (Normally Closed)
  • NO (Normally Open)
  • COMMON
  • LED –

Using finger pressure or small pliers (gently!), smoosh the last two pins (COMMON and LED –) close together. We need to loop a single wire through both of them…

Strip about 3/8" of insulation from the end of three of the jumper wires: BLACK, YELLOW and GREEN. Twist the ends a bit to keep the strands from fraying.

Do not do this with the serial data cable! Use the one-sided jumper wires.

Loop the BLACK wire through the LED – and COMMON pins, bend it back on itself and solder.

This is a tight squeeze for the wire, like threading a needle. It may help to turn the wire a bit while passing it through, to keep the strands from fraying. It may take a few tries…you can remove the wire, re-twist it, and try again.

Repeat with the GREEN wire on the LED + pin and the YELLOW wire on the NO (Normally Open) pin.

The NC (Normally Closed) pin is NOT CONNECTED.

Fish the three wires through the button hole on the top case piece, press the button into place and secure with the included nut.

There is no front or back side for the top piece…you can insert the button either way.

Prepare DC Jack

There are three “legs” on the DC jack, but we’ll just be using two of them.

The large center leg corresponds to the power supply tip, which will be +5V.

The “outer” of the two small legs is the power supply ring (ground).

The “inner” small leg is not connected.

Strip about 1/4" insulation from the red and black wires on the power cable and the one-sided jumper wires.

Twist the wires a bit to prevent the strands from fraying.

Twist the two red wires together, feed through the large center leg (+) and solder in place.

Repeat with the two black wires through the “outer” small leg (–).

Remember, the “inner” small leg is not connected.

Fish the connector and wires through the DC hole on the back piece of the case (this the part with the etched Adafruit logo) and press the jack into place.

Secure the DC jack from the other side with the included nut. You’ll need to fish the wires through this to get it into place.

 

Once the jack is in place, solder the 4700uF capacitor to the + and - terminals. This will help keep the voltage stable when the thermal printer is operating.

 

 

MAKE SURE THE NEGATIVE (shorter) LEG OF THE CAPACITOR IS CONNECTED TO BLACK/GND AND THE POSITIVE LED IS CONNECTED TO RED/5VDC.
That’s it for soldering! You can unplug your iron now.

Soldering (Pre 2017)

These steps cover the older (pre-2017) kit.

Some soldering steps take place close to pieces of the case. Be very careful where you set your soldering iron so as not to damage the plastic parts! Also watch out for flux spatter.

During the soldering and assembly process, certain parts will become “tethered” together by wires…always pick up and move these parts together, don’t let pieces hang by the wires…this could damage parts or solder joints.

Prepare the T-Cobbler

First we’ll be joining the T-Cobbler board and 26-pin socket.

But my kit didn’t come with a T-Cobbler!

You probably have the newer version of this kit. It’s explained on the prior page.

Normally the Cobbler would have a header soldered to the top, but we’re doing something different with this kit: the socket sits on the underside of the board.
Tack the header in place by soldering just one pin (any will do) on the top side of the board. Notice we’re soldering on the label side for this step.
Check that the header is straight and square. If not, heat the one soldered pin and realign the header.
Once the header is straight, the rest of the pins can be soldered.

It’s normal for a bit of solder to drain or “wick” down the hole being soldered…in fact, this is good and proper soldering technique. But only a little. If you keep feeding solder, the socket holes on the other side will fill in with solder and won’t plug into the Raspberry Pi!
After soldering (and allowing some time to cool), you can test fit the Cobbler on the Raspberry Pi. Gently pry it off with your fingers afterward…more soldering lies ahead…

Prepare Wires

In the plastic baggie accompanying the thermal printer should be two cables. The power cable has two conductors: red and black. The data cable has three conductors: green, yellow and black.

These cables are a bit over a foot long. We don’t need that much length inside the case, so we’ll be cutting them in half. Do not throw away the other half! We’ll be repurposing the extra wire in a subsequent step.
The power cable has a different connector at each end. We want to keep the wider of the two connectors for the printer. The small connector at the other end can be clipped off.

The data cable has wide connectors at both ends. One should be left connected, the other can be clipped off and discarded.

If you inadvertently cut the wrong connector off the power cable, you may be able to salvage it using a jeweler’s screwdriver to push the pin sockets out (there’s a small tab on the side that keeps them in place) and replace the connector at the other end.
After cutting, you should have two cables, each about 7 inches long, both with a “wide” connector: one for power (red and black) and one for data (green, yellow and black).

You should also have five loose wires (two black, one red, yellow and green). Keep these for later steps.

The two connectors (one small, one wide) can be discarded.

Prepare Button


This is done using three of the spare pieces of wire, not the serial data cable!

Looking at the back of the button, with the pins arranged in a “smile,” the functions from left to right are:
  • LED +
  • NC (Normally Closed)
  • NO (Normally Open)
  • COMMON
  • LED –
Using finger pressure or small pliers (gently!), smoosh the last two pins (COMMON and LED –) close together. We need to loop a single wire through both of them…
Strip about 3/8" of insulation from the end of three of the spare wires: BLACK, YELLOW and GREEN. Twist the ends a bit to keep the strands from fraying.

Do not do this with the serial data cable! Use the spare wire pieces.
Loop the BLACK wire through the LED – and COMMON pins, bend it back on itself and solder.

This is a tight squeeze for the wire, like threading a needle. It may help to turn the wire a bit while passing it through, to keep the strands from fraying. It may take a few tries…you can remove the wire, re-twist it, and try again.
Repeat with the GREEN wire on the LED + pin and the YELLOW wire on the NO (Normally Open) pin.

The NC (Normally Closed) pin is NOT CONNECTED.
Fish the three wires through the button hole on the top case piece, press the button into place and secure with the included nut.

There is no front or back side for the top piece…you can insert the button either way.

Prepare DC Jack

There are three “legs” on the DC jack, but we’ll just be using two of them.

The large center leg corresponds to the power supply tip, which will be +5V.

The “outer” of the two small legs is the power supply ring (ground).

The “inner” small leg is not connected.
Strip about 1/4" insulation from the red and black wires on the power cable and the spare wires.

Twist the wires a bit to prevent the strands from fraying.
Twist the two red wires together, feed through the large center leg (+) and solder in place.
Repeat with the two black wires through the “outer” small leg (–).

Remember, the “inner” small leg is not connected.
Fish the connector and wires through the DC hole on the back piece of the case (this the part with the etched Adafruit logo) and press the jack into place.
Secure the DC jack from the other side with the included nut. You’ll need to fish the wires through this to get it into place.

Wiring Diagram

In the next few steps, we’ll be connecting components to the Cobbler according to the following diagram:

Solder the Serial Data Cable to the T-Cobbler

Strip about 1/4" insulation from the three wires of the serial data cable.

  • Solder the GREEN wire to the RXD pin on the Cobbler
  • Solder the YELLOW wire to the TXD pin on the Cobbler
  • The BLACK wire can go to any GND pin, but the next in line on the Cobbler is especially tidy.

The wires are inserted from the top side of the board and soldered on the underside.

Solder Remaining Wires to the Cobbler

Components that are installed in case pieces are now soldered to the Cobbler. Once these are tethered together like this, they can’t be separated. Always pick up and move these parts together as a set. Don’t let pieces hang by the wires.

The button and power wires are now soldered to the Cobbler using the wiring diagram.
  • RED from DC jack to 5V0 on Cobbler
  • BLACK from DC jack to GND on Cobbler
  • GREEN from button to #18 on Cobbler
  • BLACK from button to GND on Cobbler
  • YELLOW from button to #23 on Cobbler
Once all the wires have been soldered, you can trim any excess on the underside so that nothing accidentally touches the Pi board.
That’s it for soldering! You can unplug your iron now.

Case Prep

Peel and Clean Case Parts

The enclosure is comprised of seven (7) laser-cut acrylic pieces. Peel the paper backing from the acrylic case pieces. Some people use a razor blade as a scraper to get this started, but a fingernail at a corner is usually sufficient and won’t gouge the plastic.

After peeling, the parts may have a little bit of paper soot on them from laser cutting. Wiping off may suffice, or they can be washed with soap and water…but be absolutely certain that everything is completely dry before assembling components in the case!

Case Assembly: 1 of 2

These steps cover the current (2017-and-later) kit. For the older kit, skip to the next page.

Some case pieces are reversible and can be flipped over and installed either way, while others have a specific orientation. You’ve already been acquainted with a couple of these pieces during the soldering stage. Let’s assign names to the rest of these parts so we can refer to them in these directions:

Install Raspberry Pi on Bottom Plate

Remove the WiFi adapter and SD card if you haven’t already.

The bottom piece is scored on one side, with an outline showing the placement and orientation of the Raspberry Pi board.

Push out the laser cut holes and mount the Raspberry Pi Board to the bottom plate using the included plastic #4-40 screws

Install Thermal Printer

The parts baggie included with the thermal printer contains two triangle-shaped brackets and two long screws. These will hold the printer inside the case.

Note the location of the paper feed button. This should be oriented toward the BACK of the printer.

Being mindful of the wires and other attached components, slide the thermal printer through the large slot on the top case piece, with the feed button toward the BACK (the silver button is toward the front).

Set the printer and top piece face-down and insert the two brackets and screws. Use a small screwdriver to secure these in place. Use gentle pressure! Cranking these down tightly can crack the case.

Connect the serial cable and power from the DC jack, noting the labels on the bottom of the printer. The connectors are identical and it’s easy to get these switched around.

Case Assembly 1 (Pre 2017)

These steps cover the older (pre-2017) kit.
The enclosure is comprised of seven (7) laser-cut acrylic pieces. The paper backing should already have been peeled off during the “Preparation” step. If any remains, take care of that now.

Some case pieces are reversible and can be flipped over and installed either way, while others have a specific orientation. You’ve already been acquainted with some of these pieces during the soldering stage. Let’s assign names to the rest of these parts so we can refer to them in these directions:

Install Raspberry Pi on Bottom Plate

Remove the WiFi adapter and SD card if you haven’t already.

The bottom piece is scored on one side, with an outline showing the placement and orientation of the Raspberry Pi board.
All but the earliest Raspberry Pi boards have two mounting holes. Insert a 1/2" #4-40 screw into each of these holes from the top of the board.
Using your fingertips to keep the screws in place, flip the board over and install a 1/4" nylon spacer over each of the two screws.
Position the bottom plate over the Raspberry Pi (remember, the scored side should face the board) and secure in place with two #4-40 nuts. Tighten the screws from the other side using a small screwdriver and gentle pressure — don’t crank the screws down hard or you’ll crack the case!
If you have an early “rev1” Raspberry Pi board without mounting holes, this can be installed using a set of four board edge mounts (sold separately, not included in kit).

Install Thermal Printer

The parts baggie included with the thermal printer contains two triangle-shaped brackets and two long screws. These will hold the printer inside the case.

Note the location of the paper feed button. This should be oriented toward the BACK of the printer.
Being mindful of the wires and other attached components, slide the thermal printer through the large slot on the top case piece, with the feed button toward the BACK (the silver button is toward the front).
Set the printer and top piece face-down and insert the two brackets and screws. Use a small screwdriver to secure these in place. Use gentle pressure! Cranking these down tightly can crack the case.

Connect the power and serial cables from the DC jack and Cobbler, noting the labels on the bottom of the printer. The connectors are identical and it’s easy to get these switched around.

With these three pieces now “tethered” by wires, they should always be lifted and moved around as a single unit. Don’t pull on any of the wires.

Case Assembly: 2 of 2

Case assembly for the two versions is similar enough that a single set of steps and photos are shown. Pre-2017 kit uses a Pi Cobbler, newer kit has jumper wires, but otherwise similar.
Here’s the map of case parts again, as you may need to refer back to it some more:

Using “T-Slots”

The case is assembled using “t-slot” construction, common among laser-cut kits. You’ll notice a couple case parts (back and center support) have t-shaped slots along their edges. These slots hold nuts, while perpendicular case parts have holes for a corresponding machine screw.

Let’s start with the center support piece…that’s the part with four t-slots and a long tab that looks like a nose or something.

For the 2017 kit: this piece is asymmetrical…it has a specific right and left. Viewed from the front, the long tab is offset to the left.

For pre-2017 kits: this piece has no right or left…you can flip it around either way…but it definitely has a top and bottom.

Let’s start with one of the t-slots at the top. Insert a nut into the cross part of the “t” and hold it there between finger and thumb.

If holding the part and the nut simultaneously is a dexterity challenge, you can instead use a bit of tape to provide a temporary hold for the nut. This can be peeled away once the corresponding screw is in place.
We’ll attach this piece to one of the sides. The sides are interchangeable — there is no right or left — but they do have a definite top and bottom, front and back.

Insert the tab from the center support into the corresponding slot on a side piece — this is the off-center slot slightly towards the front. Make sure the tops and bottoms of the two pieces are oriented the same.

When properly aligned, insert a 1/2" #4-40 machine screw into the hole directly over the nut.
Use a screwdriver to turn the nut into place. Just “finger tight” is good for now…in subsequent steps we’ll be loosening certain screws anyway.

Never crank down hard on the case screws or you’ll break the acrylic.
Repeat the above step with the second nut and screw between these two case pieces.

Connect Back Piece

We’ll repeat some steps similar to the above, this time with the back piece. This is connected by wires to the thermal printer (and Cobbler board, on pre-2017 kits). Be very careful to always move these around as a unit…don’t tug on the wires else your solder joints (or the parts they’re connected to) may break.

Connect the same side piece to the case back, using two nuts and screws as before.

Make sure the tops of the two parts are aligned. In this picture the case is being held at an angle to access the slot…the top of the case faces the bottom-right.
You should now have four nuts and screws installed in one side piece, holding the back and center support.

The parts probably won’t be perfectly square at this stage. That’s perfectly okay…things will become progressively more aligned as the rest of the case goes together.

Stand the partial case up on its side and move the top piece (with button and thermal printer attached) roughly into position. Don’t fit this into the slots yet, just an approximate position.

Route the cables so that the button wires pass through the openings in the center support. For pre-2017 kits, position the T-Cobbler below the printer. You might need to turn some parts around or temporarily disconnect the cables from the printer to achieve a good fit.

Connect Second Side

This is why the printer isn’t slotted into place yet…it would block some t-slots that we still need access to. We’ll come back to it in a moment…

Scoot the printer out a bit so you can reach theremaining t-slots. Insert a nut into one of the slots, set the second side of the case into position and install a screw.

Repeat with the remaining three nuts and screws. You should now have a box with four sides and eight nuts & screws installed.

Slot one end of the top/printer piece into position. But with both sides in place, the slots at the other end are now blocked. The next few steps take care of all this…

Insert Case Top

Loosen two of the lower screws about 1/2 turn.

Loosen the corresponding two upper screws so the tip of the screw is flush with the face of the nut (but not so loose that it falls out…if this happens, move the top/printer piece out of the way and repeat the prior steps).
Lift the side of the edge piece. There should be just enough “play” for the tabs from the top piece to fit underneath. Press the printer piece into position.
Lower the side piece into place…slots should fit into corresponding tabs.

Tighten all four screws with a screwdriver. Just “finger tight” is sufficient for now…there’s a few more sequences like this ahead yet…

Install Front Piece

This sequence is very similar to the above…

Slot one end of the front piece into the side of the case. The “torn receipt” effect should be at the bottom. There’s no front or back to this piece, it can go either way, but Nimbus, our Internet of Things cloud mascot, wears his pompadour to the left.

Loosen the two screws at the back of the case 1/2 turn. Loosen the two front screws so the tip is flush with the nut.

Lift the side piece and pop the front into place.

Pop!
Tighten all four screws using a screwdriver (finger-tight).

Install Bottom

Nearly done! The anticipation is deadly…

You probably know the routine by now: loosen two top screws by 1/2 turn and two bottom screws so the tip is flush with the nut.

The piece we’re inserting is a little different this time: rather than tabs and slots, there’s a small nubbin at either side that fits into a circular hole on each side of the case. This piece hangs open for now.

Tighten the four screws as before.

For the 2017-and-later kit, plug in the connections as shown here.

The end of the data cable with the trimmed plug should connect to the Pi. See how it makes space for the adjacent jumper wire?

For the pre-2017 kit: Gently install the Cobbler board on to the Raspberry Pi GPIO header. Support the Pi board from below with the tips of your fingers…this prevents strain on the board and the case.

Make sure all the pins are properly aligned with the header. If it’s off by one pin in any direction, there’s the possibility of damaging the board when the power supply is connected.

Re-insert the SD card and USB WiFi adapter.
Carefully fold all the wires while swinging the bottom shut like a door. The center support piece has just enough flex to act as a latch.

If you need access to the Raspberry Pi board later (to change out the SD card or connect a monitor for troubleshooting), you can unlatch and swing this open later…no need to dismantle the whole case.
Now you can go around the case and tighten each screw. Gently! Just finger pressure plus a fraction of a turn will hold it firmly. If you crank these down too hard you’ll crack the plastic.

Insert Paper and Connect Power

Pull up the top lever to access the paper compartment. Insert a roll of thermal receipt paper and push the lid closed while feeding the end of the paper through the slot.
Connect the 5V DC power supply to the jack on the back of the case.

Many power supplies look alike. Make absolutely certain you’re connecting the 5 Volt supply included with the kit! Anything more will likely kill the Raspberry Pi board.
If the printer starts dumping lots of random gibberish after power is connected, pop the printer lid open to stop it printing. The serial port has not been correctly configured. After the system has finished booting (about a minute), connect via SSH and repeat the steps in Raspberry Pi Setup: 2 of 3.

Twitter Setup

One of our example applications prints an ongoing timeline of live “tweets” from Twitter. To access this feature, even if you don’t use the Twitter service personally yourself, you’ll still need to sign up for an account to use the search function in software. If you don’t yet have one, begin at the Twitter home page and use the sign-up form.

In addition to some basic account information, you’ll need to provide a real email address in order to confirm and activate the account. Within a few minutes you should receive an email with an activation link.

Once you have an account and have logged in, you can then proceed to apps.twitter.com (the Twitter Developer App home page). Click "Create new App"

You’ll be asked for some basic information about your application — the tweet-printing program we’ll be loading on the Raspberry Pi. Provide a reasonable name and description…we don’t know if applications are audited, but being honest and descriptive here would be helpful. You also need to provide a Website URL. If you have a personal or company web site, enter that on the form, else you can use Adafruit’s home page.

You’ll need to agree to the developer terms of service before finalizing your application. Read, agree, and click “Create your Twitter application”:

There used to be a CAPTCHA here. Now, Twitter requires that you add a mobile phone number to your account, if not already assigned. A verification code will be sent to this number.

Once you complete these steps and the app is created, you’ll have the credentials needed to authorize your application. Click on the “Keys and Access Tokens” tab. On the next page of this guide we’ll copy and paste the “Consumer Key” and “Consumer Secret” strings into a Python script.

Do not share these strings with anyone—they’re for the secure and exclusive use of your application. If you’re sharing source code via Github or other management system, remember to remove these before posting the code!

Raspberry Pi Setup: 3 of 3

Install Adafruit Code

Connect the power cable to boot the system. Negotiating a wireless connection will take a moment, so wait about a minute before trying to access the system using SSH.

Once logged in, install the Adafruit thermal printer library and example code:

git clone https://github.com/adafruit/Python-Thermal-Printer

Make sure a roll of paper is installed in the printer and the top is securely latched. Then we’ll test all the basic functionality:

cd Python-Thermal-Printer
python printertest.py

This should progress through different text sizes, styles and formats, as well as barcodes and images.

If this does not work, the most likely culprits are:
  • One of the prerequisite Python libraries is not installed (serial, imaging, unidecode) — explained in Raspberry Pi Setup Part 2 of 3.
  • The serial port has not been properly disengaged for application use — also explained in Raspberry Pi Setup Part 2 of 3.
  • Wrong connection between printer and Raspberry Pi — explained in Assembly.
The first two will likely give an informative error response. The latter will just produce no results.

Configure the Weather Scripts

Before running the weather scripts, you must create another developer account in order to use the DarkSky weather API.

Go to https://darksky.net/dev/ and sign up for an account.

Get your API secret key, and go ahead and modify the following line in forecast.py and timetemp.py

API_KEY = "YOUR_API_KEY"

Save the changes, then run the script again:

python forecast.py

This should now print the current weather and the forecast for NYC, the default location. Change the latitude and longitude variables too to reflect the location you'd like to get the weather for. I use NASA's site

If this works, also edit the file timetemp.py and make the same change there. This is a different script that prints the current time and local weather conditions.

Configure the Twitter Script

As written, the sketch will search for Tweets originating from Adafruit, but you can change this to any search string supported by the Twitter SearchAPI. FIrst step though is to set up authentication…

nano twitter.py

Look for this section of code:

# Twitter application credentials -- see notes above -- DO NOT SHARE.
consumer_key    = 'PUT_YOUR_CONSUMER_KEY_HERE'
consumer_secret = 'PUT_YOUR_CONSUMER_SECRET_HERE'
Copy the Consumer key and Consumer secret strings from the Twitter application page into the corresponding spots, keeping the quotes around them.

Just below this is the search term. You can change Adafruit to any other valid Twitter account.
queryString = 'from:Adafruit'
Different search types are possible, such as by tag. Refer to the SEARCH OPERATORS section of the Twitter Developers Documentation for guidance.

Any search string used by the “Gutenbird” sketch for the original Internet of Things Printer can also be used here.

Test the Main Script

The “main” script starts by printing a greeting image, performs once-daily actions (weather forecast and Sudoku puzzle), then goes into Twitter-monitoring mode.

sudo python main.py

The “main” script must be run as root (i.e. using “sudo”) because it directly accesses hardware — the GPIO pins for the button and LED.

Each morning at 6:30 am, the once-daily actions are performed again. You can change this time (or the actions) by editing the main.py script.

Press control+C to stop the program. We’ll set it up to run automatically when the printer is turned on…

Configure Auto-Start

With the software now tested “manually,” let’s make it start automatically upon booting:

sudo nano /etc/rc.local

Before the final “exit 0” line, add these two lines:

cd /home/pi/Python-Thermal-Printer
python main.py &

If you downloaded or otherwise placed the printer software in a different location, the first line should be changed accordingly. “sudo” isn’t necessary here because the rc.local script is already run as root.

Reboot the system to test the startup function:

sudo reboot

After 30 seconds to a minute, you should see the status light come on. After another 30 seconds, the greeting image should be printed, then the “once daily” functions. After that, the printer will go into Twitter-monitoring mode.

Regular Operation

When the printer is idle, tap the button for the current time and local weather conditions.

Hold the button down to initiate an orderly shutdown. This is always a good idea — you don’t want to just pull the plug on most Linux systems. There may be many files open at any given time, and this gives the system a chance to put things in order.

Troubleshooting

My kit is missing one or more parts, or parts arrived damaged.

Email support@adafruit.com with your order number and a description of the trouble, and we’ll have a replacement part sent promptly!

The case I received is tan, not the pretty shade of blue in the pictures.

The case acrylic is covered in adhesive paper to prevent scratches in transit. Pull up one corner with a fingernail, and the rest should peel cleanly from there. (We get this question a LOT…don’t feel silly for asking!)

I need to diagnose a software or configuration problem, but can’t connect to the Raspberry Pi over WiFi.

The bottom of the case can be unlatched and swings open. Stand the case on its side, connect an HDMI or composite monitor and a keyboard or USB hub, and you can work with the system like a regular “desktop” Raspberry Pi to troubleshoot the issue.

Sometimes the paper jams in the printer, especially when printing inverse blocks of text.

Edit the file Adafruit_Thermal.py and look for this line (around line 53):

defaultHeatTime = 60

Replace '60' with a smaller number. Try decreasing it by 10 and repeating until the problem is resolved.

Text and graphics print very faint.

Edit the file Adafruit_Thermal.py and look for this line (around line 53):

defaultHeatTime = 60

Replace '60' with a larger number. Try increasing it by 10 and repeating until the output improves.

Raspberry Pi Setup: 2 of 3 (Pre 2017)

Wireless networking MUST be working before continuing. If your Pi is not on the network yet, work through the prior page to diagnose the issue.
Further configuration of the Raspberry Pi will take place over the network using SSH, not the keyboard and mouse. As you can probably figure by now, we have an in-depth SSH tutorial. In summary:
  • The SSH server should already be enabled on the Raspberry Pi — this was done during the initial Raspi-config setup.
  • On Mac or Linux systems, you can use a Terminal or xterm window.
  • For Windows systems, you can download PuTTY.
The terminal command to access the system would be:

ssh pi@thataddressfromthe-previous-step
for example:
ssh pi@10.0.1.10

You’ll be prompted for a password — either use the password that you set up from Raspi-config, or “raspberry” if you left the default. Additionally, the first time connecting you may be prompted regarding a host key for security…enter Y (or click Yes) when prompted.

Update Installed Software

Once logged in, type the following at the command prompt:

sudo apt-get update

This updates the list of available software packages, and takes a couple of minutes.

Install Additional Python Libraries

These libraries are required by the thermal printer library and example programs:

sudo apt-get install python-serial python-imaging python-unidecode

This takes a couple of minutes.

Enable Software Access to Serial Port

The serial port on the Raspberry Pi’s GPIO header is normally configured for console cable use. But now we want to use this port for the thermal printer instead, so we’ll need to disable this default behavior.

sudo nano /boot/cmdline.txt

Change:
dwc_otg.lpm_enable=0 console=ttyAMA0,115200 kgdboc=ttyAMA0,115200 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait
to:
dwc_otg.lpm_enable=0 console=tty1 root=/dev/mmcblk0p2 rootfstype=ext4 elevator=deadline rootwait
(Basically, delete the references to ttyAMA0)

And:

sudo nano /etc/inittab

Comment out or delete the last line. i.e. change this:
T0:23:respawn:/sbin/getty -L ttyAMA0 115200 vt100
to:
# T0:23:respawn:/sbin/getty -L ttyAMA0 115200 vt100
Or simply delete that line.

On the next reboot, the console cable (if using one) will no longer work. SSH network access (or a keyboard and monitor directly attached) will be the only way in.

Optional Software

You can optionally install a VNC server to allow a remote graphical session. This is a lengthy topic and best covered in its own tutorial. However, for the “Running VNCServer at Startup” section, use the directions in this tutorial instead (specifically the “Getting VNC Server to Work on a Specific User” section).
Mac users may want to install Netatalk, which makes the system appear in the Finder sidebar and can simplify transferring files to and from the system:

sudo apt-get install netatalk

Finish Up

Shut down the system. We'll work on the case and wiring next, then return to the final software configuration later.

sudo shutdown -h now

After about 30 seconds, you can disconnect the USB power cable.

Remove the SD card and WiFi adapter, and get your soldering iron ready…