docs: detailed documentation of pidog/pidog.py

[devin-ai-integration]

Summary

Adds docs/pidog.md, a documentation-only deep dive into the Pidog hardware abstraction layer, in the same style as the existing docs/action_flow.md. No code changes.

Covers: module header (sudo-aware UserHome/config_file discovery, the numpy-2 numpy_mat shim), every constant (link lengths, *_DPS, PID gains, HEAD_PITCH_OFFSET, head limits), __init__'s peripheral-by-peripheral fail-soft init and thread_list registry, the producer/consumer threading model (buffers + per-group locks + wait_*_done polling), each worker thread, the motion primitives, the ultrasonic subsystem, audio, calibration, and the kinematics (head_rpy_to_angle gimbal blend, pose2coords, pose2legs_angle, the two-link IK, legs_angle_calculation).

Notable findings recorded while cross-reading actions_dictionary.py / preset_actions.py:

• _imu_thread doesn't continue after data == False, so it unpacks a bool → TypeError; repeated IMU failure sets self.exit_flag = True, which also kills the leg/head/tail threads. An IMU fault disables all motion.
• compare_version returns or_v >= or_v (always True), so the version check is a no-op — and the dead else branch defines numpy_mat as return numpy_mat(data) (infinite recursion) instead of np.mat(data).
• __init__ sets leg_point_struc; set_legs()/pose2coords() use legpoint_struc — calling pose2coords() before set_legs() raises AttributeError.
• polar2coord references non-existent self.A/B/C; set_angle references non-existent limit_angle/coord_temp/servo_move — both dead/broken.
• Legs pop the buffer afterservo_move, head/tail pop before, so wait_head_done()/wait_tail_done() return one frame early.
• close() never runs signal.alarm(0) (the finally: is commented out), leaving a 5 s alarm armed and SIGINT hijacked after it returns; the ultrasonic threads are non-daemon, so skipping close() hangs process exit.
• speak() shells out to sudo killall pulseaudio on every call.
• legs_angle_calculation calls Pidog.coord2polar(cls, coord) — passing the class as self — which only works because that method touches class constants only; this is what lets actions_dictionary.py compute gait frames without a Pidog instance.

Link to Devin session: https://app.devin.ai/sessions/7111583235ea4084a505cf2a925fd7aa
Requested by: @PascalDesmet

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring