Unofficial Playdate reverse-engineering notes/tools - covers file formats, server API and USB commands

James

Last update: Dec 31, 2022

Related tags

Hardware reverse-engineering usb-serial file-formats playdate playdate-reverse-engineering

Overview

Unofficial Playdate reverse-engineering notes/tools - covers file formats, server API and USB commands

⚠️ This documentation is unofficial and is not affiliated with Panic. All of the content herein was gleaned from reverse-engineering Playdate tools and game files, and as such there may be mistakes or missing information.

Documentation

File Formats
- Playdate game formats
  - .pdz - Executable file container
  - .pda - Audio file
  - .pdi - Image file
  - .pdt - Imagetable file
  - .pdv - Video file
  - .pds - Strings file
  - .pft - Font file (TODO)
- Other formats
  - .fnt - Font source file (TODO)
  - .strings - Strings source file (TODO)
Server
- Playdate API - Main Playdate server API
Misc
- USB - Playdate USB interface

Tools

pdz.py - Unpacks all files from a .pdz file container
pdex2elf.py - Converts a pdex.bin to an ELF file that can be analysed in a decompilation tool such as Ghidra
usbeval.py - Uses the Playdate's USB eval command to evaluate a Lua script over USB. Has access to the Lua runtime of the currently loaded game, except for system apps.

Special Thanks

Simon for helping with some ADPCM audio data reverse engineering
Zhuowei for this script for unpacking Playdate .pdx executables, which was the base for pdz.py
The folks at Panic for making such a wonderful and fascinating handheld!

2022 James Daniel

Playdate is © Panic Inc. - this project isn't affiliated with or endorsed by them in any way.

Comments

PDX for dumping system lock key?

Hello, I was wondering if someone has made a tool that dumps the lock key as seen at the bottom of this page, I am not very familiar with C so any help would be appreciated!

opened by ChaoticPumpkin 2
usb: document the unlock command

The serial console has an unlock command that takes a (likely device-specific) 32 character code and, if correct, adds more commands to the serial console.

Also document a working picocom command for talking to the console.

opened by zhuowei 2
Document difference between two sizes in pdi table header

The table header in a pdt file has two numbers. For a sequential image table, they're both the number of images. For a matrix image table, the first is the total number of images, while the second is the number of images per row.

(The change at the end is just adding a final newline.)

opened by AlanDeSmet 1
Help about an eventual API recreation

I want to recreate the playdate server API, but here's a thing; I don't have any /games/purchased/ or /games/system/ or /games/user/ API dump which isn't empty (just [])

If you can, can you provide a schema of the response given from /games/purchased/ or /games/system/ or /games/user/?

opened by Rix565 1
Note meaning of size in compressed image header

The image width and height in the compressed image header are for the first image only. For matrix image tables, this is the size for all of the images, but for sequential image tables, they may vary. Document this.

opened by AlanDeSmet 0
Document terminal frame table entry

The table of frame offsets has one additional entry of type 0 which indicates the end of the last frame. So if the file has 16 frames, the frame offset table will have 17 entries.

opened by AlanDeSmet 0
Update PDV docs

Looks like the unknown value is the first frame offset, among other things: https://devforum.play.date/t/video-encoder-work-in-progress-mac-only/1390/15

opened by jaames 0
Document non-obvious clip/no-alpha interaction

Having spent too long debugging this, I think the pdi/pdt documentation should add some notes on interpreting the cell header. Here's my immediate thoughts (feel free to use them if you think they're useful):

When compiling images, the Playdate software tries to eliminate borders that are entirely transparent. How many rows or columns were removed are the clip values. If the clipped image has no remaining transparent pixels, no alpha channel will be written at all.

As a result, an image with transparent pixels may not have an alpha channel. The pixels for which there is data are opaque. When the clipped borders are re-added, they are always transparent.

opened by AlanDeSmet 1
Tools: Scripts for other formats
I am planning on adding more scripts for working with the various formats you can find in a Playdate game:

pdv converter - convert gif sequences to and from the pdv video format

pdi/pdt converter - convert images to and from the pdi/pdt image format

pda converter - convert audio to and from the pda format

pdz packing support - add the ability to repack files into a pdz to pdz.py

If anyone would like to help so this gets done faster, that would be appreciated!
help wanted
opened by jaames 4
Investigate PFT font format

I haven't had a chance to properly look at this yet. It seems to be pretty similar to the imagetable format, but it wasn't obvious how each glyph is stored.
help wanted

opened by jaames 1

Owner

James

yelling about vectors, variables and vertices

GitHub

Hotplugger: Real USB Port Passthrough for VFIO/QEMU!

Hotplugger: Real USB Port Passthrough for VFIO/QEMU! Welcome to Hotplugger! This app, as the name might tell you, is a combination of some scripts (py

66 Nov 24, 2022

LifeSaver automatically, periodically saves USB flash drive data into the PC

LifeSaver automatically, periodically saves USB flash drive data into the PC. Theoriticaly it will work with any any connected drive ex - Hard Disk ,SSD ... But, can't handle Backing up multipatition drives. I can guess, but cannot be sure of, how it will react to multipartiton system.

4 Sep 26, 2021

LUNA: a USB multitool & nMigen library

LUNA is a full toolkit for working with USB using FPGA technology; and provides hardware, gateware, and software to enable USB applications.

750 Dec 28, 2022

Monitor Live USB Plug In & Plug Out Events

I/O - Live USB Monitoring Author: Jonathan Scott @jonathandata1 Date: 3/13/2021 CURRENT VERSION 1.0 This is just a simple bash script that calls a pyt

17 Dec 3, 2022

CircuitPython library for the CH559 USB to Serial chip

CH559 (USB to Serial) CircuitPython Library Why? Because you might want to get keyboard/mouse/gamepad/HID input into your CircuitPython projects witho

3 Nov 19, 2022

USB Rubber Ducky with the Rasberry Pi pico microcontroller

pico-ducky Install Install and have your USB Rubber Ducky working in less than 5 minutes. Download CircuitPython for the Raspberry Pi Pico. Plug the d

3 Oct 8, 2022

Turn your Raspberry Pi Pico into a USB Rubber Ducky

pico-ducky Turn your Raspberry Pi Pico into a USB Rubber Ducky Install Requirements CircuitPython for the Raspberry Pi Pico adafruit-circuitpython-bun

5 Nov 8, 2022

Turns a compatible Raspberry Pi device into a smart USB drive for PS4/PS5.

PSBerry A WIP project for Raspberry Pi, which turns a compatible RPI device into a smart USB drive for PS4/PS5. Allows for save management of PS4 game

2 Jan 15, 2022

Example code to sending USB Gadget multimedia keys via Python

Send Multimedia USB HID Keys via Python As an USB Gadget in Linux This gives a simple script with zero dependencies that can easily run on any Linux d

2 Jan 2, 2023

Sticklog2heatmap - Draw a heatmap of RC sticks from OpenTX logs or USB HID device

sticklog2heatmap Draw a heatmap of RC sticks from OpenTX logs or USB HID device

2 Feb 2, 2022

A python file which I wrote to allow the Dorna Robots API to draw an Image on a 3D plane

Dorna-Robotics-Internship Code In the directory "Code" is a python file which I wrote to allow the Dorna Robots API to draw an Image on a 3D plane. I

2 Dec 6, 2021

An IoT Trivia app that shows you how to take a JSON web API such as the opentdb.com API and stream and display it on a FeatherS2 in an OLED display.

CircuitPython IoT Trivia ESP32-S2 OLED Version An IoT Trivia app that shows you how to take a JSON web API such as the opentdb.com API and stream and

1 Nov 27, 2021

Tools and documentation to aid in modifying the ADI ADALM Pluto firmware

Pluto firmware modifications This repository contains tools and documentation to aid in modifying the ADI ADALM Pluto firmware. Extraction of the Plut

28 Dec 21, 2022

A low power 1U Raspberry Pi cluster server for inexpensive colocation.

Raspberry Pi 1U Server There are server colocation providers that allow hosting a 1U server for as low as $30/month, but there's a catch: There are re

627 Dec 31, 2022

[unmaintained] WiFi tools for linux

Note: This project is unmaintained. While I would love to keep up the development on this project, it is difficult for me for several reasons: I don't

288 Dec 13, 2022

A raspberrypi tools for python

raspberrypi-tools how to install: first clone this project: git clone https://github.com/Ardumine/rpi-tools.git then go to the folder cd rpi-tools and

1 Jan 4, 2022

GUI wrapper designed for convenient service work with TI CC1352/CC2538/CC2652 based Zigbee sticks or gateways. Packed into single executable file

ZigStar GW Multi tool is GUI wrapper firtsly designed for convenient service work with Zig Star LAN GW, but now supports any TI CC1352/CC2538/CC2652 b

133 Jan 1, 2023

I made this so I can control my Tapo L510 light bulb and Govee H6159 light strip using the PyP100 module and the Govee public API

TAPO-And-Govee-Controller I made this so I can control my Tapo L510 light bulb and Govee H6159 light strip using the PyP100 module and the Govee publi

0 Nov 23, 2021

Using a GNSS module (Beidou + GPS) and the mapquest static map API

1 Nov 4, 2021