PRINTDECKDOCS

Architecture · Chapter 1

Overview

Two decks drive two printers on the home network. One cloud service shows their prints to the owner and to friends.

HOME NETWORKPRINTDECK.BEETLEBUG.ORG (AWS)BROWSERS, ANYWHERECuraPrintdeck pluginOctoPrint connectionBrowser on the LANremote screen, /systemprintdeckRaspberry Pi 5, touch screenprogram printdeckKlipper host in GoLulzBot TAZ WorkhorseFDM · Klipper firmwareChiTuBoxChituManagerfinds boards by UDPresindeckRaspberry Pi 5, touch screenprogram printdeckChiTu backend and relayPeopoly Phenomresin · ChiTu boardOctoPrint APIHTTPHTTPUSBUDP :3000via relayUDP :3000CloudFrontTLS 1.2+, security headers, CSPfunction Paths, 404 pageS3 bucketprivatepages, shares,projects, keysAPIGo on Lambdaarm64, 1024 MB/api/v1/Schedulersweep each 15 minOAC, GET/api/*OwnerpasskeyFriendspasskeyViewersshare linkpages: HTML + Go in WebAssembly3D view: three.js r170session token in localStorageHTTPS: pages and APIphoto POSTwith a grantOwner's computerpwf, with the AWScredentials of the ownersigned API requests of a deckPOST to S3 with a grantAWS APIs: pwf deploy, codes, decksbrowser traffic
Figure 1. The parts of Printdeck. The decks connect out to the cloud. The cloud never connects to a deck. pwf runs on the computer of the owner and uses the AWS APIs directly.

1.1 The decks

Each deck is a Raspberry Pi 5 with a touch screen. It runs Printdeck OS, a small read-only Linux system that Buildroot makes. The OS has no package manager, no shell and no SSH. The program printdeck is one static Go binary. It draws the touch screen, serves a remote screen at http://<deck>.local, and keeps the print history.

  • printdeck drives the FDM printer, a LulzBot TAZ Workhorse. printdeck klippy is a Go port of the Klipper host. It talks to the Klipper firmware on the printer board over USB. The deck talks to the Klipper host on its API socket. Slicers send files through the part of the OctoPrint API that Cura, OrcaSlicer and PrusaSlicer use.
  • resindeck drives the resin printer, a Peopoly Phenom. The ChiTu backend sends one line of text in one UDP packet to port 3000 of the ChiTu board. The board sends one line back. The deck also runs a relay on its own UDP port 3000, so ChiTuBox (its ChituManager) lists the deck as a printer.

The relay answers the discovery broadcast of ChituManager (M99999) with the line of the board. It keeps each upload (M28, the data packets, M29) as a file on the deck. ChituManager sends its data packets with no wait and does not resend them. So the relay answers each packet itself, and then the deck sends the file to the board one packet at a time. The deck keeps a copy of each sliced file. That copy gives the layer plan, the layer pictures and the 3D cells of a resin print (section 5).

1.2 The cloud service

The service is at https://printdeck.beetlebug.org. It is serverless, in one AWS CloudFormation stack in us-east-1. A second, older stack, printdeck-relay, keeps the secret of the push relay and a relay function for old copies of the iPhone app. The owner makes the stack with pwf deploy on their own computer (section 1.3).

  • CloudFront is the only public entry. It sends /api/* to the Lambda function URL with no cache. It serves all other addresses from the bucket. It adds the security headers and the Content-Security-Policy to each reply.
  • S3 keeps all the data as files in one private bucket. CloudFront reads only the listed keys, through Origin Access Control (OAC): the pages, the shares, the public pages, the pictures of the comments on pull requests (gh/*), and the files of the projects behind a signed cookie. The API reads and writes all keys.
  • The API is one Go program in one Lambda function, printdeck-cloud-api (arm64, 1024 MB, 60 s). It serves /api/v1/, and also the push relay of the iPhone app at /api/v1/relay/. A schedule runs its sweep every 15 minutes to delete or move old shares. For the jobs after a request (the comments on pull requests and the checks of their state), the function invokes itself with an event. A failed job does not run again. The API reads the records of a project 64 at a time, keeps the name of the owner in memory for 5 minutes, and writes one log line for each request with the route, the time and the count of bucket calls.
  • GitHub Actions of a linked repository sends the plans and the builds of the project to the API, with an OIDC token of GitHub (section 6). With the GitHub App, the API also starts the slice runs and writes a comment on each pull request.
  • The pages are static HTML. Their logic is Go, compiled to WebAssembly (cmd/pwf-web). pwf uses TinyGo when it finds it, because TinyGo makes a file about 5 times smaller. The 3D views use three.js r170 from the bucket.
AWS ACCOUNT · US-EAST-1 Clients browsers the iPhone app the decks GitHub Actions GitHub API PR comments, checks APNs pushes to iPhones CloudFront the only public entry · Route 53 alias, ACM certificate /api/* → the function URL of the API, no cache /x/* → the bucket, only with a signed cookie (key group) all else → the bucket, through OAC A CloudFront function (Paths) maps the short page addresses to their files. Lambda printdeck-cloud-api Go · arm64 · 1024 MB · 60 s THREE TRIGGERS 1 function URL: the API, /api/v1/ 2 an async invoke of itself: the jobs PR comments and checks, no retry 3 the schedule: the sweep ALSO the push relay at /api/v1/relay/ /api/* OAC S3 bucket all data: JSON records, files, pages private: read by CloudFront (OAC) and by the API only Secrets Manager the cookie key of the files the key of the GitHub App the relay secret (APNs key) EventBridge Scheduler every 15 minutes STACK PRINTDECK-RELAY Lambda printdeck-relay Go · arm64 · 128 MB · 15 s · own function URL the first relay, for an app that has its URL
Figure 2. The AWS pieces of the service. Two Lambda functions run Go on arm64. printdeck-cloud-api does all the work of the service: the API, the jobs after a request, the sweep, and the push relay. At a cold start it reads its 3 secrets at the same time. printdeck-relay is the first relay, in its own stack. It shares the relay secret, so the send tokens of the apps stay valid.
Requesthttps://printdeck.beetlebug.org/…CloudFrontHTTPS onlyviewer request:function PathsAPI on Lambda/api/*, no cache, all methodsSigned cookie check/x/*: key group of the files;policy for /x/<project>/*Other addressespages, s/*, p/*, gh/*, assets/*Auth in the APIdeck signatures, tokens,owner keys of sharesS3 bucket (OAC)GET of the listed keys;x/* only throughthe cookie check;edge cache/404.htmlfor each 403 or 404no valid cookie: 403Paths changes the address of the file:/projects/… → /app/p/<slug>/<n> → /p/<slug>
Figure 3. How CloudFront routes a request. The API never replies 403 or 404. A 403 or 404 from S3 or from the cookie check shows the "not found" page with status 404.

1.3 The owner tool pwf

pwf (cloud/cmd/pwf) is a command-line tool. The owner runs it on their own computer, with the AWS credentials of the owner. It does not run on a deck, and it does not run in AWS. It uses the AWS APIs directly: CloudFormation, S3, Lambda, Secrets Manager, Route 53 and STS. It does not use CloudFront or the API of the service.

AWS ACCOUNT (US-EAST-1)Owner's computerpwf (cloud/cmd/pwf)AWS credentialsof the ownernot on a deck, not in AWSdeployStack: bucket, CloudFront, Lambda, roles;pages; RSA key of the file cookiesenroll-codeData bucket: writescodes/<sha256>.json (deck, 1 hour)decks, decks remove IDData bucket: lists ordeletes decks/<id>.jsonrelay set-apple-keySecrets Manager: the APNs keyof the push relay; LambdadevThis computer: the whole serviceat localhost:8790, local datachanges who can reach the service
Figure 4. Where pwf runs, and what each command reaches. The orange commands change who can reach the service.
CommandWhat it doesEffect on the auth
pwf deployBuilds the Lambda function (Go, linux/arm64) and the WebAssembly pages. At the first deploy, makes an RSA key pair for the file cookies and keeps the private key in the secret <stack>-files-key. Makes or changes the CloudFormation stack with the public key. Uploads the pages to the data bucket, and writes the pages of the running shares again. For each public project, it runs the whole publish again, so it also repairs a publish that stopped before its end.Makes the private data bucket, its bucket policy, CloudFront with the CSP and the key group of the files, and the role of the function. The API makes keys/session in this bucket at its first use.
pwf enroll-codeWrites codes/<sha256>.json straight to the data bucket, and shows the code. The code works once, for 1 hour.The only way to get a deck enrollment code. It uses the AWS rights of the owner, so the code does not go through the API.
pwf decks, pwf decks remove IDLists the files in decks/, or deletes one.A removed deck gets 401 at its next request.
pwf relay set-apple-keyWrites the APNs key of the push relay into Secrets Manager, and makes the functions start again to read it.No effect on the sign-in.
pwf github-app --id N --key app.pemWrites the App ID and the private key of the GitHub App into the secret <stack>-github-app. The next pwf deploy gives the secret to the function.The function then starts the slice runs of the builds (section 6.6), and writes the comments on the pull requests. Each App token works for one repository, with only the permission of its call: Actions to start a run, Pull requests to read a pull request or to write a comment.
pwf devRuns the whole service on the computer at localhost:8790, with the data in memory or in a folder (-data). It shows a deck enrollment code and an owner link.Needs no AWS credentials. It has its own data and its own keys/session.
Through CloudFrontthe bucket policy lists these keysindex.html, 404.htmlthe home page and the page for a missing fileapp, owner, jthe app page: projects, owner passkey, invitesassets/*, .well-known/*CSS, WebAssembly, three.js, printer modelss/<id>the page of a shares/<id>/status.json, ready.jsonthe print state; Ready flag, note, photoss/<id>/cam-<view>.jpg, lapse/<n>.jpgcamera frames and time lapse framess/<id>/model.jpg, plan.jsonthe picture of the model, layer timess/<id>/part.binthe resin cells for the 3D views/<id>/photos/*photos of the owner of the share, cleanedp/<slug>, p/<slug>/*the public page of a project and its copiesx/*/prints/*/*, x/*/photos/*.jpg, x/*/live/*/*print files, photo pictures, live pictures: with the cookiex/*/plans/*/*, x/*/builds/*/*plan models and PDFs, sliced files: with the cookiegh/*pictures of the comments on pull requests, random namesPrivate: only the API reads themno CloudFront accesskeys/sessionthe HMAC key of tokens and ceremony stateowner.jsonthe name of the ownerowners/<credential>.jsonowner passkeys: public key, countermembers/<credential>.jsonmember passkeys: user handle, list of projectsdecks/<id>.jsonenrolled decks: Ed25519 public keycodes/<sha256>.jsonenrollment codes and owner codesinvites/<sha256>.jsoninvites that are not used yetshares/<id>.jsonshare records: deck, SHA-256 of owner keyx/<id>/project.json, prints/*.jsonproject and print records; also photos/*.json, live/*.jsonx/<id>/plans/*.json, builds/*.jsonplan and build records; also prs/*.json: the PR commentsrepos/<owner>/<name>.jsonthe project of a GitHub repositoryoidc/<sha256>the IDs of the GitHub tokens that the API tooknames/*, printers/*project slugs; printers: queue, plates, removalsup/*photo uploads before the API cleans them
Figure 5. The layout of the bucket. The bucket blocks all public access. CloudFront can read only the keys on the left. The keys on the right have the codes, the passkeys, the session key, the repository links, the used GitHub tokens and the state of the pull request comments.

ContentsNext: 2 Identity and trust