Boolean by Nature. Panda by Design.

https://pinpanda-api.com/

Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Online Usage
4. Local Usage
5. Architecture
6. Settings
7. Roadmap
8. Your Projects
9. Contributing
10. License
11. Contact

About The Project

PinPanda-API is a lightweight REST API that gives you secure, remote access to the GPIOs of your single-board computer—even when it's running on your home network. Once configured, you can control your devices from anywhere in the world via https://pinpanda-api.com, no coding required.

Designed for DIY creators, PinPanda-API removes the complexity of remote hardware control. Forget chipset quirks or board-specific limitations—set it up once, and start building, automating, and experimenting from anywhere.

Follow the installation steps to get started.

(back to top)

Getting Started

Prerequisites

• Have an Ubuntu / Debian Distro installed on your board.

  ...more Info

  
  Follow your boards documentation if you haven't already.
  

  For example, I personally use a La Potato AML-S905X-CC with Ubuntu 22.4 (Jammy) installed.
  If you have the same board and don't mind using a headless version, use the base-arm64+aml-s905x-cc version.

(back to top)

Installation

1. Run the debian package installation

   sudo curl https://pinpanda-api.com/Install.sh | bash

2. Go to /opt/pinpanda-api-1.4/appsettings.json and update Authorization:AuthorizedEmails with your gmail account.

3. Log into your firewall / router and add a new single port forwarding rule.

   1. The Type should be TCP
   2. The IP Address should be the IP of your board where you're installing PinPanda-API (ex: 192.168.1.144)
   3. The Port should be 3005 (default) - unless you've changed this in the appsettings.json file.

(Optional) Have PinPanda-API launch on Reboot

1. To start the API on reboot - install crontab:

     sudo apt-get install crontab

2. Open the Text Based User Interface (TUI)

   sudo crontab -e

3. Then add the following line to the file

   @reboot cd /opt/pinpanda-api-1.4; ./PinPanda-Api >> /opt/pinpanda-api-1.4-logs

(back to top)

Online-Usage

1 - Navigate to the PinPanda-API website

2 - Login with Google Oauth2.0

3 - Visit whatismyipaddress to find and copy your public IPv4 address. This is how PinPanda-API will communicate securely with your board.

4 - Enter in that IPv4 address you just copied, followed by the port your API is running on. (Default is 3005)

5 - Add a new request and start interacting with the GPIOs on your board.

6 - Send requests to turn off / on your GPIO pins. Use the red stop button to cancel all active requests. That's it!

Step-by-step screenshots

(back to top)

Local-Usage

Postman Documentation

GET /sbc/chipsets/gpios

• Description: Get information about all available GPIOs on your board.
  
  

• Example

    curl -X GET "http://69.203.14.52:3005/sbc/chipsets/gpios" 

Important!

• The ID from the response will correlate to the Linux ID in your SBC documentation.
• Not all GPIO states can be updated. You'll see an error on the SBC terminal if you attempt this and it cannot be updated.

GET /sbc/chipsets/{chipsetId}/gpios/{gpioId}

• Description: Get information about a specific GPIO on your board.

• Example

    curl -X GET "http://69.203.14.52:3005/sbc/chipsets/1/gpios/81" 

GET /sbc/chipsets/{chipsetId}/gpios/{gpioId}/state

• Description: Read current state of your GPIO

• Example

    curl -X GET "http://69.203.14.52:3005/sbc/chipsets/1/gpios/81/state" 

POST /sbc/chipsets/{chipsetId}/gpios/{gpioId}/state/{state}

• Description: Change the state of a single GPIO

• State: Can be 1, 0, Low, or High.

• Example

    curl -X POST "http://69.203.14.52:3005/sbc/chipsets/1/gpios/81/state/0" 

POST /sbc/chipsets/gpios/state

• Description: Allows you to change multiple GPIO states to "Low" or "High" You can also choose to repeat the task or add a delay.

• Example (Cancels all active requests) :

    curl -X PATCH "http://69.203.14.52:3005/sbc/chipsets/gpios/state" \
     -H "Content-Type: application/json" \
     -d '[]'

• Example (Starts a new request):

    curl -X PATCH "http://69.203.14.52:3005/sbc/chipsets/gpios/state" \
     -H "Content-Type: application/json" \
     -d '[
            {
                "Gpios": [91, 92, 81],
                "Chipset": 1,
                "State": "Low",
                "Options": {
                    "Milliseconds": 30000,
                    "RepeatTimes": 1
                }
            },
            {
                "Gpios": [93],
                "Chipset": 1,
                "State": "High",
                "Options": {
                    "Milliseconds": 500,
                    "RepeatTimes": 10
                }
            }
        ]'

(back to top)

Architecture

(back to top)

Advanced-Settings

To update your API settings, refer to the AppSettings file in your optional installs directory: /opt/pinpanda-api-1.4.

Kestral:

• Kestral:Endpoints:Http:Url - This is the endpoint your API will bind to.
  By default it's set to 0:0:0:0:3005. Meaning it will bind to http://localhost:3005 and http://your.ip.address:3005.

Authorization:

• Authorization:Enabled - allows values "true" or "false".

  • False: Allows access to any CORS origins and headers. Recommended only for developement.
  • True: Requires a Google JWT to be authorized. It also requires the following authorization settings to be filled.

• Authorization:AuthorizedEmails - Restricts entry to only the following Google users.
  

  • Example value: ["yourEmailHere@gmail.com, anotherEmailHere@gmail.com]

• Authorization:AuthorizedCorsOrigins - Restricts CORS origins. For security purposes only requests with the listed origins are allowed through.

Filters:

• Filters:AllowOnlyTheseChipsets - GET /sbc/chipsets/gpios will usually return all Chipsets from your board. Some projects only require a subset of these. Adding IDs here filters results.

  • Example: [1]

• Filters:AllowOnlyTheseGpios - GET /sbc/chipsets/gpios will usually return all GPIOs from your board. Some projects only require a subset of these. Adding IDs here filters results.

  • Example: [91, 92, 81,95,80,79,94,93]

Mappings:

• Mappings:GpioNames - GET /sbc/chipsets/gpios will usually return the names assigned by the SBC. If you'd like to return custom names in their place, use this setting.
  • Example: [ { "Id": 91, "Name": "VCC Power" }, { "Id": 92, "Name": "Common" }, { "Id": 81, "Name": "Zone 1" }, { "Id": 85, "Name": "Zone 2" } ]

Important!
If you expose your IP and Port to the public (By adding a rule to your router / firewall) it is highly recommended to set Authorization:Enabled to true. Without it, anybody can call your API.

(back to top)

Roadmap

• Add endpoint to list available GPIOs
• Add endpoint to Update GPIO state
• Add endpoint to read GPIO values
• Add settings to make usage easier (filter, security, configuration, etc...)
• Add secure endpoints for Google JWT Auth
• Create UI to interface with individual boards
• Add communication between SBC and PinPanda-API
• Add documentation
• Add GPIO mapping on API side to set custom labels
• Add additional chipset architectures
  • linux-muscl-64
  • linux-arm

See the open issues for a full list of proposed features (and known issues).

(back to top)

Your-Projects

Made something cool? Let us know!

• Remotely Controlled Sprinkler System (by David K): Instructables | hackaday.io
• Get yours listed here...

(back to top)

Contributing

If you have a suggestion that would make this API better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement".

Contribute in other ways. Sponserships are solely responsible for keeping this project running. If you found this repo useful please consider becoming a sponsor.

Don't forget to give the project a star!

Thank you!

(back to top)

License

See LICENSE.txt for more information.

(back to top)

Contact

David Kobuszewski - dkob8789@gmail.com

Project Link: Gpio Controller Api

(back to top)