{"id":13516968,"url":"https://github.com/scottbez1/splitflap","last_synced_at":"2025-05-13T22:12:13.680Z","repository":{"id":38400757,"uuid":"43653150","full_name":"scottbez1/splitflap","owner":"scottbez1","description":"DIY split-flap display","archived":false,"fork":false,"pushed_at":"2025-05-13T04:56:49.000Z","size":21329,"stargazers_count":3411,"open_issues_count":22,"forks_count":295,"subscribers_count":91,"default_branch":"master","last_synced_at":"2025-05-13T05:28:45.674Z","etag":null,"topics":["arduino","diy","kicad","laser-cutting","openscad","split-flap","splitflap"],"latest_commit_sha":null,"homepage":"https://scottbez1.github.io/splitflap","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scottbez1.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"scottbez1"}},"created_at":"2015-10-04T21:17:52.000Z","updated_at":"2025-05-13T04:56:52.000Z","dependencies_parsed_at":"2023-02-01T04:46:06.450Z","dependency_job_id":"23c9a245-38a0-401a-bc3b-04ed51772dc6","html_url":"https://github.com/scottbez1/splitflap","commit_stats":{"total_commits":629,"total_committers":20,"mean_commits":31.45,"dds":0.09856915739268679,"last_synced_commit":"e89f35adc2a8d8cf842fe5c0e88be590dd84bcf9"},"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottbez1%2Fsplitflap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottbez1%2Fsplitflap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottbez1%2Fsplitflap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottbez1%2Fsplitflap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scottbez1","download_url":"https://codeload.github.com/scottbez1/splitflap/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254036842,"owners_count":22003654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arduino","diy","kicad","laser-cutting","openscad","split-flap","splitflap"],"created_at":"2024-08-01T05:01:27.919Z","updated_at":"2025-05-13T22:12:08.648Z","avatar_url":"https://github.com/scottbez1.png","language":"JavaScript","funding_links":["https://github.com/sponsors/scottbez1"],"categories":["JavaScript","HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# Split-Flap Display\n\nThis is a DIY ESP32-based [split-flap display](https://en.wikipedia.org/wiki/Split-flap_display), optimized for easy assembly at home in small quantities but able to be scaled up to large affordable displays.\n\n![animated rendering](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_animation.gif)\n\u003cimg src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/all_flaps.gif\" height=\"320\" /\u003e\n\n[![Build Status](https://github.com/scottbez1/splitflap/actions/workflows/3d.yml/badge.svg?branch=master)](https://github.com/scottbez1/splitflap/actions/workflows/3d.yml?query=branch%3Amaster)\n[![Build Status](https://github.com/scottbez1/splitflap/actions/workflows/electronics.yml/badge.svg?branch=master)](https://github.com/scottbez1/splitflap/actions/workflows/electronics.yml?query=branch%3Amaster)\n[![Build Status](https://github.com/scottbez1/splitflap/actions/workflows/pio.yml/badge.svg?branch=master)](https://github.com/scottbez1/splitflap/actions/workflows/pio.yml?query=branch%3Amaster)\n\nThe [splitflap community Discord server](https://discord.com/invite/wgehm3PcrC) is the best place to keep up with the latest changes or ask questions about the project!\n\nWant to help support development or just say \"thanks\"? Consider a one-time or monthly sponsorship:\n\n| [:heart: Sponsor scottbez1 on GitHub](https://github.com/sponsors/scottbez1) |\n|---|\n\n\u003ca href=\"https://www.youtube.com/watch?v=UAQJJAQSg_g\" target=\"_blank\"\u003e\n  \u003cimg src=\"renders/howItWorksThumbnail.jpg\" height=320 /\u003e\n\u003c/a\u003e\n\n**Using this project in a commercial setting or for paid client work?** Go right ahead - it's open source (just make sure to follow the terms of the Apache License)! I would, however, ask that you consider [sponsoring the project](https://github.com/sponsors/scottbez1). I've been developing and maintaining this project in my free time for over 10 years, and I'd love to continue working on it. Sponsorships allow me to pay for prototypes and development tools that make this project possible. Unlike pure software projects, every iteration has real hardware costs; sponsorships allow me to keep iterating and improving the project faster. Thank you!\n\n\n# Current Status\n[You can download the **latest stable releases** of the hardware designs from the official 'releases' page.](https://github.com/scottbez1/splitflap/releases)\n\nReleases have been tested and used to produce working units, but as this is a continuously evolving open-source project, there may always be minor issues and/or incomplete documentation from time to time.\n\nHere's a video of a large 108-module display powered by 18 Chainlink Driver boards and a Chainlink Base:\n\n[![Video: animations on 108-module display](https://raw.githubusercontent.com/wiki/scottbez1/splitflap/images/animationsThumb.gif)](https://youtu.be/g9EPabcxBsM)\n\n## Stable v2 Mechanical Release\nAs of 2025-01-19, the v2 refresh of the mechanical and sensor design is considered stable and recommended for new builds.\n\n**Here's what's new in v2:**\n\n- **52 flaps per module** for more character/symbol options\n- **New printed flap design (\"Epilogue\")** with 52 flaps per set (see animation above), including several color-block flaps\n- **Updated enclosure** and mechanical parts (laser-cut) to accomodate 52 flaps\n  - Motor wires now exit downward for less awkward wiring!\n- **New sensor PCB** that's easier to assemble and includes an LED for checking the magnet status\n- **Software-configurable calibration** rather than mechanical sensor adjustment\n\n**But many things are staying the same for easy upgrades/compatibility:**\n- No change to flap dimensions!\n- No changes to Chainlink Driver, Chainlink Buddy boards, or system architecture!\n- 40-flap modules are still an officially supported option!\n- Open source, as always!\n- v0 parts (sensor kits) will continue to be stocked at Bezek Labs through mid-2025; don't worry if you haven't finished your build yet, the old sensor kits aren't going away for a little while!\n\nI'd love to hear your thoughts and questions about this project, and happy to incorporate any feedback you might have into these designs! Please feel free (and encouraged) to [open GitHub issues](https://github.com/scottbez1/splitflap/issues/new), email me directly, reach out [on Bluesky](https://bsky.app/profile/scottbez1.bsky.social), and [get involved](https://github.com/scottbez1/splitflap/pulls) in the open source development and let's keep chatting and building together!\n\n# Build Your Own\nIf you have any questions, please don't hesitate to ask in the [community Discord server](https://discord.gg/Hxnftc8PyW)!\n\n* [**Documentation Index**](/docs/DocumentationIndex.md)\n* [**Ordering guide (the \"easy\" route) v2**](/docs/v2/OrderingEasy.md)\n* [**Comprehensive ordering guide**](/docs/v2/OrderingComplete.md)\n* [**Chainlink Driver Electronics User Guide**](/docs/ElectronicsGuide.md)\n* [**Assembly instructions v2**](/docs/v2/Assembly.md)\n* [**Latest stable releases**](https://github.com/scottbez1/splitflap/releases)\n\n# Table of Contents\n- [Design Overview](#design-overview)\n  - [Mechanical](#mechanical)\n    - [Combined front panel (script)](#combined-front-panel-script)\n    - [Flap font/sticker generator (script)](#flap-fontsticker-generator-script)\n  - [Electronics](#electronics)\n    - [Sensor PCBs](#sensor-pcbs-1-per-module)\n    - [Chainlink Driver](#chainlink-driver-1-per-6-modules)\n    - [Chainlink Buddy \\[T-Display\\]](#chainlink-buddy-t-display-1-for-entire-display)\n    - [Advanced items](#advanced-items)\n      - [Chainlink Buddy \\[Breadboard\\]](#chainlink-buddy-breadboard-1-for-entire-display-alternative-to-t-display)\n      - [Chainlink Base](#chainlink-base-1-for-entire-display-large-displays)\n    - [Older designs](#older-designs)\n      - [Classic controller](#classic-controller-electronics-deprecated)\n    + [Miscellaneous Tools](#miscellaneous-tools)\n      - [3D Printed Tools](#3d-printed-tools)\n      - [Chainlink Driver Tester](#chainlink-driver-tester)\n  * [Code](#code)\n    + [Firmware](#firmware)\n    + [Computer Control Software](#computer-control-software)\n- [Contributing/Modifying](#contributingmodifying)\n  * [3D Design](#3d-design)\n  * [Electronics Design](#electronics-design)\n\n# Design Overview\n\n## Mechanical\nThe mechanical/structural components are made from laser-cut 3mm MDF or acrylic, and held together with M4 bolts and nuts. The design is parametric and built using OpenSCAD. See below for more info on rendering/modifying the design.\n\nYou can view an interactive 3d model of the design [here](https://scottbez1.github.io/splitflap/embed.html?branch=master).\n\nThe v2 mechanical design officially supports variants with 52 flaps (perfect for use with the new [\"Epilogue\" printed flaps](https://bezeklabs.etsy.com/listing/1685633114/)) and 40 flaps. But you can always modify the design to customize it further.\n\n### v2 (52-flap module option - recommended)\n![2d laser cut rendering](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_raster-52.png)\n\nInstructions: [v2 assembly guide](/docs/v2/Assembly.md)\n\nModule dimensions: \u003cimg height=\"18\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-52-module_dimensions.svg\" /\u003e\n\nLatest auto-generated (untested!) artifacts\u003csup\u003e:warning:\u003c/sup\u003e:\n* For Ponoko 3mm MDF ([svg](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-52-ponoko-3mm-mdf_1x.svg)) \u003cimg height=\"18\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-52-ponoko-3mm-mdf_1x_dimensions.svg\" /\u003e\n* For Ponoko 3mm acrylic ([svg](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-52-ponoko-3mm-acrylic_1x.svg)) \u003cimg height=\"18\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-52-ponoko-3mm-acrylic_1x_dimensions.svg\" /\u003e\n* For generic material (0.18mm kerf correction) ([svg](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-52.svg))\n* For Elecrow 3mm Wood ([zipped pdf](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-52-elecrow-3mm-wood_1x.zip))\n* For Elecrow 3mm Acrylic ([zipped pdf](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-52-elecrow-3mm-acrylic_1x.zip))\n\n\u003csup\u003e:warning:\u003c/sup\u003eFor tested/stable/recommended artifacts, always use the [latest release](https://github.com/scottbez1/splitflap/releases) instead, as the links on this page will change over time.\n\n### v2 (40-flap module option)\n![2d laser cut rendering](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_raster-40.png)\n\nInstructions: [v2 assembly guide](/docs/v2/Assembly.md)\n\nModule dimensions: \u003cimg height=\"18\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-40-module_dimensions.svg\" /\u003e\n\nLatest auto-generated (untested!) artifacts\u003csup\u003e:warning:\u003c/sup\u003e:\n* For Ponoko 3mm MDF ([svg](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-40-ponoko-3mm-mdf_1x.svg)) \u003cimg height=\"18\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-40-ponoko-3mm-mdf_1x_dimensions.svg\" /\u003e\n* For Ponoko 3mm acrylic ([svg](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-40-ponoko-3mm-acrylic_1x.svg)) \u003cimg height=\"18\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-40-ponoko-3mm-acrylic_1x_dimensions.svg\" /\u003e\n* For generic material (0.18mm kerf correction) ([svg](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-52.svg))\n* For Elecrow 3mm Wood ([zipped pdf](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-40-elecrow-3mm-wood_1x.zip))\n* For Elecrow 3mm Acrylic ([zipped pdf](https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_laser_vector-40-elecrow-3mm-acrylic_1x.zip))\n\n\u003csup\u003e:warning:\u003c/sup\u003eFor tested/stable/recommended artifacts, always use the [latest release](https://github.com/scottbez1/splitflap/releases) instead, as the links on this page will change over time.\n\n### Combined front panel (script)\nBy default, the design will have a separate laser-cut faceplate for each individual module. For larger displays you may want to combine front panels into a single piece, and the repo has a script to help with this.\n\nYou can modify:\n* Number of rows and columns\n* Horizontal and vertical spacing/separation of modules\n* Overall outer width and height of the panel\n\nThere are a lot of options; see the `--help` for explanations.\n\n#### Example 1 - Laser cut 6x1\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_front_panel-52-elecrow-3mm-acrylic-6x1.svg\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_front_panel_raster-52-elecrow-3mm-acrylic-6x1.png\"/\u003e\n\u003c/a\u003e\n\n```\npython3 3d/scripts/generate_combined_front_panel.py \\\n  --kerf-preset elecrow-3mm-acrylic \\\n  --num-flaps 52 \\\n  --cols 6 \\\n  --rows 1 \\\n  --spacing-x 0 \\\n  --spacing-y 0 \\\n  --frame-margin-x 0 \\\n  --frame-margin-y 0 \\\n  --center-mode module\n```\n\n#### Example 2 - CNC router 12x2, with frame margin\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_front_panel-52-3.175-20x4margin-12x2.svg\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/3d_front_panel_raster-52-3.175-20x4margin-12x2.png\"/\u003e\n\u003c/a\u003e\n\nFor CNC cutting, the script supports rendering a vector file optimized for thicker material (e.g. 6mm MDF) where only the bolt-holes will be through-cut. In this mode, the slots for the top/bottom enclosure pieces can be cut as ~4mm pockets so they aren't visible from the front face. The script automatically generates dog-bone shapes for these pocket cuts.\n\nThis example also demonstrates use of the --frame-margin-x and --frame-margin-y options to add an additional margin of 20mm horizontally and 4mm vertically to the front panel dimensions.\n\n```\npython3 3d/scripts/generate_combined_front_panel.py \\\n  --tool-diameter 3.175 \\\n  --num-flaps 52 \\\n  --cols 12 \\\n  --rows 2 \\\n  --spacing-x 0 \\\n  --spacing-y 0 \\\n  --frame-margin-x 20 \\\n  --frame-margin-y 4 \\\n  --center-mode module\n```\n\n### Flap font/sticker generator (script)\nIf you'd like to print your own flaps, or cut custom vinyl letter stickers, the project includes a script (`generate_fonts.py`) to generate vector design files, which is extremely configurable:\n\n* Font for text\n  * This is further customizable in `flap_fonts.scad` -- this is where font parameters are defined like the overall font scale, position offsets, and even per-character scale and position overrides in case you need to tweak particularly problematic letters (e.g. a really wide \"W\" or an \"@\" with too thin of a stroke).\n* Character-set - which letters/numbers/symbols/colors are included and in what order\n* Bleed - extends rendering past the borders of the flaps to compensate for slight misalignment of printing and cutting operations\n* Keepout areas - option to highlight keepout violations for manual review, automatically clip them, or ignore them\n* Rendering options:\n    * Single-sided - useful for previewing how all letters will look on flaps\n    * Front/back - for batch duplex printing, generate separate front-side and back-side files (e.g. sign shop printing on a flat sheet of PVC)\n    * Side-by-side - for individual flap printing, each flap's front design is laid out side-by-side with its back design\n\nThere are a lot of options; see the `--help` for explanations.\n\n\n#### Example 1 - Epilogue font, rendered in front+back pairs, default character set, 1mm bleed (for printing)\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/font_example-Epilogue-1mmBleed.svg\"\u003e\n\u003cimg width=\"400\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/3d/font_example-Epilogue-1mmBleed.png\"/\u003e\n\u003c/a\u003e\n\n```\npython3 3d/scripts/generate_fonts.py \\\n  --mode side-by-side \\\n  --font Epilogue \\\n  --columns 4 \\\n  --bleed 1 \\\n  --fill\n```\n\n\n## Electronics\n\u003e [!NOTE]\n\u003e For small displays (up to 3 modules), you can skip the custom controller boards and use off-the-shelf ULN2003A driver\nmodules plugged into an Arduino Uno. This is [partially documented in the wiki](https://github.com/scottbez1/splitflap/wiki/Electronics#basic-prototyping-alternative-electronics-approach)\n\u003e but may require some additional tinkering to get it to work. _Help wanted: if you'd like to help improve these instructions,\n\u003e please reach out in the Discord server, thanks!_\n\nThe \"Chainlink\" electronics system is designed to support long chains of driver boards to control medium/large displays (up to 100+ split-flap modules).\nIt's also designed to be easy and cheap to order pre-assembled or build yourself, especially in higher\nquantities, due to its simple BOM and surface-mount components.\n\nTo build a display, you'll need 3 different electronics:\n* One **Sensor PCB** for every split-flap module\n* One **Chainlink Driver** board for every 6 split-flap modules. This is what interfaces with the motors and sensors of each module. Chainlink Driver boards can be chained together to construct a large display.\n* An ESP32 microcontroller board. There are a few options:\n    * For small/medium displays, one of the **Chainlink Buddy** boards are recommended\n        * **Chainlink Buddy [T-Display]**  holds a Lilygo T-Display ESP32 module which includes a built-in LCD and 2 buttons\n        * **Chainlink Buddy [Breadboard]** makes it easy to connect a Chainlink Driver to a breadboard for prototyping, though you can also easily connect a Chainlink Driver to a breadboard with a few dupont wires.\n    * For large displays, the **Chainlink Base** provides a number of advanced features: central\npower management/distribution and fault monitoring, UART and RS-485 connections, configuration switches, and status LEDs.\n\n### Sensor PCBs (1 per module)\nEach module needs a hall-effect sensor for start-up calibration and fault monitoring. \n\n#### Sensors v2\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/panelized_sensor_smd-front-3d.png\"\u003e\n\u003cimg width=\"320\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/panelized_sensor_smd-front-3d.png\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/panelized_sensor_smd-back-3d.png\"\u003e\n\u003cimg width=\"320\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/panelized_sensor_smd-back-3d.png\"/\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-schematic.pdf\"\u003e\n\u003cimg width=\"320\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-schematic.png\"/\u003e\n\u003c/a\u003e\n\nNew sensors for the v2 laser-cut hardware - these use surface mount components and are optimized for PCB assembly at JLCPCB. These new sensors are not compatible with v0.7 and older laser-cut hardware.\n\nPacks of 6 sensors are [available mostly-assembled in the Bezek Labs store](https://bezeklabs.etsy.com/listing/1696745674),\nand come with the right-angle pin headers and magnets you'll need. Purchases support continued development of this project.\n\nLatest auto-generated (untested!) artifacts\u003csup\u003e:warning:\u003c/sup\u003e:\n\n* Schematic [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-schematic.pdf)\n* Interactive BOM (for manual assembly) [interactive](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-ibom.html)\n* Fabrication files (single)\n  * NOTE: PCBs must be 0.8mm! (rather than the more typical 1.6mm thickness)\n  * PCB gerbers [zip](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-jlc/gerbers.zip)\n  * PCB BOM (for JLCPCB assembly) [csv](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-jlc/bom.csv)\n  * PCB CPL (for JLCPCB assembly) [csv](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-jlc/pos.csv)\n* Fabrication files (panelized)\n  * NOTE: PCBs must be 0.8mm! (rather than the more typical 1.6mm thickness)\n  * PCB gerbers [zip](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-panelized-jlc/gerbers.zip)\n  * PCB BOM (for JLCPCB assembly) [csv](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-panelized-jlc/bom.csv)\n  * PCB CPL (for JLCPCB assembly) [csv](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-v2/sensor_smd-panelized-jlc/pos.csv)\n* Purchase sensor kits in the US: [Bezek Labs](https://bezeklabs.etsy.com/listing/1696745674)\n\n\u003csup\u003e:warning:\u003c/sup\u003eFor tested/stable/recommended artifacts, always use the [latest release](https://github.com/scottbez1/splitflap/releases) instead, as the links on this page will change over time.\n\n### Chainlink Driver (1 per 6 modules)\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-3d.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-3d.png\"/\u003e\n\u003c/a\u003e\n\nKey features:\n* Controls 6 split-flap modules per board\n* Primarily SMD and all components (except the pin headers and motor connectors) are available in JLCPCB's parts library\nfor easy SMD/THT assembly\n* Clock and latch lines are buffered on each board with a 74HC125 to support longer chains\n* 2 bits of loopback error checking per board (connecting 2 spare output bits on output shift registers to 2 spare inputs) allows the controller\nto validate data integrity up and down the whole chain\n* Module order goes from right-to-left since this is intended to be installed and accessed from *behind* the modules\n\nChainlink Driver boards are [available mostly-assembled in the Bezek Labs store](https://bezeklabs.etsy.com/listing/1123280069/splitflap-chainlink-driver-v11),\nand come with the additional connectors and ribbon cables you'll need. Purchases support continued development of this project.\n\nMore information on building and using Chainlink Drivers is available in the [Chainlink Driver User Guide](/docs/ElectronicsGuide.md).\n\nOr if you'd like to order these directly from a fab, this design is optimized for assembly at JLCPCB, and files are automatically generated\nfor ordering *assembled* PCBs there. Or if you wish to assemble this board yourself instead of paying for assembly, \nyou can view the [interactive BOM/placement tool](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/bom/chainlinkDriver-ibom.html)\n\nDepending on available stock at JLCPCB, you may need to manually modify the BOM file to use alternative components, or regenerate the files\nyourself using `export_jlcpcb.py` and specifying one or more `LCSC_ALT_*` field names to use a pre-selected alternative part number. See\nthe schematic for available pre-selected alternatives (check the symbol's properties/fields).\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-schematic.pdf\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-schematic.png\"/\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-pcb-raster.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-pcb-raster.png\"/\u003e\n\u003c/a\u003e\n\nLatest auto-generated (untested!) artifacts\u003csup\u003e:warning:\u003c/sup\u003e:\n\n* Schematic [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-schematic.pdf)\n* PCB overview [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-pcb-packet.pdf)\n* PCB gerbers [zip](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-jlc/gerbers.zip)\n* PCB bom (for JLCPCB assembly) [csv](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-jlc/bom.csv)\n* PCB CPL (for JLCPCB assembly) [csv](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/chainlinkDriver-jlc/pos.csv)\n* PCB bom (for manual assembly) [interactive](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink/bom/chainlinkDriver-ibom.html)\n\n\u003csup\u003e:warning:\u003c/sup\u003eFor tested/stable/recommended artifacts, always use the [latest release](https://github.com/scottbez1/splitflap/releases) instead, as the links on this page will change over time.\n\n### Chainlink Buddy \\[T-Display\\] (1 for entire display)\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-3d.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-3d.png\"/\u003e\n\u003c/a\u003e\n\nThe Chainlink Buddy \\[T-Display\\] is a convenient way to connect a T-Display ESP32 board (recommended microcontroller) to a chain\nof Chainlink Drivers.\n\nKey features:\n* TTGO T-Display ESP32 module as the controller, which includes USB-C, color IPS LCD display and buttons\n* Extra terminals for every pin of the T-Display allow you to connect any other peripherals to the ESP32 (the connection to the Chainlink Driver requires _only 4_ of the GPIOs)\n* Optional barrel jack makes it easy to use a \"wall wart\" AC adapter/power-supply (since the Chainlink Driver only has screw terminals for power) -- plug in a 12V supply\nand then run a wire from the onboard screw terminals to the Chainlink Driver's motor power screw terminals.\n* Optional 5V regulator allows for powering the ESP32 without a USB connection, using the 12V motor power supply\n\n\nChainlink Buddy \\[T-Display\\] boards are [available in the Bezek Labs store](https://bezeklabs.etsy.com/listing/1109357786/splitflap-chainlink-buddy-t-display),\nand come with the additional connectors you'll need. Purchases support continued development of this project. \n\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-schematic.pdf\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-schematic.png\"/\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-pcb-raster.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-pcb-raster.png\"/\u003e\n\u003c/a\u003e\n\nLatest auto-generated (untested!) artifacts\u003csup\u003e:warning:\u003c/sup\u003e:\n\n* Schematic [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-schematic.pdf)\n* PCB ([gerbers](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-jlc/gerbers.zip) / [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-pcb-packet.pdf))\n* Panelized PCB ([gerbers](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-panelized-jlc/gerbers.zip) / [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/chainlinkBuddyTDisplay-panelized-pcb-packet.pdf))\n* PCB bom (for manual assembly) [interactive](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-t-display/bom/chainlinkBuddyTDisplay-ibom.html)\n\n\u003csup\u003e:warning:\u003c/sup\u003eFor tested/stable/recommended artifacts, always use the [latest release](https://github.com/scottbez1/splitflap/releases) instead, as the links on this page will change over time.\n\n### Advanced items\n#### Chainlink Buddy \\[Breadboard\\] (1 for entire display; alternative to T-Display)\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-3d.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-3d.png\"/\u003e\n\u003c/a\u003e\n\nThe Chainlink Buddy \\[Breadboard\\] makes it easy to connect a Chainlink Driver to a breadboard for prototyping. You could use 5 dupont wires and have a\nmessy rats nest, or you could use a single ribbon cable and this slick breakout board.\n\nChainlink Buddy \\[Breadboard\\] boards are [available in the Bezek Labs store](https://bezeklabs.etsy.com/listing/1123863267/splitflap-chainlink-buddy-breadboard),\nand come with the additional connectors you'll need. Purchases support continued development of this project. \n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-schematic.pdf\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-schematic.png\"/\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-pcb-raster.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-pcb-raster.png\"/\u003e\n\u003c/a\u003e\n\nLatest auto-generated (untested!) artifacts\u003csup\u003e:warning:\u003c/sup\u003e:\n\n* Schematic [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-schematic.pdf)\n* PCB ([gerbers](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-jlc/gerbers.zip) / [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-pcb-packet.pdf))\n* Panelized PCB ([gerbers](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-panelized-jlc/gerbers.zip) / [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/chainlinkBuddyBreadboard-panelized-pcb-packet.pdf))\n* PCB bom (for manual assembly) [interactive](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-buddy-breadboard/bom/chainlinkBuddyBreadboard-ibom.html)\n\n\u003csup\u003e:warning:\u003c/sup\u003eFor tested/stable/recommended artifacts, always use the [latest release](https://github.com/scottbez1/splitflap/releases) instead, as the links on this page will change over time.\n\n#### Chainlink Base (1 for entire display; large displays)\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/chainlinkBase-3d.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/chainlinkBase-3d.png\"/\u003e\n\u003c/a\u003e\n\nFor larger displays, you should take additional care to make the hardware more robust to potential faults. The Chainlink Base is an experimental (but unsupported) controller design that adds some additional functionality. This has been tested and appears to work, but is not recommended for general use.\n\nThe Chainlink Base PCB is an optional alternative to a Chainlink Buddy, designed for particularly large displays.\nIt hosts the ESP32 and adds additional connectivity options (terminals for UART and RS485 serial) and\npower distribution (independently-monitored power channels for multiple \"zones\" of Driver boards).\n\nKey features:\n* TTGO T-Display ESP32 module as the controller, which includes USB-C, color IPS LCD display and buttons\n* Optional master relay output for 12V PSU control (5V relay, up to ~500mA coil current)\n  * Future firmware will power on the 12V PSU after a startup self-test, and power off PSU in case of any faults\n* 5 channels of independently monitored 12V switches for powering groups of Chainlink Driver boards (6-10A max per channel)\n  * Depending on the motors you use, each channel may be able to power about 6 Chainlink Driver boards which is 36 splitflap modules\n  * Each channel includes an automotive fuse holder for additional over-current protection\n  * INA219 and shunt resistor provide high fidelity voltage and current monitoring \n  * Firmware will power on each channel after a startup self-test, and power off the channel in case of any faults\n  * 3.3V output for powering many Chainlink Driver boards\n* Flexible controller input power\n  * USB power from the T-Display works by default, though external power is recommended for larger displays\n  * Regulated 5V can be connected directly to the screw terminals, or\n  * if you are using an always-on 12V PSU without a master relay, you can install a buck module and power the board from 12V using the 7-28V screw terminals\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/chainlinkBase-schematic.pdf\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/chainlinkBase-schematic.png\"/\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/chainlinkBase-pcb-raster.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/chainlinkBase-pcb-raster.png\"/\u003e\n\u003c/a\u003e\n\nLatest auto-generated (untested!) artifacts\u003csup\u003e:warning:\u003c/sup\u003e:\n\n* Schematic [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/chainlinkBase-schematic.pdf)\n* PCB overview [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/chainlinkBase-pcb-packet.pdf)\n* PCB gerbers [zip](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/chainlinkBase-jlc/gerbers.zip)\n* PCB bom (for manual assembly) [interactive](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-base/bom/chainlinkBase-ibom.html)\n\n\u003csup\u003e:warning:\u003c/sup\u003eThere are currently no stable releases of this board, and none are planned. Some past variants of this board have been used, to some success, but it is not considered an\nofficially supported design\n\n## Older designs\n### Classic Controller Electronics (deprecated)\nThe Classic driver board is deprecated and unsupported.\n\nThe Classic controller board was designed to plug into an Arduino like a shield, and could control 4 stepper motors.\nUp to 3 driver boards could be chained together, for up to 12 modules controlled by a single Arduino.\n\nThe driver uses 2 MIC5842 low-side shift-register drivers, with built-in transient-suppression diodes, to control the motors, and a 74HC165 shift register to read from 4 hall-effect magnetic home position sensors.\nThere are optional WS2812B RGB LEDs which can be used to indicate the status of each of the 4 channels.\n\n\n### Miscellaneous Tools\n\n#### 3D Printed Tools\nThe project also includes a number of optional 3D printed designs to make assembly easier. These include:\n\n* [a flap scoring jig](3d/tools/scoring_jig.scad) for precisely marking the cut point when splitting CR80 cards\n* [a flap punch jig](3d/tools/punch_jig.scad) for aligning the punch when making the pin cutouts on either side of a flap\n* [a flap container](3d/tools/flap_container.scad) for storing and organizing stacks of completed flaps\n\nAll of these designs are parametric and customizable within OpenSCAD. To print them, open up the relevant file in OpenSCAD and use `File -\u003e Export -\u003e Export as STL` to render the design as an STL file for your slicer.\n\n\n#### Chainlink Driver Tester\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/chainlinkDriverTester-3d.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/chainlinkDriverTester-3d.png\"/\u003e\n\u003c/a\u003e\n\nThis is not likely to be useful unless you're planning to manufacture dozens to hundreds of Chainlink Driver boards, but the Chainlink Driver Tester is a complete testbed\nfor Chainlink Driver boards as they come assembled by the PCBA fabricator.\n\nThis is currently under very active development.\n\nKey features:\n* TTGO T-Display (ESP32) controller, screen, and buttons for controlling tests and reporting results\n* Pogo-pins for all connectors on the Chainlink Driver board-under-test (screw terminals, sensor pin headers, and motor connectors)\n* 12V switch to supply motor power to the board-under-test, with automotive fuse and INA219 voltage/current monitoring (based on the Chainlink Base channel switch design)\n* Separate 3.3V supply for the board-under-test, protected with a polyfuse, should avoid browning out the Tester's MCU in case of 3.3V short-circuits\n* Motor and sensor connections are broken out from the pogo-pins for a full closed-loop hardware test\n* Screw terminals to chain another Chainlink Driver (not under test) to validate that chained outputs work on the board-under-test\n* MCP23017 GPIO expander with 8 GPIO pins exposed via headers for future expansion inputs\n* Large cutout allows a barcode scanner or camera to be aimed at the bottom of the board-under-test for tracking serial numbers.\n* Buzzer option for audible pass/fail feedback\n\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/chainlinkDriverTester-schematic.pdf\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/chainlinkDriverTester-schematic.png\"/\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/chainlinkDriverTester-pcb-raster.png\"\u003e\n\u003cimg width=\"640\" src=\"https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/chainlinkDriverTester-pcb-raster.png\"/\u003e\n\u003c/a\u003e\n\n\nLatest auto-generated (untested!) artifacts\u003csup\u003e:warning:\u003c/sup\u003e:\n\n* Schematic [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/chainlinkDriverTester-schematic.pdf)\n* PCB overview [pdf](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/chainlinkDriverTester-pcb-packet.pdf)\n* PCB gerbers [zip](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/chainlinkDriverTester-jlc/gerbers.zip)\n* PCB bom (for manual assembly) [interactive](https://s3.amazonaws.com/splitflap-artifacts/master/electronics-chainlink-tester/bom/chainlinkDriverTester-ibom.html)\n\n\u003csup\u003e:warning:\u003c/sup\u003eThere are currently no stable releases of this board, and there may never be as it is a niche production tool, not an end product. If you\nneed this tool, you are likely actively involved in development and should understand the revision history and current status of development enough to make\nan informed decision about which revision(s) to use.\n\n\n## Code\n### Firmware\nThe driver firmware is written using PlatformIO with the Arduino framework and is available at [`firmware/`](firmware/). \n\nThe firmware implements a closed-loop controller that accepts letters as input over USB serial and drives the stepper motors using a precomputed acceleration ramp for smooth control. The firmware automatically calibrates the spool position at startup, using the hall-effect magnetic sensor, and will automatically recalibrate itself if it ever detects that the spool position has gotten out of sync. If a commanded rotation is expected to bring the spool past the \"home\" position, it will confirm that the sensor is triggered neither too early nor too late; otherwise it will search for the \"home\" position to get in sync before continuing to the desired letter.\n\n### Serial protocol\nIn order for a computer to communicate with the splitflap, it appears as a USB serial device.\n\nHowever, usage of Arduino’s `Serial` is strictly forbidden, and instead a `logger` abstraction is provided for sending basic text debug logs. Other data is transferred in a structured way, described below.\n\nThis allows flexibility in the format of data transferred over serial, and in fact the splitflap provides 2 different serial modes that serve different purposes.\n\n\n#### Plaintext mode\n\nBy default, it starts in “plaintext” mode, which is developer-friendly and you’re probably familiar with if you’ve opened a serial monitor with the splitflap connected:\n```\n{\"type\":\"init\", \"num_modules\":6}\n```\n\nHowever, this isn’t great for programmatically configuring or receiving updates from the splitflap, so instead the firmware offers a programmatic interface using a binary protocol based on Google’s Protobuf standard.\n\n\n#### Protobuf (binary/programmatic) mode\n\nThe protobuf-based binary serial mode is a compact and flexible way to transfer structured data from the host computer to the splitflap and vice-versa.\n\n\n##### Benefits of protobuf\nprotobuf provides several benefits over other encoding mechanisms like JSON:\n\n1. Well-defined schema. If you’re curious about the format of data to expect or send, you just need to check the protobuf file\n2. Code generation. Instead of hand-writing JSON parsers every time the data changes, protobuf provides code generation of the encoding and decoding logic, and data-structures. Splitflap uses nanopb to generate C structs based off the schema, and all the code for encoding/decoding that data from the binary format.\n3. Relatively compact/efficient wire encoding. It’s not a primary goal in this project, but the binary wire encoding is generally fairly compact, due to omitting default/unspecified fields, using variable length encodings, etc. It’s certainly much more compact than JSON which uses strings to describe every field in every message.\n4. Backwards/forwards compatibility. Not super relevant to this project, but many common schema changes are backwards and forwards compatible, meaning an older client or a newer client will be able to handle them gracefully.\n\n##### Disadvantages of protobuf\n\n1. Not human-readable. This makes it much harder to debug, as you need something that can interpret messages. Since they’re binary, viewing anything in a terminal directly will be fruitless.\n2. Not self-describing. If you come across a JSON document, you can generally tell what it means because fields have string names/labels describing their contents. Protobuf has no such thing (it uses integer field numbers, which does make renaming fields easier) so you need to have a copy of the schema (.proto file - and you’d better hope it matches the data!) in order to understand an encoded message.\n\nThis is why the splitflap defaults to plaintext mode to make basic validation/debugging easier.\n\n##### How it works\nProtobuf messages are encoded to their binary wire format and a CRC32 checksum appended. Then that entire binary string is COBS encoded into a packet, and delimited/framed by 0 (NULL) bytes when sent over serial. This provides a basic packet-based interface with integrity checks (rather than the raw, stream-based interface of a serial connection).\n\nThe splitflap automatically switches to binary protobuf mode when it receives a 0 byte.\n\n\n### Computer Control Software\nThe display can be controlled by a computer connected to the ESP32 over USB serial. If you've built a display and want to test it out, check out the web-based demo [here](https://scottbez1.github.io/splitflap) which will connect to your display using USB - no applications/installation necessary!\n\nThe firmware supports a plaintext serial mode (enabled by default) for ease of testing, and a protobuf-based binary mode used by the software libraries for enhanced programmatic control and feedback.\n\nYou can find example Typescript and Python libraries in the [`software/chainlink`](software/chainlink) folder.\n\n# Contributing/Modifying\n\nLooking to make some modifications or play around with the design on your local machine? Jump right in! Note that all of the scripts and automation are developed for Ubuntu. Mac OS support is planned,\nbut not currently implemented (but feel free to open a PR if you want to help!).\n\n## 3D Design\n\nThe main design file is [`3d/splitflap.scad`](3d/splitflap.scad)\n\nYou'll need a recent version of OpenSCAD (e.g. 2015-03), which may need to be installed through the PPA:\n`sudo add-apt-repository ppa:openscad/releases`\n\nIn general, solid objects such as the enclosure sides or spool components are built from 2d primitives and then extruded to the appropriate thickness for 3d rendering, rather than using 3d primitives. This simplifies the design without losing expressiveness; the perpendicular laser cut beam doesn't allow for cuts that vary in the Z dimension anyway.\n\nNote that while the design is parameterized and many values may be tweaked, there is currently no error checking for invalid parameters or combinations of parameters. Please take care to validate the design if you change any parameters. For instance, while most of the design will adjust to a changed `num_modules` value, certain values may cause some elements to intersect with other elements or protrude beyond their expected dimensions.\n\n### Rendering\n#### Laser-cut vector files\nThe design can be rendered to 2d for laser cutting by running [`3d/scripts/generate_2d.py [--panelize \u003cnumber\u003e]`](3d/scripts/generate_2d.py), which outputs to `3d/build/laser_parts/combined.svg`. The optional `--panelize` argument allows for rendering a panel of modules in a single SVG, for bulk laser-cutting.\n\nInternally, the design uses a `projection_renderer` module ([`3d/projection_renderer.scad`](3d/projection_renderer.scad)), which takes a list of child elements to render, and depending on the `render_index` renders a single child at a time. It also _adds_ material to each shape to account for the kerf that will be cut away by the laser.\n\nThe [`generate_2d.py`](3d/scripts/generate_2d.py) script interacts with the `projection_renderer` module by first using it to determine the number of subcomponents to render, then runs OpenSCAD to export each component to an SVG file. It does some post-processing on the SVG output (notably adds \"mm\" to the document dimensions), and then combines all components into the single `combined.svg` output.\n\nOnce the `combined.svg` file is generated, you'll want to double-check there aren't any redundant cut lines that are shared by multiple adjacent pieces, to save time/cost when cutting. They should be detected automatically (and highlighted in red in the rendering above), but it doesn't hurt to double-check. In Inkscape, select the \"Edit paths by nodes\" tool and select an edge to delete - the endpoints should turn blue. Then click \"Delete segment between two non-endpoint nodes\", and repeat this for all other redundant cut lines.\n\n#### Animated gif\nThe design can be rendered to a rotating 3d animated gif (seen above) by running [`3d/scripts/generate_gif.py`](3d/scripts/generate_gif.py), which outputs to `3d/build/animation/animation.gif`\n\nThe `generate_gif.py` script runs multiple OpenSCAD instances in parallel to render the design from 360 degrees to individual png frames, which are then combined into the final gif animation. As part of building the animation, `generate_gif.py` renders the design with multiple configurations (opaque enclosure, see-through enclosure, no-enclosure and no flaps) by setting the `render_enclosure` and `render_flaps` variables.\n\n#### STL models/web viewer\nThe design can be rendered to a series of STL files (one per color used in the model) in order to be displayed in an [interactive web-based 3d viewer](https://scottbez1.github.io/splitflap/). Similar to the `projection_renderer` used to render individual components for laser-cutting, the [ColoredStlExporter](3d/scripts/colored_stl_exporter.py) detects all the colors used in the model and renders them one-by-one to separate STL files, along with a manifest that maps each STL file to its RGB color. The STL files and manifest are loaded using three.js to display an interactive model on a web site using WebGL. See this blog post for more details on how the export and three.js renderer work: [OpenSCAD Rendering Tricks, Part 3: Web viewer](http://scottbezek.blogspot.com/2016/08/openscad-rendering-tricks-part-3-web.html).\n\n\n## Electronics Design\nAll of the electronics are developed using KiCad 5. Panelization is provided by [KiKit](https://github.com/yaqwsx/KiKit) and gerber/BOM generation is provided by [KiBot](https://github.com/INTI-CMNB/KiBot).\n\n### Rendering\nThe mechanical and electrical design renderings and links above are automatically updated on every commit with the latest rendering. See this blog post for more details on how that works: [Automated KiCad, OpenSCAD rendering using Travis CI](http://scottbezek.blogspot.com/2016/04/automated-kicad-openscad-rendering.html).\n\nThe PCB layout can be rendered to an svg or png (seen above) by running [`electronics/scripts/generate_svg.py file.kicad_pcb`](electronics/scripts/generate_svg.py).\nThis uses KiCad's [Python scripting API](https://docs.kicad-pcb.org/doxygen/md_Documentation_development_pcbnew-plugins.html)\nto render several layers to individual svg files, manipulates them to apply color and opacity settings, and then merges them to a single svg.\nFor additional details, see this blog post: [Scripting KiCad Pcbnew exports](http://scottbezek.blogspot.com/2016/04/scripting-kicad-pcbnew-exports.html).\n\nFor reviewing the design, a pdf packet with copper, silkscreen, and drill info can be produced by running [`electronics/scripts/generate_pdf.py file.kicad_pcb`](electronics/scripts/generate_pdf.py).\n\nGerber files for fabrication can be exported by running [`electronics/scripts/generate_gerber.py file.kicad_pcb`](electronics/scripts/generate_gerber.py).\nThis generates gerber files and an Excellon drill file with Seeed Studio's [naming conventions](http://support.seeedstudio.com/knowledgebase/articles/1176532-how-to-generate-the-gerber-manufacturing-files) and produces a `.zip` which can be sent for fabrication.\n\nEESchema isn't easily scriptable, so to export the schematic [`electronics/scripts/export_schematic.py`](electronics/scripts/export_schematic.py) starts an X Virtual Frame Buffer (Xvfb) and open the `eeschema` GUI within that virtual display, and then send a series of hardcoded key presses via `xdotool` to interact with the GUI and click through the dialogs. This is very fragile but seems to work ok for now. For additional details, see this blog post: [Using UI automation to export KiCad schematics](http://scottbezek.blogspot.com/2016/04/automated-kicad-schematic-export.html).\n\n\n\n# License\nI'd love to hear your thoughts and questions about this project, and happy to incorporate any feedback you might have into these designs! Please feel free (and encouraged) to [open GitHub issues](https://github.com/scottbez1/splitflap/issues/new), email me directly, reach out [on Twitter](https://twitter.com/scottbez1), and [get involved](https://github.com/scottbez1/splitflap/pulls) in the open source development and let's keep chatting and building together!\n\nThis project is licensed under Apache v2 (see [LICENSE.txt](LICENSE.txt)).\n\n    Copyright 2015-2025 Scott Bezek and the splitflap contributors\n    \n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n    \n        http://www.apache.org/licenses/LICENSE-2.0\n    \n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottbez1%2Fsplitflap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscottbez1%2Fsplitflap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottbez1%2Fsplitflap/lists"}