{"id":45863790,"url":"https://github.com/drewmcdonald/flipdot","last_synced_at":"2026-02-27T07:05:00.428Z","repository":{"id":277083007,"uuid":"931279152","full_name":"drewmcdonald/flipdot","owner":"drewmcdonald","description":"Driver and UI for Alfa-Zeta xy5 flip-dot displays","archived":false,"fork":false,"pushed_at":"2025-11-21T22:18:13.000Z","size":492,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-21T23:23:10.546Z","etag":null,"topics":["flipdiscs","flipdot"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/drewmcdonald.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-02-12T02:24:14.000Z","updated_at":"2025-11-21T22:18:16.000Z","dependencies_parsed_at":"2025-02-12T03:38:59.719Z","dependency_job_id":null,"html_url":"https://github.com/drewmcdonald/flipdot","commit_stats":null,"previous_names":["drewmcdonald/flipdot"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/drewmcdonald/flipdot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewmcdonald%2Fflipdot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewmcdonald%2Fflipdot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewmcdonald%2Fflipdot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewmcdonald%2Fflipdot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/drewmcdonald","download_url":"https://codeload.github.com/drewmcdonald/flipdot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/drewmcdonald%2Fflipdot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29887153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-27T05:38:26.446Z","status":"ssl_error","status_checked_at":"2026-02-27T05:38:25.235Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["flipdiscs","flipdot"],"created_at":"2026-02-27T07:04:59.772Z","updated_at":"2026-02-27T07:05:00.423Z","avatar_url":"https://github.com/drewmcdonald.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FlipDot Driver v2.0\n\nA lightweight driver for flipdot displays that fetches pre-rendered content from a remote server.\n\n## Architecture Overview\n\nThe new architecture separates the **driver** (runs on Raspberry Pi) from the **content server** (runs anywhere). This separation allows:\n\n- Faster startup times on the Pi (no NumPy, minimal dependencies)\n- Heavy lifting (rendering, fonts, animations) happens on a powerful server\n- Easier development and testing\n- Better scalability\n\n```\n┌─────────────────────────────────┐\n│  CONTENT SERVER (anywhere)      │\n│  - Render frames                │\n│  - Generate animations          │\n│  - Return structured JSON       │\n└────────────┬────────────────────┘\n             │ HTTP/JSON\n             ▼\n┌─────────────────────────────────┐\n│  DRIVER (Raspberry Pi)          │\n│  - Poll for content             │\n│  - Accept push notifications    │\n│  - Manage frame queue           │\n│  - Send to hardware             │\n└────────────┬────────────────────┘\n             │ Serial\n             ▼\n┌─────────────────────────────────┐\n│  FLIPDOT HARDWARE               │\n└─────────────────────────────────┘\n```\n\n## Quick Start\n\n### 1. Install Dependencies\n\nThe driver has minimal dependencies:\n\n```bash\npip install pydantic pyserial\n```\n\n### 2. Create Configuration\n\nCopy the example configuration:\n\n```bash\ncp config.example.json config.json\n```\n\nEdit `config.json` with your settings:\n\n```json\n{\n  \"poll_endpoint\": \"https://your-server.com/api/flipdot/content\",\n  \"auth\": {\n    \"type\": \"api_key\",\n    \"key\": \"your-secret-key\"\n  },\n  \"serial_device\": \"/dev/ttyUSB0\",\n  \"module_layout\": [[1], [2]]\n}\n```\n\n### 3. Run the Driver\n\n```bash\npython -m flipdot.driver.main --config config.json\n```\n\nFor development (no hardware):\n\n```bash\npython -m flipdot.driver.main --config config.dev.json\n```\n\n## Data Structures\n\n### Frame\n\nA single image to display:\n\n```json\n{\n  \"data_b64\": \"AQIDBAUGBwgJ...\",\n  \"width\": 56,\n  \"height\": 14,\n  \"duration_ms\": 1000\n}\n```\n\n- `data_b64`: Base64-encoded packed bits (little-endian)\n- `width`, `height`: Dimensions in pixels\n- `duration_ms`: How long to display (null = indefinite)\n\n### Content\n\nA sequence of frames with playback instructions:\n\n```json\n{\n  \"content_id\": \"clock-12:00\",\n  \"frames\": [\n    /* array of Frame objects */\n  ],\n  \"playback\": {\n    \"loop\": true,\n    \"loop_count\": null,\n    \"priority\": 0,\n    \"interruptible\": true\n  }\n}\n```\n\n- `content_id`: Unique identifier\n- `frames`: Array of Frame objects\n- `playback.loop`: Whether to loop frames\n- `playback.loop_count`: How many times to loop (null = infinite)\n- `playback.priority`: Priority level (0=normal, 10=notification, 99=urgent)\n- `playback.interruptible`: Can be interrupted by higher priority?\n\n### ContentResponse\n\nWhat the server returns:\n\n```json\n{\n  \"status\": \"updated\",\n  \"content\": {\n    /* Content object */\n  },\n  \"poll_interval_ms\": 30000\n}\n```\n\n- `status`: \"updated\", \"no_change\", or \"clear\"\n- `content`: Content object (only if status=\"updated\")\n- `poll_interval_ms`: How long to wait before next poll\n\n## Server API\n\nThe driver expects a server endpoint that returns `ContentResponse` JSON.\n\n### Polling Endpoint\n\n**GET** `/api/flipdot/content`\n\nReturns the current content to display.\n\n**Headers:**\n\n- `X-API-Key: your-secret-key` (or `Authorization: Bearer token`)\n\n**Response:**\n\n```json\n{\n  \"status\": \"updated\",\n  \"content\": {\n    \"content_id\": \"clock-12:00\",\n    \"frames\": [...],\n    \"playback\": {...}\n  },\n  \"poll_interval_ms\": 30000\n}\n```\n\n### Push Notifications (Optional)\n\nIf `enable_push: true` in config, the driver runs a simple HTTP server:\n\n**POST** `http://pi-address:8080/`\n\nPush high-priority content immediately.\n\n**Headers:**\n\n- `X-API-Key: your-secret-key`\n- `Content-Type: application/json`\n\n**Body:**\n\n```json\n{\n  \"content_id\": \"notification\",\n  \"frames\": [...],\n  \"playback\": {\n    \"priority\": 10,\n    \"interruptible\": false\n  }\n}\n```\n\n## Configuration Reference\n\n```json\n{\n  // Server settings\n  \"poll_endpoint\": \"https://example.com/api/content\",\n  \"poll_interval_ms\": 30000,\n\n  // Push server (optional)\n  \"enable_push\": false,\n  \"push_port\": 8080,\n  \"push_host\": \"0.0.0.0\",\n\n  // Authentication\n  \"auth\": {\n    \"type\": \"api_key\", // or \"bearer\"\n    \"key\": \"secret-key\",\n    \"header_name\": \"X-API-Key\"\n  },\n\n  // Hardware\n  \"serial_device\": \"/dev/ttyUSB0\",\n  \"serial_baudrate\": 57600,\n  \"module_layout\": [[1], [2]],\n  \"module_width\": 28,\n  \"module_height\": 7,\n\n  // Behavior\n  \"error_fallback\": \"keep_last\", // \"keep_last\", \"blank\", or \"error_message\"\n  \"dev_mode\": false,\n  \"log_level\": \"INFO\"\n}\n```\n\n## Content Queue \u0026 Priorities\n\nThe driver maintains a priority queue:\n\n- **Priority 0-9**: Normal content (clock, weather, etc.)\n- **Priority 10-98**: Notifications\n- **Priority 99**: Urgent alerts\n\nHigher priority content **interrupts** lower priority if marked as `interruptible`.\n\nExample flow:\n\n1. Clock is displaying (priority 0)\n2. Notification arrives (priority 10)\n3. Clock pauses, notification plays\n4. Notification completes\n5. Clock resumes from where it left off\n\n## Generating Content\n\nSee `examples/generate_content.py` for examples of creating frames:\n\n```python\nfrom flipdot.hardware import pack_bits_little_endian\nimport base64\n\n# Create a 2x2 frame\nbits = [1, 0, 1, 0]  # Row-major order\npacked = pack_bits_little_endian(bits)\nb64 = base64.b64encode(packed).decode()\n\nframe = {\n    \"data_b64\": b64,\n    \"width\": 2,\n    \"height\": 2,\n    \"duration_ms\": 1000\n}\n```\n\n## Testing\n\nRun tests:\n\n```bash\npytest tests/test_driver.py\n```\n\nGenerate example content:\n\n```bash\ncd examples\npython generate_content.py\n```\n\n## Development Mode\n\nUse `dev_mode: true` to test without hardware:\n\n```bash\npython -m flipdot.driver.main --config config.dev.json\n```\n\nThe driver will print serial data to the console instead of sending to hardware.\n\n## Migration from v1.0\n\n**Key changes:**\n\n1. **Driver is now minimal**: Only handles display logic, no rendering\n2. **NumPy removed**: Faster startup on Pi\n3. **Server provides frames**: All rendering happens server-side\n4. **New data format**: Base64-encoded packed bits instead of live rendering\n5. **Priority queue**: Better support for notifications\n\n**What was removed from the Pi:**\n\n- FastAPI web server\n- React frontend\n- Display modes (Clock, ScrollText, Weather, etc.)\n- NumPy dependency\n\n**What moved to the content server:**\n\n- All rendering logic\n- Font handling\n- Animation generation\n- Display mode implementations\n\n## Troubleshooting\n\n### Driver can't connect to server\n\nCheck:\n\n- `poll_endpoint` is correct\n- Authentication credentials match\n- Server is running and accessible\n\n### Serial device not found\n\nCheck:\n\n- Device path is correct (`/dev/ttyUSB0`, `/dev/ttyACM0`, etc.)\n- User has permission to access serial port\n- Run: `sudo usermod -a -G dialout $USER`\n\n### Frames not displaying\n\nCheck:\n\n- Frame dimensions match display dimensions\n- `data_b64` is valid base64\n- Driver logs for errors (`log_level: \"DEBUG\"`)\n\n## Next Steps\n\nThis is Phase 1 and 2 of the refactor. Still TODO:\n\n- **Phase 3**: Build the content server\n  - Migrate existing mode logic\n  - Create API endpoints\n  - Handle rendering server-side\n- **Phase 4**: Advanced features\n  - Content caching\n  - Compression\n  - Transition effects\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewmcdonald%2Fflipdot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdrewmcdonald%2Fflipdot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdrewmcdonald%2Fflipdot/lists"}