search

carolynz / poetry-camera-rpi

Other
162 stars 8 forks source link

readme

Poetry Camera

A camera that prints poems of what it sees.

We started this project as newcomers to the world of hobby electronics. The following instructions are intended for complete beginners, as we were. We simplified some of the design to optimize for easily sourcing and assembling parts; as a result, it's less compact than our photographed versions. If you are comfortable with electronics and coding, we encourage you to experiment and remix even more.

⚠️ These instructions are still in progress. ⚠️ Try it out and let us know what's confusing, or doesn't work.

Hardware you'll need

1. Computer: Raspberry Pi Zero 2 W with headers

Raspberry Pis are simplified computers. They are lightweight, cheap, have limited processing power, and are more fragile than typical consumer electronic devices. It's very sensitive to the specific power sources you use — too much power and you'll fry the part, too little power and the software won't run. You also have to manually shut down the software before unplugging the power, to protect the software from being corrupted.

We chose the Pi Zero 2 for its balance of processing power (Pi Zeros are too slow) and compact size (most other Pis on the market are larger). The wire diagrams in this tutorial will apply to all Raspberry Pis, but there may be differences in software and camera compatibility, especially with older devices. We've tested this with a Pi 3b+ and it works fine, but a Pi 4 probably requires too much power to make it a viable portable solution.

Raspberry Pi Zero 2 is often sold without headers (those 2x20 black metal connectors). The headers let you easily connect the Pi to the printer and buttons with plug-in jumper wires. If you buy the Pi without headers, you'll need to separately buy a 2x20 header and solder them on yourself. If you don't want to solder, you can use hammer-on headers and this installation rig.

Raspberry Pis are also recovering from a supply shortage. Check rpilocator.com for live stock notifications on standalone parts (does not list accessory kits).

2. Accessories to connect the Raspberry Pi to stuff.

3. Camera: Raspberry Pi Camera Module 3

Mostly straightforward, but be careful of damaging the hardware. The Raspberry Pi camera is delicate and can be easily fried via static. We broke 3 cameras in the process of making this project. Just make sure to always store it in a static-shielding bag when you're not using it.

If you are connecting the camera to a Pi Zero 2, note that the Zero 2's camera connection collar is also very delicate. We broke a Pi Zero 2 camera collar in the process of making this as well and had to just get a new Pi 🥲

We have not tested these instructions with older models of Raspberry Pi cameras.

4. Receipt printer: Mini Thermal Printer w/ TTL Serial connection

We used the Adafruit thermal printer line for this project, but they have subsequently been discontinued. Similar printers exist on Amazon and Aliexpress; the ones we've bought work with the same printer drivers (which are also no longer maintained by Adafruit, but still seem to work).

The Nano Thermal Printer or Tiny Thermal Printer are more compact, but have slightly different wiring.

The important thing is that the thermal printer has a TTL serial connection so you can easily connect it to the Pi. Search "TTL embedded thermal printer" on Amazon or Aliexpress to find your parts.

5. Batteries:

If you want your camera to be portable, you'll need some batteries! The Pi requires a steady 5V of power @ 1.2A, while the printer needs 5-9V and draws ~2A while printing.

Recommended power supply: 6xAA batteries

It's not the lightest solution, but it's a beginner-friendly starting point.

Other solutions that could work:

Power supplies that DON'T work:

6. Shutter button & LED

Any LED + momentary pushbutton will work for the shutter button. We use the LED as a status indicator for things like ready, loading, etc.

7. Miscellaneous equipment

Software

This code currently uses OpenAI's models to turn the image into a poem. It also uses thermal printer drivers from Adafruit's thermal printer Python library.

You'll need to get your own OpenAI account & API key. Each request costs a couple of cents.

Currently, the main.py script running on the Pi:

Putting it all together

This was adapted from the following tutorials:

Part 1. Check that your Raspberry Pi & camera works

  1. Connect your Raspberry Pi to your Camera module.

  2. Insert your SD card with a fresh install of any Raspberry Pi OS onto the Pi.

  3. Connect your Pi to a monitor via mini HDMI.

  4. Plug in power. You should see a green light on the Pi, and a start-up screen on the monitor.

  5. Once the Pi is on, open up the Terminal on your Pi to start making changes.

  6. Set up Raspberry Pi hardware to take Camera & Serial inputs:

    sudo raspi-config

  7. You'll want to adjust the following settings:

    • Glamor: ON (for Camera setup on newer versions of Raspbian OS)
    • Serial Port ON (lets you access receipt printer inputs)
    • Serial Console OFF (idk what this does)

    Restart the system as needed.

[Tutorial TODO: include a basic camera test script & show desired behavior]

Part 2. Check that your printer works

  1. Update the system and install requirements. I'm not sure you even need all of these; I can go over these again later and trim out the unnecessary ones.

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

  2. Install some software required to make the Adafruit Thermal Printer work.

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

  3. Clone this repo, which contains our Poetry Camera software:

    $ cd
$ git clone https://github.com/carolynz/poetry-camera-rpi.git

  4. Set up your thermal printer, connecting it to power and your Pi. See diagram and instructions in this tutorial. Test that it works. Pay attention to your printer's baud rate (e.g. 19200). We will use this later on.

  5. Open our poetry-camera-rpi directory:

    $ cd poetry-camera-rpi

  6. If your printer's baud rate is different from 19200, open main.py and replace that number with your own printer's baud rate:

    
# main.py:

instantiate printer

printer = Adafruit_Thermal('/dev/serial0', 19200, timeout=5)


[TODO] need a setup script to test that the printer works

### Part 3. Set up the AI
1. Set up an OpenAI account and create an API key.

2. Navigate to your directory with the Poetry Camera code and create a `.env` file, which will store sensitive details like your OpenAI API key:
```nano .env```

3. In the .env, add your API key:
```OPENAI_API_KEY=pasteyourAPIkeyhere```

[TODO] add an openai test script

### Part 4. Get it working end-to-end
[TODO] include wiring diagram

1. Connect buttons

2. Run the poetry camera script.
```shell
$ python main.py

  1. Check that the shutter button lights up, indicating that the camera is ready to take a picture

  2. Click the shutter button and wait for the poem to print out.

[TODO] troubleshooting instructions different common error messages

Part 5. Automatically run the Poetry Camera code when the camera turns on

  1. Set up a cron job to run your python script at startup. First, open your crontab file to your default editor: 
    $ crontab -e

2 Then add the following line to your crontab, to run the script when you boot up the computer.

# Run poetry camera script at start
@reboot python /home/pi/poetry-camera-rpi/main.py >> /home/pi/poetry-camera-rpi/errors.txt 2>&1

The >> {...}errors.txt 2>&1 writes any error messages to errors.txt for debugging. A common failure mode is files cannot be found. Make sure that all your filepaths are absolute filepaths and have the right usernames and directory names.

Part 6. Make the power circuit

[TODO] clean this up & explain steps :)

image

Part 7: Change wifi networks on-the-go

The camera needs wifi to work. You could always hardcode in your mobile hotspot by editing wpa_supplicant.conf. If you want to connect to new wifi networks on the fly, just follow this simple tutorial with plug-and-play code. (You can auto-run the tutorial's Flask app and our main camera code as two cron jobs at the same time.)

To do the above tutorial, you'll need a second wifi adapter, plugged into your microUSB port. Definitely get a plug-and-play wifi adapter that works for Linux/Raspberry Pi.

Wifi adapter options that seem to work:

MicroUSB to USB adapters: