name

pidog-control

description

Control a SunFounder PiDog V2 installed with the official tutorial under the user's home directory (`~/pidog`, with related dependencies such as `~/robot-hat` and `~/vilib`). Use when the user wants PiDog to perform basic motions, posture changes, barking or simple expressive behaviors, or control the onboard RGB light board. Also use when verifying that a standard PiDog V2 Python installation is present and ready.

PiDog Control

Control a SunFounder PiDog V2 using the standard tutorial-style installation layout under ~/.

Scope

This skill is designed for the common setup used by PiDog hobbyists who followed the SunFounder installation docs and installed the projects under their home directory:

~/pidog
~/robot-hat
~/vilib

This version of the skill focuses on:

basic motion / posture control
simple expressive actions such as bark and tail wag
RGB light-board control
basic environment checks

Do not assume custom wiring, custom virtualenvs, or nonstandard install prefixes unless the user says so.

Safety

Before movement:

Tell the user to place PiDog on the floor or on a stable open surface.
Prefer short actions first.
Avoid repeated or continuous movement loops unless explicitly requested.
If the setup is unverified, run status first and then safe-test.

If the user asks for something outside the supported action set, inspect the local examples under ~/pidog/examples/ before inventing APIs.

Standard workflow

If the machine state is unknown, run:
```
python3 scripts/pidog_ctl.py status
```
For the first real movement on a new machine, run:
```
python3 scripts/pidog_ctl.py safe-test
```
Then run the requested action or light command.
Report exactly what happened.

Supported commands

Inspect environment

python3 scripts/pidog_ctl.py status

Checks:

expected directories under ~/
whether the pidog package is importable
availability of Pidog
available speech utilities

Safe movement test

python3 scripts/pidog_ctl.py safe-test

Runs a minimal do_action('stand') → do_action('sit') test.

Basic actions

python3 scripts/pidog_ctl.py action stand
python3 scripts/pidog_ctl.py action sit
python3 scripts/pidog_ctl.py action lie
python3 scripts/pidog_ctl.py action bark
python3 scripts/pidog_ctl.py action wag-tail
python3 scripts/pidog_ctl.py action forward
python3 scripts/pidog_ctl.py action backward
python3 scripts/pidog_ctl.py action turn-left
python3 scripts/pidog_ctl.py action turn-right

To keep a posture instead of auto-cleaning at the end:

python3 scripts/pidog_ctl.py action stand --hold
python3 scripts/pidog_ctl.py action sit --hold
python3 scripts/pidog_ctl.py action lie --hold

When switching between hold postures, the helper tries to stop the previous hold process automatically so the user usually does not need to manually pkill the prior command.

These map to the official high-level API:

dog.do_action('stand')
dog.do_action('sit')
dog.do_action('lie')
dog.do_action('wag_tail')
dog.speak('single_bark_1') for the default bark effect in this skill

Light-board control

General path through the main helper:

python3 scripts/pidog_ctl.py light off
python3 scripts/pidog_ctl.py light breath --color purple
python3 scripts/pidog_ctl.py light listen --color yellow
python3 scripts/pidog_ctl.py light boom --color orange
python3 scripts/pidog_ctl.py light solid --color '#00aaff'

Minimal direct RGB path that avoids initializing the full Pidog() runtime:

python3 scripts/pidog_rgb_ctl.py light breath --color red
python3 scripts/pidog_rgb_ctl.py light listen --color yellow
python3 scripts/pidog_rgb_ctl.py light off

This maps to the official light-board API:

dog.rgb_strip.set_mode(mode, color=..., bps=..., brightness=...)

Recommended modes in this skill:

off
breath
listen
boom

Experimental alias:

solid (mapped to boom, not a true steady-on solid mode)

Supported color names are defined in the script and can also be passed as hex RGB values. Real-device testing showed that breath and listen are usable but visually brief. A local rgb_strip_test.py example confirmed direct use of RGBStrip.set_mode('boom', ...), so this skill now exposes boom and maps solid to it as the closest tested approximation.

Design assumptions

This skill assumes the official PiDog V2 install flow was used and that the runtime is on the default system Python path after pip3 install . from ~/pidog.

This skill follows the public repository structure directly:

package import: from pidog import Pidog
motion interface: do_action(...)
light-board interface: rgb_strip.set_mode(...)
sound effects: speak(...)

Prefer these official APIs over heuristic method-name probing.

If something fails

Check these in order:

~/pidog exists
python3 -c "import pidog" works
PiDog is powered correctly
Servo calibration has been completed
The light board hardware is connected and enabled

References

Read these as needed:

references/install-layout.md for standard home-directory layout assumptions
references/api-notes.md for confirmed upstream interfaces
references/actions.md for the exposed public action set
references/light-board.md for light-board behavior and mode mapping notes
references/troubleshooting.md when runtime checks or hardware behavior fail
official docs: https://docs.sunfounder.com/projects/pidog/en/latest/

Keep this skill focused on the standard install path and the basic features promised here.