{"id":23024020,"url":"https://github.com/adriankeenan/rpi-epaper-api","last_synced_at":"2026-05-09T01:02:12.378Z","repository":{"id":266892505,"uuid":"837739023","full_name":"adriankeenan/rpi-epaper-api","owner":"adriankeenan","description":"REST API for displaying images on Waveshare epaper displays","archived":false,"fork":false,"pushed_at":"2025-01-10T23:33:00.000Z","size":17,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-08T10:18:44.913Z","etag":null,"topics":["eink","flask","python","raspberry-pi"],"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/adriankeenan.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}},"created_at":"2024-08-03T21:59:29.000Z","updated_at":"2025-01-10T23:33:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"feb66c90-3cba-4772-ad18-4eacf8df08e1","html_url":"https://github.com/adriankeenan/rpi-epaper-api","commit_stats":null,"previous_names":["adriankeenan/rpi-epaper-api"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adriankeenan%2Frpi-epaper-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adriankeenan%2Frpi-epaper-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adriankeenan%2Frpi-epaper-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adriankeenan%2Frpi-epaper-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adriankeenan","download_url":"https://codeload.github.com/adriankeenan/rpi-epaper-api/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246879678,"owners_count":20848736,"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":["eink","flask","python","raspberry-pi"],"created_at":"2024-12-15T13:16:12.129Z","updated_at":"2026-05-09T01:02:07.325Z","avatar_url":"https://github.com/adriankeenan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# rpi-epaper-api\n\nA rest API for setting the display image on a [Waveshare 4.26\"](https://www.waveshare.com/4.26inch-e-paper-hat.htm) \neink HAT connected to a Raspberry Pi. Supports scaling and rotating the input image. Endpoints are also provided for\nfetching display contents and clearing the display.\n\nThis project utilises the [Waveshare e-paper SDKs](https://github.com/waveshareteam/e-Paper) for handling the device commands. This SDK does not seem to have\nany official documentation, the API usage was obtained from these pages:\n- [Waveshare display manual](https://www.waveshare.com/wiki/4.26inch_e-Paper_HAT_Manual)\n- [epd test script](https://github.com/waveshareteam/e-Paper/blob/master/RaspberryPi_JetsonNano/python/examples/epd_4in26_test.py)\n- [epd library code](https://github.com/waveshareteam/e-Paper/blob/master/RaspberryPi_JetsonNano/python/lib/waveshare_epd/epd4in26.py)\n\nFor convenience, this tool is packaged as a docker container. It can also be run on bare metal, but you will need to\nadd the Waveshare SDK to your path (see [Dockerfile](./Dockerfile)).\n\n⚠️ The API is served via the Flask development webserver - you should not expose it publicly.\n\n⚠️ A shared instance of the `epd` object is used across requests, therefore it is not possible to run this application\non a webserver with more than a single worker, should you choose to use a webserver other than the Flask development\nwebserver.\n\n## Setup\n\n### Install on a Raspberry Pi + Display\n\nBuild and run the container:\n\n```commandline\ngit clone https://github.com/adriankeenan/rpi-epaper-api.git\ndocker build -t rpi-eink-api .\ndocker run -p 5000:5000 --restart=always --privileged rpi-eink-api\n```\n\nNow you're ready to send images to the display!\n\n`--restart=always` will ensure that the container is restarted on crash and on system boot. \n\n### Running locally\n\nYou can run also run the API locally using the `EPD_MOCK=true` env var to mock all calls to the display itself.\nYou can still check that the correct image is produced by looking at `src/img.png`.\n\n```commandline\nEPD_MOCK=true python3 src/server.py\n```\n\n## API\n\n### Setting the image\n\n`POST http://rpi:5000`\n\nSet image from file\n```commandline\ncurl --form upload=@image.jpg --form resize=FIT --form background=WHITE http://rpi:5000\n```\n\nSet image from pipe\n```commandline\ncat image.jpg | curl --form image=@- --form resize=FIT --form background=WHITE http://rpi:5000\n```\n\nData should be sent form-encoded.\n\n| Field        | Description                                                                                                                                                                                                                                                                                                                                | Default | Required |\n|--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|----------|\n| `image`      | Image file to display. Any image type supported by the Python PIL library should work.                                                                                                                                                                                                                                                     | N/A     | Yes      |\n| `mode`       | Display mode, corresponding to the `display_XXX` method on the `epd` object.\u003cbr\u003e`FAST` - uses `display_Fast` for a complete screen refresh.\u003cbr\u003e`4GRAY` - uses `display_4Gray` in order to display an image in black, white and 2 shades of grey.\u003cbr\u003e`PARTIAL` - uses `display_Partial` for incremental updates (which may cause ghosting). | `FAST`  | No       |\n| `dither`     | Whether to enable dithering when converting image to mono or 4 gray palette. `true` or `1` to enable.                                                                                                                                                                                                                                      | `true`  | No       |\n| `resize`     | `FIT` Resize keeping aspect ratio, without cropping.\u003cbr\u003e`CROP` Resize keeping aspect ratio, with cropping.\u003cbr\u003e`STRETCH` fill display, ignoring aspect ratio.\u003cbr\u003e`NONE` Display without any scaling, pixels drawn 1:1.                                                                                                                      | `FIT`   | No       |\n| `rotate`     | Number of degrees to rotate counter-clockwise, supports increments of 90 degrees.                                                                                                                                                                                                                                                          | `0`     | No       |\n| `background` | Background colour to use if the image doesn't fill the display. Either `WHITE` or `BLACK`.                                                                                                                                                                                                                                                 | `WHITE` | No       |\n\nExpect this call to take ~5 seconds.\n\nDisplay update will be skipped if the resulting image is the same as the last request (see `updated` field in the response).\n\n### Fetching the current image\n\n`GET http://rpi:5000`\n\n```commandline\ncurl http://rpi:5000 -o img.png\n```\n\nReturns the last image (as PNG) that was successfully sent to the display. This is the exact framebuffer sent to the device (eg post-scaling).\nThis is useful for checking the scaling and rotation settings are correct.\n\nThis image is not persisted between restarts of the container.\n\n### Clearing the current image\n\n`DELETE http://rpi:5000`\n\n```commandline\ncurl -X DELETE http://rpi:5000\n```\n\nExpect this call to take ~7 seconds.\n\nReverts all pixels to the off (white) state. \n\n## Notes\n\n- Although this is project is intended only for the 4.26\" e-paper display, it's likely that other displays can be supported\n  by changing the imported EDP object.\n\n# License\n\n[MIT](./LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadriankeenan%2Frpi-epaper-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadriankeenan%2Frpi-epaper-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadriankeenan%2Frpi-epaper-api/lists"}