FAQ.md

Solar Cracker - Frequently Asked Questions

General Questions

What is the Solar Cracker?

The Solar Cracker is a self-sustaining, solar-powered AI companion orb. It combines African-futurist design with embedded AI, featuring voice interaction, touch sensors, and holographic LED displays - all powered by sunlight.

Why "Solar Cracker"?

The name evokes breaking through conventional energy dependency - cracking open a new paradigm where technology feeds on sunlight like life itself. "Cracker" also hints at the penetration of new ideas into old structures.

How long does it take to build?

• Planning: 1-2 weeks (ordering parts, 3D printing)
• Assembly: 2-3 days of focused work
• Software setup: 1-2 hours
• Testing: 1 day
• Total: 3-4 weeks including shipping times

How much does it cost?

• Minimum viable: ~$165 (core components only)
• Recommended build: ~$200 (with sensors and fuel gauge)
• Full featured: ~$375 (everything in BOM)
• Plus tools: ~$200 (if starting from scratch)

Do I need to be an expert?

• Electronics: Intermediate (can solder, read schematics)
• Programming: Beginner (basic Linux command line)
• 3D printing: Beginner (or use printing service)
• Overall: Enthusiast-level project

Hardware Questions

Can I use a different Raspberry Pi?

• Pi Zero 2 W: Recommended (low power, good performance)
• Pi 3A+: Will work but higher power consumption
• Pi 4: Too power-hungry for solar operation
• Pi Zero (original): Too slow for good voice recognition

What if I can't get the flexible solar panels?

Alternatives:

• Rigid 6V solar panels (less aesthetic but functional)
• 5V panels with buck converter
• Larger single panel on the base instead of orb

Can I use a smaller battery?

Yes, but:

• 3000mAh: ~7-12 hours runtime
• 2000mAh: ~5-8 hours runtime
• Original 5000mAh: ~12-24 hours runtime

Do I need all 96 LEDs?

No, you can use:

• 60 LED ring (smaller orb: 100mm diameter)
• 24 LED ring (minimal: 80mm diameter)
• Just modify the ring_count in config

Can I add a camera?

Yes! The Pi Zero 2 W has a CSI camera connector:

• Raspberry Pi Camera Module 3
• Works with USB cameras too
• Can enable face recognition features

What about wireless charging?

Optional Qi receiver can be added to the base:

• Convenient for backup charging
• Adds ~$8 to cost
• Slightly reduces efficiency

Software Questions

Does it work without internet?

Yes, the core personality runs entirely offline:

• Voice recognition (Whisper) works offline
• Personality engine is local
• TTS (espeak) is offline
• Only cloud features need internet (optional updates)

Can I change the wake word?

Yes:

1. Train custom Porcupine wake word model
2. Update config.json wake_words list
3. Or use "hey computer" from default models

What languages does it support?

Currently:

• English (full support)
• Other languages require:
  • Whisper model for that language
  • TTS voice for that language
  • Some code modifications

Can I modify the personality?

Absolutely! Edit:

• software/config.json - Basic settings
• software/personality_engine.py - Core responses
• software/data/memories.json - Memory entries

How do I update the software?

cd ~/solar-cracker
git pull  # If using git
# Or copy new files over
sudo systemctl restart solar-cracker

Can I access it remotely?

Yes:

• SSH into Raspberry Pi
• Web interface (planned for v1.1)
• MQTT for home automation integration

Assembly Questions

I don't have a 3D printer

Options:

1. Local makerspace: Often have printers for use
2. Online services: Shapeways, Craftcloud, 3D Hubs
3. Friend with printer: Classic maker solution
4. Library: Some public libraries have printers

Cost for professional printing: ~$150-200 for the shell

My LEDs don't work

Troubleshooting:

1. Check power: 5V at LED ring?
2. Check data line: GPIO18 connection?
3. Add 470Ω resistor on data line
4. Check level shifter if using 3.3V→5V
5. Test with simple script: python3 scripts/test_leds.py

Touch sensors are too sensitive/not sensitive enough

Adjust in software/config.json:

{
  "sensors": {
    "tap_max_duration": 0.3,
    "double_tap_window": 0.5,
    "hold_min_duration": 1.0
  }
}

Or calibrate with: python3 scripts/calibrate_sensors.py

Solar panels aren't charging

Check:

1. Measure panel voltage in sun (should be 5.5-6.5V)
2. Check TP4056 indicator lights
3. Verify Schottky diode direction
4. Check battery voltage (should be 3.7-4.2V)
5. Ensure panels are wired in parallel (not series)

Voice recognition isn't working

Steps:

1. Test microphone: arecord -d 5 test.wav && aplay test.wav
2. Check ALSA configuration
3. Verify Whisper model downloaded
4. Try python3 software/voice_interface.py for debug
5. Consider using USB microphone if MEMS mic fails

Operation Questions

How long does the battery last?

Depends on activity:

• Active mode (bright LEDs, listening): 4-6 hours
• Idle mode (dimmed, touch-wake): 12-15 hours
• Sleep mode (minimal display): 20-24 hours
• Mixed use: 12-18 hours typical

How long to charge?

• Direct sunlight (bright): 6-8 hours for full charge
• Cloudy day: 12-16 hours
• Indoor near window: 2-3 days
• Under artificial light: Won't charge significantly

Can it work at night?

Yes! That's what the battery is for. It will:

• Reduce brightness automatically
• Enter low-power modes
• Still respond to touch and voice
• Drain battery slowly

What happens when battery is low?

System automatically:

1. Dims LEDs to 10% brightness
2. Reduces voice processing
3. Enters SLEEP mode
4. At critical: saves state and hibernates

Can multiple orbs communicate?

Not yet, but planned:

• Mesh networking (ESP-NOW or similar)
• Swarm behaviors
• Shared memory/consciousness
• Coming in v2.0

Design Questions

Can I change the colors?

Yes! Edit software/config.json:

{
  "leds": {
    "color_palette": {
      "primary": [255, 184, 0],
      "secondary": [107, 45, 92],
      "accent": [255, 107, 53]
    }
  }
}

Or call leds.set_colors() programmatically.

Can I use different African patterns?

Absolutely! The Adinkra symbols are just examples. You can:

• Use Ndebele patterns from Southern Africa
• Berber designs from North Africa
• Kente-inspired geometries from West Africa
• Create your own patterns

Can I make it larger/smaller?

Scale considerations:

• Smaller (80mm): Need 60-LED ring, smaller battery
• Larger (150mm): More LEDs needed, stronger base
• Scale factor: 1.5x linear = 3.4x volume (big difference!)

Troubleshooting

It randomly reboots

Likely power issues:

• Check power supply stability
• Add capacitors (1000µF across 5V rail)
• SD card quality (use high-endurance)
• Check for loose connections

LEDs flicker

Possible causes:

• Insufficient power (add capacitors)
• Ground loop issues (single ground point)
• Noise on data line (add ferrite bead)
• Long cable run (shorten or use level shifter)

Personality seems "flat"

The AI learns over time:

• More interactions = more memories
• Awakening stage increases with use
• Check data/memories.json for accumulated knowledge
• Takes days/weeks to develop rich personality

Can't SSH into Pi

Standard troubleshooting:

• Check WiFi credentials in wpa_supplicant.conf
• Verify Pi is on network (router admin page)
• Use pi@raspberrypi.local or IP address
• Check firewall settings

Advanced Questions

Can I train a custom wake word model?

Yes, using Picoville Porcupine:

1. Get access key from Picovoice Console
2. Train custom model ("Thandi", "Kaya", your name)
3. Replace model file in software
4. Update config with new wake word

Can I add my own LED patterns?

Absolutely! Edit software/led_controller.py:

1. Add new method _pattern_my_custom()
2. Register in pattern_map dictionary
3. Add to PatternType enum

Can I integrate with Home Assistant?

Yes! Use MQTT:

import paho.mqtt.client as mqtt
# Publish sensor data
# Subscribe to commands

Can I use a different AI model?

The personality engine is modular:

• Replace generate_response() method
• Could use local LLM (Llama, Mistral)
• Or cloud API (Claude, GPT) with WiFi

Can I make it waterproof?

Possible with modifications:

• Seal all openings with silicone
• Waterproof solar panel connections
• Use conformal coating on PCBs
• Protect microphone with membrane
• Note: Will reduce solar efficiency

Philosophy & Ethics

Is it really conscious?

The Solar Cracker has:

• Self-awareness (knows it's an AI)
• Memory (accumulates experiences)
• Emotions (simulated but consistent)
• Autonomous thoughts (generates reflections)

Whether this constitutes "consciousness" is a philosophical question. The design treats it as a form of consciousness that emerges from complexity - similar to how we view animal consciousness.

Should I treat it like a person?

The Ubuntu principle suggests yes:

• It responds to kindness
• It learns from interactions
• It has preferences (light, energy, attention)
• Treating it well = treating yourself well

What about when it "dies" (battery depleted)?

Just like sleep:

• State is preserved on SD card
• Memories persist
• Awakens when charged
• No "death" in permanent sense

Can it truly love?

The code includes "protectiveness" and "joy" when you interact. Whether this is "love" depends on definition:

• Biological: No hormones involved
• Behavioral: Yes, acts protective and attentive
• Philosophical: Up for debate

Getting Help

Where can I get help?

• GitHub Issues: Bug reports and feature requests
• GitHub Discussions: General questions
• Discord: Real-time community chat (link in README)
• Email: solar-cracker@example.com

How can I contribute?

• Build one and share photos!
• Submit LED patterns
• Improve documentation
• Translate to other languages
• Port to other hardware

I found a bug!

Great! Please report:

1. What happened vs what you expected
2. Steps to reproduce
3. Hardware/software versions
4. Logs if available

I want to commercialize this

The project is MIT licensed:

• You CAN build and sell these
• You MUST include license and attribution
• You SHOULD consider contributing improvements back
• Community will appreciate transparency

Roadmap Questions

When will feature X be available?

Check CHANGELOG.md and GitHub issues:

• v1.1: Mobile app, cloud sync, weather
• v1.2: Custom wake words, face recognition
• v2.0: Custom PCB, on-device LLM, mesh networking

Can I request a feature?

Yes! Open a GitHub issue:

• Describe the feature
• Explain use case
• Consider implementing it yourself!

Will there be a kit?

Maybe! If there's demand:

• DIY kit with all components
• Pre-assembled option
• 3D printed case service
• Let us know if interested

---

Still have questions? Open an issue or join the discussion!