Running the Code

There are a few different ways to run the code. If you followed the setup instructions and created the icons, it should automatically run upon starting the Pi.

If you exited the code and you would like to run the code again, you can do so simply by double-tapping the icon on the desktop.

If it asks you what you want to do with the file, just choose execute.

Another option is to use ssh to connect remotely to your Raspberry Pi from your desktop computer. You can then type commands into the Pi without having to disassemble your book and plug in a keyboard, or remove the SD card in order to enter commands. This is also a great way to troubleshoot your project: when you're running the script from an ssh terminal you can see any error codes to help figure out why your project isn't working.

Adafruit's Raspberry Pi Lesson 6. Using SSH

From either your ssh window or from a keyboard plugged into your Pi, you can run the code manually from the command line / terminal window using the following commands:

source ~/story/bin/activate
cd ~/Magic_AI_Storybook
sudo -E PATH=$PATH python story.py

Creating a New Story

When you first start the script, you will be prompted about what kind of story your would like.

Wait for the NeoPixels to turn yellow and speak into the microphone using a loud clear voice. If it doesn't hear you correctly, it may generate a story different than requested. Once it has detected speech, it will display a Dreaming screen (created with Midjourney AI) while it generates the story:

Once the story has been generated, it will display the story for you to read:

Navigation

At the bottom of each page, there will be two or three buttons. Back and Next are used to navigate between pages and stories. If you are at the end of the last story, pressing the Next button will generate a new story.

If there are multiple stories, they will be displayed in the order they were generated and pressing Back at the beginning of a story will load the previous one and pressing Next at the end of a story which has another story after it will load that story.

Pressing the New Story button, which looks like a plus sign, at any time will prompt you for a new story and then display that story.

Putting the Book in a Sleep State

Closing the reed switch by closing the cover should put the book in a sleep state. If it is in the middle of a more complex task such as creating a new story, it attempts to stop those tasks and then places the book in a sleep state.

Exiting the Script

To exit the script, you can close the book three times within five seconds. If you have changed the Quit settings from the defaults, the behavior could be a bit different.

Changing the Prompt: bookprompt.txt

To change the ChatGPT prompt, you will want edit the /boot/bookprompt.txt file. If you have changed the file system to read-only, you will need to shut down the Pi, remove the SD Card, place it in a computer and you can just edit the file from the boot partition. Place it back into the Pi when finished and start it back up again.

The file is at /boot/bookprompt.txt. By default, it reads:

Write a complete story. It must begin with a title and have a body of approximately
{STORY_WORD_LENGTH} words long and a happy ending. The specific
story request is "{STORY_REQUEST}". The title should each be
specified and the body should start on the next line.

To change the prompt, ssh into your Pi or plug in your keyboard and open a terminal window. Type these commands:

cd /boot
sudo nano bookprompt.txt

This will open bookprompt.txt in the nano text editor. 

This is a powerful bit of code that lets you set whatever parameters you'd like for your stories. Example text you could add:

"Make every story about a girl named Sarah and her teddy bear Sugarbear"
"Write in the style of Neil Gaiman"
"The story should be in rhyming couplets and iambic pentameter"
"The stories should be magical and strange, with wild animal spirit magic based on ancient Norse and Finnish mythology and should end with a confusing moral"
"Every story should contain a pun"

The possibilities are endless. What kind of stories will your book imagine?

The prompts in bookprompt.txt will affect every story you ask for, so if you want just one rhyming story, use the voice control feature to ask for it. If you want EVERY story to rhyme, change it here in bookprompt.txt.

The variables STORY_WORD_LENGTH and STORY_REQUEST can be found in story.py.  By default the stories are 800 words long. Change STORY_WORD_LENGTH in story.py to edit this.

Troubleshooting

This is a complicated project with a lot of steps. Here are a few things to try if you're running into trouble.

Story.py Doesn't Run

1. Use ssh to connect to your Pi using your computer. This is a powerful little tool that will allow you to control your Pi without having to plug in a keyboard and monitor. Here is a full tutorial that will help you get started:

Adafruit's Raspberry Pi Lesson 6. Using SSH

Once you can ssh into your Pi, type sudo -E python story.py into your terminal window to start the story script. The terminal window will give you a verbose output about what's going on with your project, which is VERY helpful in the debugging process.

2. Start Over. Head back to the Software Install page and run through every step again. It's easy to miss a command, or not to notice if you've mistyped something. This is where ssh comes in handy again: you can copy/paste the commands easily from your computer's web browser into your terminal window and that lessens the chance of a typo.

The Pi Keeps Rebooting / Crashing

Is your battery sufficiently charged? And is it plugged in to the charger? Try unplugging it. I had trouble with the Pi rebooting over and over when I started it up while the charging cord was plugged in. Be sure the battery is charged and unplug before you start.

If the story.py script keeps quitting on you, perhaps you missed our little Easter Egg: if you open and close the book, activating the magnetic reed switch 3x within 5 seconds, then story.py will exit so you can get to the Pi desktop. This is a feature, not a bug! Relaunch the script by double-clicking the desktop icon.

The App is Still Running in Fullscreen, but not Responding

If you set up the Pi with the Read-Only File system, you can simply restart it. You can also plug a keyboard in and hit Alt+F4. After about 5 seconds, a popup should appear asking if you want to Wait or Force Quit. Choose Force Quit.

The Story pages through by itself

This can happen if you have something obscuring or stuck to part of the touch screen. I initially stuck a pretty vinyl sticker on the edges of the screen to cover the paper transition, but the vinyl activated the capacitive touch response on the screen and made it act like I was touching it. Be sure your screen is completely clear of glue or stickers or anything that will make it react.

It Doesn't Listen / Can't Seem to Hear You

Try changing the sensitivity of the microphone by editing the ENERGY_THRESHOLD variable in story.py

If that doesn't help, try running this script. Save it as microphone_recognition.py in the same folder as your listener.py file. You'll have to paste your API key into it.

from listener import Listener

OPENAI_API_KEY = ""

listener = Listener(OPENAI_API_KEY)

print("Say Something")
listener.listen()

if listener.speech_waiting():
    print(f"Whisper API thinks you said {listener.recognize()}")
else:
    print("No speech detected")

Authentication Errors

If you get stuck on the "Dreaming" page, you may have an authentication error. Did you remember to add your Open API key to keys.txt? Try editing keys.txt and make sure your key is in there and looks correct.

cd ~
sudo nano keys.txt

If it still doesn't work, try going back to Open API and generating a new key, and use that one.

This guide was first published on May 24, 2023. It was last updated on Mar 29, 2024.

This page (Usage) was last updated on Mar 28, 2024.

Text editor powered by tinymce.