Skip to main content

Raspberry Pi Zero W Setup Guide

This document summarizes the setup process for the Raspberry Pi Zero W Basic Starter Kit - Black Box Edition and the first commands to run after connecting successfully through SSH.

1. Kit purchased​

Product:

Raspberry Pi Zero W Basic Starter Kit - Black Box Edition

According to the product description you shared, the kit includes:

Included items​

  1. Raspberry Pi Zero W

    • Wireless LAN 802.11 b/g/n
    • Bluetooth 4.1 Low Energy
    • BCM2835 SoC @ 1GHz
    • 1GHz single-core CPU
    • 512MB RAM
    • MicroSD slot
    • Micro HDMI port
    • USB On-The-Go port
    • Micro USB power port
    • 40-pin GPIO-compatible header area
    • Composite video and reset headers
    • 1080p HD video output
    • Raspberry Pi Zero CSI camera connector
    • Built-in Wi-Fi

  2. Premium black ABS case

    • Closed lid
    • Open cover for different configurations
    • Camera module mount
    • Vented bottom
    • Wall mount support

  3. Micro USB power supply

    • 5V 2.5A
    • In-line on/off switch
    • 5 ft cable
    • Ferrite bead noise filter
    • UL Listed

  4. Micro USB male to USB female adapter

    • Used to connect a keyboard, mouse, USB flash drive, etc.

  5. HDMI to Mini HDMI adapter

    • Allows a standard HDMI cable to connect to the Raspberry Pi Zero W.

  6. Mini camera module adapter cable

    • Used to connect a Raspberry Pi camera module to the Pi Zero W.

  7. 40-pin header

    • Used for GPIO projects.
    • May require soldering depending on whether it is already attached.

  8. Aluminum heat sink

    • Optional but useful for helping with heat.

2. Important missing item​

The kit description does not clearly include a microSD card, so this is required separately.

Recommended:

16GB or 32GB microSD card
Class 10 or A1 preferred

In this setup, the detected microSD card was:

Name: NO NAME
Format: MS-DOS (FAT32)
Capacity: 31.25 GB

That means the card is effectively a 32GB microSD card, which is good for this Raspberry Pi.

3. Setup approach used​

We used a headless setup.

That means:

No monitor
No keyboard
No mouse

The Raspberry Pi is controlled from a Mac using SSH over Wi-Fi.

This is a good setup for IoT, automation, small server, and FlowPOS-related experiments.

4. Raspberry Pi Imager configuration​

The setup was done using Raspberry Pi Imager on macOS.

Device selection​

In Raspberry Pi Imager, choose:

Raspberry Pi Zero
Raspberry Pi Zero, Zero W, and Zero WH

Do not choose:

Raspberry Pi Zero 2 W

because the purchased board is the older Raspberry Pi Zero W, not the newer Zero 2 W.

5. Operating system selection​

Choose:

Raspberry Pi OS (other)
→ Raspberry Pi OS Lite (32-bit)

Reason:

The Raspberry Pi Zero W has limited resources:

1GHz single-core CPU
512MB RAM

So it is better to use the Lite version without a desktop environment.

Avoid the full desktop OS for this board unless you specifically need a visual interface.

6. Storage selection​

In Raspberry Pi Imager, choose the SD card:

Generic- USB3.0 CRW -SD Media
29.1 GB
Mounted as /Volumes/NO NAME

Important:

Make sure you select the SD card, not the Mac's internal drive.

7. Customization settings​

Before writing the image, configure the Raspberry Pi.

Hostname​

Recommended:

flowpi

This allows connecting later with:

ssh rpaprintuser@flowpi.local

User​

Example used:

Username: rpaprintuser
Password: your chosen password

Wi-Fi​

Configure:

SSID: your Wi-Fi name
Password: your Wi-Fi password
Wireless LAN country: GT
Time zone: America/Guatemala
Keyboard layout: us

Important:

The Raspberry Pi Zero W works with 2.4 GHz Wi-Fi. If your router has separate 2.4 GHz and 5 GHz networks, use the 2.4 GHz one.

Example:

Use: HomeWiFi
Avoid: HomeWiFi_5G

Remote access​

Enable SSH:

Enable SSH
Use password authentication

This is required for headless access from your Mac.

Raspberry Pi Connect​

Leave Raspberry Pi Connect turned off for the first setup:

Enable Raspberry Pi Connect: OFF

SSH is simpler and better for learning.

8. Writing the image​

Final review before writing:

Device: Raspberry Pi Zero
Operating system: Raspberry Pi OS Lite (32-bit)
Storage: Generic- USB3.0 CRW -SD Media
Customizations:
- Hostname configured
- Localisation configured
- User account configured
- Wi-Fi configured
- SSH enabled

Then click:

WRITE

Expected behavior:

  1. Raspberry Pi Imager erases the SD card.
  2. It writes Raspberry Pi OS.
  3. It verifies the image.
  4. It finishes and allows you to eject the card.

After completion:

  1. Eject the SD card safely from macOS.
  2. Remove the microSD card.
  3. Insert it into the Raspberry Pi Zero W.

9. Powering the Raspberry Pi​

The Raspberry Pi Zero W has two micro USB ports:

PWR IN  → power input
USB     → USB On-The-Go accessories

Connect the power supply to:

PWR IN

Then wait:

2–3 minutes

The first boot can take a little longer because the Pi is configuring itself.

10. Connecting through SSH​

From your Mac, open Terminal and run:

ssh rpaprintuser@flowpi.local

Replace rpaprintuser if you used a different username.

The first time, you may see a message like:

The authenticity of host 'flowpi.local (...)' can't be established.
ED25519 key fingerprint is SHA256:...
Are you sure you want to continue connecting (yes/no/[fingerprint])?

This is normal the first time connecting to a new device.

Type:

yes

Then press Enter.

After that, enter the password created in Raspberry Pi Imager.

Important:

When typing the password, Terminal will not show characters. That is normal.

11. Successful SSH login​

A successful login looks like this:

Linux flowpi 6.12.75+rpt-rpi-v6 #1 Raspbian ...
Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY...
rpaprintuser@flowpi:~ $

The important part is:

rpaprintuser@flowpi:~ $

That means you are inside the Raspberry Pi.

12. Update the Raspberry Pi​

After logging in, update the system:

sudo apt update
sudo apt full-upgrade -y

When it finishes, reboot:

sudo reboot

The SSH session will disconnect.

Wait 1–2 minutes, then reconnect:

ssh rpaprintuser@flowpi.local

13. Basic system checks​

After reconnecting, run:

Check hostname​

hostname

Expected:

flowpi

Check disk space​

df -h

Check memory​

free -h

Check Wi-Fi connection​

iwgetid

Expected result:

It should show the Wi-Fi network name.

14. Install basic tools​

Install useful tools:

sudo apt install -y git curl wget python3 python3-pip python3-venv nano

These tools are useful for:

  • Running Python scripts
  • Downloading files
  • Cloning Git repositories
  • Editing files
  • Building small IoT or server projects

15. First Python test​

Create a folder:

mkdir ~/hello-pi
cd ~/hello-pi

Create a Python file:

nano hello.py

Paste:

print("Hello from my Raspberry Pi Zero W")

Save in nano:

Control + O
Enter
Control + X

Run the script:

python3 hello.py

Expected output:

Hello from my Raspberry Pi Zero W

16. First local web server test​

Create a folder:

mkdir ~/web-test
cd ~/web-test

Create a small HTML file:

echo "Hello from FlowPOS Raspberry Pi" > index.html

Start a web server:

python3 -m http.server 8080

From your Mac browser, open:

http://flowpi.local:8080

Expected page:

Hello from FlowPOS Raspberry Pi

To stop the server in Terminal:

Control + C

17. Safe shutdown​

Do not unplug the Raspberry Pi suddenly if possible.

To shut it down safely:

sudo poweroff

Wait around:

20–30 seconds

Then unplug the power cable.

18. Troubleshooting​

SSH does not connect​

Try:

ssh rpaprintuser@flowpi.local

If that fails, try the IP address shown during setup. In this case, the Pi appeared as:

192.168.86.110

So you could try:

ssh rpaprintuser@192.168.86.110

Hostname does not resolve​

If flowpi.local does not work:

  1. Wait a few minutes after boot.
  2. Check your router's connected devices.
  3. Look for a device named flowpi.
  4. Use the IP address directly.

Wi-Fi does not connect​

Check:

Correct SSID
Correct password
Wireless LAN country set to GT
2.4 GHz Wi-Fi network used

The Raspberry Pi Zero W generally does not work with 5 GHz-only Wi-Fi networks.

Wrong known host warning​

If you reflash the SD card and SSH warns about a changed host key, remove the old known host entry on your Mac:

ssh-keygen -R flowpi.local

Then reconnect:

ssh rpaprintuser@flowpi.local

A good first practical project is:

FlowPOS Kitchen Status Device

Basic idea:

FlowPOS backend
→ Raspberry Pi
→ small status page, LED, buzzer, or kitchen display

Simple first version:

FlowPOS backend → Raspberry Pi local web page

Later version:

FlowPOS backend → MQTT/WebSocket → Raspberry Pi → LED or screen

This is useful because it connects directly with restaurant and POS use cases.

20. Summary​

Current status:

Raspberry Pi Zero W is installed.
Raspberry Pi OS Lite 32-bit is running.
Wi-Fi is configured.
SSH is enabled.
Mac can connect using ssh rpaprintuser@flowpi.local.

You are now ready to start building small Raspberry Pi projects.