Add Local/Remote GPIO Support to PWM Button Control Tutorial

[222448082Ashen]

Description

This PR adds Local and Remote GPIO operation modes to the "Modify PWM through button presses" Raspberry Pi tutorial, implementing support for the new remote GPIO functions introduced in splashkit-core PR #58.

Context: SplashKit now supports remote GPIO control, allowing developers to control Raspberry Pi GPIO pins from another computer over a network connection. This enables development and testing from a main development machine while controlling physical Pi hardware remotely, and supports controlling multiple Raspberry Pis simultaneously from a single program.

Related PR: thoth-tech/splashkit-core#58 - GPIO Remote Functions

Type of change

• New feature (non-breaking change which adds functionality)
• Documentation (update or new)

Changes Made

Tutorial Structure Updates

Added nested tab structure following the pattern used for C# language variants:

• Main tabs: syncKey="code-language" for C++, C#, Python
• Nested GPIO tabs: syncKey="gpio-mode" for Local and Remote operations

Code Examples Added

Main Code Block

• Added Local GPIO tab with existing code
• Added Remote GPIO tab with remote function calls
• Included connection initialization and management

Step-by-Step Sections

• Step 1: Initialise Values (Local/Remote tabs)
• Step 2: Initialise Hardware (in progress)
• Step 3: Set PWM/GPIO Pins (in progress)
• Step 4: Get User Inputs (in progress)
• Step 5: Change LED Brightness (in progress)
• Step 6: Clean Up Memory (in progress)

Documentation Added

remote_raspi_init() Explanation Section

Comprehensive documentation covering:

• Purpose: Network-based GPIO control
• Use Cases:
  • Development from main machine
  • Multi-Pi control
  • Resource-intensive program execution
• Parameters:
  • name (string): Unique connection identifier
  • ip (string): Raspberry Pi IP address
  • port (integer): Daemon port (default 8888)
• Return Value: Connection object for subsequent remote function calls
• Example Code: Comparison between local and remote function calls

Remote Function Pattern Documentation

• All remote functions have remote_ prefix
• First parameter is always the connection object
• Remaining parameters identical to local versions
• Multi-Pi control example included

Daemon Setup Note

Added caution note linking to Remote Access Guide for daemon setup instructions.

How Has This Been Tested?

Code Validation

• Fixed MDX syntax error (line highlighting in code blocks)
• Verified nested tab structure follows SplashKit conventions
• Build validation in progress

Documentation Review

• Verified all remote function names match splashkit-core PR Draw_Circle C++ Usage Example #58
• Confirmed parameter patterns (connection object as first parameter)
• Cross-referenced with networking API for connection type usage

Remote Function Mapping

Local Function	Remote Equivalent	Parameters
raspi_init()	remote_raspi_init(name, ip, port)	Returns connection object
raspi_set_mode(pin, mode)	remote_raspi_set_mode(conn, pin, mode)	Connection + local params
raspi_set_pwm_dutycycle(pin, duty)	remote_raspi_set_pwm_dutycycle(conn, pin, duty)	Connection + local params
raspi_set_pull_up_down(pin, pud)	remote_raspi_set_pull_up_down(conn, pin, pud)	Connection + local params
raspi_read(pin)	remote_raspi_read(conn, pin)	Connection + local params
raspi_cleanup()	remote_raspi_cleanup(conn)	Connection only

Testing Checklist

• Tested in latest Chrome
• Tested in latest Firefox
• npm run build (fixes applied for MDX syntax)
• npm run preview

Checklist

If involving code

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings

If modified config files

• I have checked the following files for changes:
  • package.json - No changes
  • astro.config.mjs - No changes
  • netlify.toml - No changes
  • docker-compose.yml - No changes
  • custom.css - No changes

Folders and Files Added/Modified

Modified:

• src/content/docs/guides/raspberry-gpio/3-pwm-button-control.mdx
  • Added syncKey="gpio-mode" nested tabs for Local/Remote
  • Added Remote GPIO explanation section (50+ lines)
  • Added remote_raspi_init() parameter documentation
  • Added multi-Pi control example
  • Updated main C++ code block with Local/Remote tabs
  • Updated Step 1 code section with Local/Remote tabs
  • Fixed MDX syntax error (removed invalid line highlighting)

No Changes:

• scripts/json-files/guides/Raspberry-GPIO/raspberry-gpio.json - Functions remain the same
• scripts/json-files/guides.json - Auto-generated, no manual changes needed

Code Implementation Details

Local Version (Unchanged)

raspi_init();
gpio_pin led_pin = PIN_11;
raspi_set_mode(led_pin, GPIO_OUTPUT);
raspi_set_pwm_dutycycle(led_pin, brightness);
raspi_read(increase_btn_pin);
raspi_cleanup();

Remote Version (New)

// Initialize connection
connection pi_connection = remote_raspi_init("my_pi", "192.168.1.100", 8888);

// All functions now take connection as first parameter
gpio_pin led_pin = PIN_11;
remote_raspi_set_mode(pi_connection, led_pin, GPIO_OUTPUT);
remote_raspi_set_pwm_dutycycle(pi_connection, led_pin, brightness);
remote_raspi_read(pi_connection, increase_btn_pin);
remote_raspi_cleanup(pi_connection);

Multi-Pi Example

connection pi1 = remote_raspi_init("bedroom_pi", "192.168.1.100", 8888);
connection pi2 = remote_raspi_init("kitchen_pi", "192.168.1.101", 8888);

remote_raspi_write(pi1, PIN_11, GPIO_HIGH);  // Control first Pi
remote_raspi_write(pi2, PIN_13, GPIO_HIGH);  // Control second Pi

Additional Notes

Why This Matters

Educational Value:

• Demonstrates network-based hardware control concepts
• Shows professional development workflow (develop remotely, deploy to hardware)
• Teaches connection management and resource handling

Practical Benefits:

• Enables development without physical Pi access
• Supports complex multi-device projects
• Reduces development iteration time

Implementation Status

Completed:

1. Main code block with full Local/Remote implementation
2. Comprehensive remote_raspi_init() documentation
3. Remote function pattern explanation
4. Multi-Pi control example
5. Step 1: Initialise Values (Local/Remote tabs)
6. MDX syntax fix for build compatibility

In Progress:

• Steps 2-6 require Local/Remote tab updates
• Same pattern as Step 1, but with different line highlighting
• Each step ~60 lines of code addition

Future Work:

• Apply same Local/Remote pattern to other GPIO tutorials:
  • 0-blink-led.mdx
  • 1-read-button-press.mdx
  • 2-pwm-control-led.mdx

Dependencies

Required for Remote Operations:

• SplashKit with remote GPIO functions (splashkit-core PR Draw_Circle C++ Usage Example #58)
• pigpio daemon running on target Raspberry Pi
• Network connectivity between development machine and Pi
• Pi IP address accessible from development machine

Daemon Setup

Users must start the pigpio daemon on their Raspberry Pi:

# Default port (8888)
sudo pigpiod

# Custom port
sudo pigpiod -p <port_number>

Detailed setup instructions linked at: https://programmers.guide/book/appendix/0-installation/4-0-remote-access-pi/

Breaking Changes

None. This is a pure addition of Remote GPIO examples alongside existing Local GPIO code. All existing Local code remains unchanged and fully functional.

Follow-up PRs

After this PR is merged, similar updates should be applied to:

1. Get Started with SplashKit GPIO (Blink LED)
2. Reading Button Presses
3. Using PWM to control LED brightness

Each tutorial will follow the same nested tab structure established here.

Preview

The tutorial now presents users with clear choices:

Main Code Block:

[C++] [C#]
  └─ [Local] [Remote]  ← New nested tabs
      └─ [Top-level] [OOP]  ← C# nested tabs

Step-by-Step Sections:
Each step maintains the same nested structure, allowing users to see exactly how each line differs between Local and Remote operations.

[netlify]

❌ Deploy Preview for splashkit failed.

Name	Link
🔨 Latest commit	8d023fd
🔍 Latest deploy log	https://app.netlify.com/projects/splashkit/deploys/693d47c92d7845000852ea51