### Run pixoo-rest directly with uv Source: https://github.com/4ch1m/pixoo-rest/blob/master/README.md Starts the FastAPI app with default host 0.0.0.0 and port 8000. Requires uv to be installed. ```bash uv run fastapi run pixoo_rest ``` -------------------------------- ### Usage example for Settings.get() Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/settings.md Shows how to use Settings.get() to access the cached singleton. Environment variables (or .env file) are read automatically, e.g., PIXOO_HOST and PIXOO_SCREEN_SIZE. The example prints a connection message if pixoo_debug is False. ```python from pixoo_rest.settings import Settings # Environment variables (or .env file) are read automatically: # PIXOO_HOST=192.168.178.11 # PIXOO_SCREEN_SIZE=64 settings = Settings.get() # cached singleton; subsequent calls return the same object if not settings.pixoo_debug: print(f'connecting to {settings.pixoo_host}') # -> 'connecting to 192.168.178.11' ``` -------------------------------- ### POST /passthrough/channel/getAllConf Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Gets all configuration from the device. ```APIDOC ## POST /passthrough/channel/getAllConf ### Description Gets all configuration from the device. ### Method POST ### Endpoint /passthrough/channel/getAllConf ### Parameters #### Request Body - **Command** (string) - Required - The command string, e.g., "Channel/GetAllConf". ### Request Example { "Command": "Channel/GetAllConf" } ``` -------------------------------- ### PassthroughModel usage example Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-misc.md Shows how to instantiate PassthroughModel, mirroring how the router builds its list. ```python from pixoo_rest.models.passthrough import PassthroughModel entry = PassthroughModel( route_path='/passthrough/channel/getIndex', payload_filename='channel_get_index.json', description='Get current channel.', ) ``` -------------------------------- ### curl examples for set endpoints Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Example curl commands to set brightness, channel, and screen on/off. All set endpoints return ResponseModel(message='OK') and forward to the equivalent pixoo-library setter. Status codes: 200, 422 on constraint violation, 500 on device call failure. ```bash curl -X PUT http://localhost:8000/brightness/75 curl -X PUT http://localhost:8000/channel/2 curl -X PUT http://localhost:8000/screen/on/true ``` -------------------------------- ### ResponseModel success example Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-misc.md Example JSON response returned by success routes. ```json { "message": "OK" } ``` -------------------------------- ### ResponseModel failure example Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-misc.md Example JSON response returned by download routes on failure. ```json { "message": "Error downloading the image: 404 Client Error: Not Found for url: ..." } ``` -------------------------------- ### Create .env configuration file Source: https://github.com/4ch1m/pixoo-rest/blob/master/README.md Example .env file with all available configuration options. PIXOO_HOST is mandatory; all others are optional with documented defaults. ```properties # MANDATORY: the hostname of your Pixoo device; defaults to "Pixoo64" if omitted PIXOO_HOST=192.168.178.11 # OPTIONAL: the screen size of your Pixoo device (which gets passed to the Pixoo-library); defaults to "64" if omitted PIXOO_SCREEN_SIZE=64 # OPTIONAL: enable debug mode for the Pixoo-library; defaults to "false" if omitted PIXOO_DEBUG=true # OPTIONAL: controls, whether a connection check to the Pixoo device should be performed upon application start PIXOO_CONNECTION_CHECK=true # OPTIONAL: the amount of retries that should be performed to connect to the Pixoo-device when starting the app; defaults to "infinity" when omitted PIXOO_CONNECTION_CHECK_RETRIES=10 # OPTIONAL: enable (FastAPI) debug mode for the REST-app; defaults to "false" if omitted PIXOO_REST_DEBUG=true # OPTIONAL: configures the base-path/prefix-url (which may be needed when running behind a reverse proxy); defaults to an empty string if omitted #PIXOO_REST_ROOT_PATH=/my-pixoo # OPTIONAL: the official Divoom API URL (used for querying Divoom devices in your LAN, etc.); can be overridden if necessary DIVOOM_API_URL=https://app.divoom-gz.com ``` -------------------------------- ### GET /redoc Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Serves the ReDoc UI HTML page for API documentation. Uses self-hosted `static/redoc.standalone.js`. ```APIDOC ## GET /redoc ### Description Serves the ReDoc UI HTML page for API documentation. Uses self-hosted `static/redoc.standalone.js`. ### Method GET ### Endpoint `/redoc` ### Response #### Success Response (200) - **Content-Type** (string) - `text/html` #### Response Example HTML content of the ReDoc page. ``` -------------------------------- ### APITags usage example Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-misc.md Shows how to access APITags member values. ```python from pixoo_rest.api_tags import APITags assert APITags.DRAW.value == 'draw' assert APITags.SET.value == 'set' ``` -------------------------------- ### GET /docs Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Serves the Swagger UI HTML page for interactive API documentation. Uses self-hosted assets from the static directory. ```APIDOC ## GET /docs ### Description Serves the Swagger UI HTML page for interactive API documentation. Uses self-hosted assets from the `static/` directory. ### Method GET ### Endpoint `/docs` ### Response #### Success Response (200) - **Content-Type** (string) - `text/html` #### Response Example HTML content of the Swagger UI page. ``` -------------------------------- ### curl example for draw line endpoint Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Example curl command to draw a line on the device buffer. The endpoint is POST /line and uses form fields. The handler draws on the buffer and calls pixoo.push() only when push_immediately is true. Status codes: 200, 422 on validation, 500 on decode/draw failure. ```bash curl -s -X POST \ -d "start_x=32&start_y=32&stop_x=0&stop_y=-1&r=0&g=255&b=0&push_immediately=true" \ "http://localhost:8000/line" ``` -------------------------------- ### home: redirect to /docs Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Route handler for GET / that returns a RedirectResponse to /docs (Swagger UI), built from request.base_url. Registered with include_in_schema=False. ```python @app.get('/', include_in_schema=False) async def home(request: Request) -> RedirectResponse: return RedirectResponse(f'{request.base_url}docs') ``` -------------------------------- ### Basic sendGif curl command Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-send.md Example curl command to call POST /sendGif with query parameters for the model and a multipart file upload. ```bash curl -s -X 'POST' \ -F "gif_file=@./duck.gif;type=image/gif" \ "http://localhost:8000/sendGif?skip_first_frame=false&animation_speed=100" ``` -------------------------------- ### GET /favicon.ico Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Serves the favicon file. The handler references `favico.icon` (as written in source) while the repository file is `static/favicon.ico`. ```APIDOC ## GET /favicon.ico ### Description Serves the favicon file. The handler references `favico.icon` (as written in source) while the repository file is `static/favicon.ico`. ### Method GET ### Endpoint `/favicon.ico` ### Response #### Success Response (200) - **Content-Type** (string) - The MIME type of the favicon file. #### Response Example Binary content of the favicon file. ``` -------------------------------- ### POST /line Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Draws a line on the device buffer. Accepts start and stop coordinates, color, and push settings as form fields. Pushes to the device only if push_immediately is true. ```APIDOC ## POST /line ### Description Draws a line from a start point to a stop point. The coordinates, color, and push settings are provided as form fields. ### Method POST ### Endpoint /line ### Parameters #### Request Body (application/x-www-form-urlencoded) - **start_x** (int) - Optional - Start X coordinate, default 0, must be >= 0. - **start_y** (int) - Optional - Start Y coordinate, default 0, must be >= 0. - **stop_x** (int) - Optional - Stop X coordinate, default 0, must be >= 0. - **stop_y** (int) - Optional - Stop Y coordinate, default 0, must be >= 0. - **r** (int) - Optional - Red color component, default 255, range 0-255. - **g** (int) - Optional - Green color component, default 255, range 0-255. - **b** (int) - Optional - Blue color component, default 255, range 0-255. - **push_immediately** (bool) - Optional - Whether to push to device immediately, default true. ### Request Example ```bash curl -s -X POST -d "start_x=32&start_y=32&stop_x=0&stop_y=-1&r=0&g=255&b=0&push_immediately=true" "http://localhost:8000/line" ``` ### Response #### Success Response (200) - **message** (str) - "OK" #### Response Example { "message": "OK" } ### Error Handling - 422: Validation error - 500: Decode or draw failure ``` -------------------------------- ### Embedding routers in FastAPI app Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Python example showing how to include the set_router, draw_router, and passthrough_router in a custom FastAPI application. Only relevant when extending the app. ```python from pixoo_rest.routers import set_router, draw_router, passthrough_router app.include_router(set_router) app.include_router(draw_router) app.include_router(passthrough_router) ``` -------------------------------- ### create_endpoint factory function Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Factory function that returns an async endpoint closure. At registration time it loads the example payload JSON from the resources directory. The endpoint accepts a JSON body with an OpenAPI example and description, forwards it via `requests.post` to `http://{pixoo.ip_address}/post`, and returns the device response JSON. ```python def create_endpoint(passthrough_model: PassthroughModel) -> Callable[..., CoroutineType[Any, Any, Any]]: with open(Path(__file__).parent.parent / 'resources' / 'passthrough_payloads' / Path(passthrough_model.payload_filename), encoding='utf-8') as payload_file: payload = json.load(payload_file) async def endpoint(body: Annotated[dict, Body(examples=[payload], description=passthrough_model.description)]): return requests.post(url=f'http://{pixoo.ip_address}/post', json=body).json() return endpoint ``` -------------------------------- ### POST /passthrough/device/getWeatherInfo Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Gets weather information from the device. ```APIDOC ## POST /passthrough/device/getWeatherInfo ### Description Gets weather information from the device. ### Method POST ### Endpoint /passthrough/device/getWeatherInfo ### Parameters #### Request Body - **Command** (string) - Required - The command string, e.g., "Device/GetWeatherInfo". ### Request Example { "Command": "Device/GetWeatherInfo" } ``` -------------------------------- ### GET / Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Redirects to the Swagger UI documentation page. This endpoint is not included in the OpenAPI schema. ```APIDOC ## GET / ### Description Redirects to the Swagger UI documentation page at `{request.base_url}docs`. ### Method GET ### Endpoint `/` ### Response #### Success Response (302) - **Location** (string) - The URL to the Swagger UI documentation page. #### Response Example HTTP/1.1 302 Found Location: /docs ``` -------------------------------- ### Compose common mixins into a concrete model Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-common.md Shows how to inherit from XYModel, RGBModel, and TextWidthModel to build a concrete model. The example is conceptual and mirrors the source's inheritance style. These mixins carry pydantic Field metadata so FastAPI can generate validation and OpenAPI schemas for form-parameter bindings. ```python from pydantic import BaseModel, Field from pixoo_rest.models.common import XYModel, RGBModel, TextWidthModel class MyTextModel(XYModel, RGBModel, TextWidthModel): value: str = Field(default='hi') ``` -------------------------------- ### handle_gif: upload animated GIF or draw static image Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/helpers.md If the image is an animated GIF, resets the HTTP GIF ID, collects up to 59 frames (starting at index 1 if skip_first_frame is True), resizes non-16/32/64 frames to the device size, and posts each frame as a Draw/SendHttpGif command with base64-encoded RGB data. Otherwise, draws the image and pushes it. No error handling around requests.post calls; device connection failures raise uncaught requests exceptions. ```python def handle_gif(gif: ImageFile, speed: int, skip_first_frame: bool) -> None: pixoo = get_pixoo() if isinstance(gif, GifImageFile) and gif.is_animated: requests.post(f'http://{pixoo.ip_address}/post', json.dumps({ 'Command': 'Draw/ResetHttpGifId' })) gif_frames = [] for i in range((1 if skip_first_frame else 0), gif.n_frames): if len(gif_frames) == 59: break gif.seek(i) if gif.size not in ((16, 16), (32, 32), (64, 64)): gif_frames.append(gif.resize((pixoo.size, pixoo.size)).convert('RGB')) else: gif_frames.append(gif.convert('RGB')) for offset, gif_frame in enumerate(gif_frames): requests.post(f'http://{pixoo.ip_address}/post', json.dumps({ 'Command': 'Draw/SendHttpGif', 'PicID': 1, 'PicNum': len(gif_frames), 'PicOffset': offset, 'PicWidth': gif_frame.width, 'PicSpeed': speed, 'PicData': base64.b64encode(gif_frame.tobytes()).decode('utf-8') })) else: pixoo.draw_image(gif) pixoo.push() ``` -------------------------------- ### Get cached Settings instance Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Retrieves the cached Settings instance using the Settings.get() method. ```python settings = Settings.get() ``` -------------------------------- ### redoc_html: self-hosted ReDoc Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Route handler for GET /redoc that returns ReDoc HTML using the self-hosted static/redoc.standalone.js, honoring settings.pixoo_rest_root_path in asset URLs. ```python @app.get('/redoc', include_in_schema=False) async def redoc_html() -> HTMLResponse: return get_redoc_html( openapi_url=f'{settings.pixoo_rest_root_path}{app.openapi_url}', title=f'{app.title} - ReDoc', redoc_favicon_url=f'{settings.pixoo_rest_root_path}/static/favicon.ico', redoc_js_url=f'{settings.pixoo_rest_root_path}/static/redoc.standalone.js' ) ``` -------------------------------- ### GET /static/{sub_path} Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Serves static files from the `static/` directory. The `sub_path` path parameter specifies the file path relative to the static directory. ```APIDOC ## GET /static/{sub_path} ### Description Serves static files from the `static/` directory. The `sub_path` path parameter specifies the file path relative to the static directory. ### Method GET ### Endpoint `/static/{sub_path}` ### Parameters #### Path Parameters - **sub_path** (string) - Required - The path to the static file relative to the `static/` directory. ### Response #### Success Response (200) - **Content-Type** (string) - The MIME type of the requested file. #### Response Example Binary content of the requested static file. ``` -------------------------------- ### custom_swagger_ui_html: self-hosted Swagger UI Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Route handler for GET /docs that returns Swagger UI HTML using self-hosted assets under /static/. All asset URLs honor settings.pixoo_rest_root_path. ```python @app.get('/docs', include_in_schema=False) async def custom_swagger_ui_html() -> HTMLResponse: return get_swagger_ui_html( openapi_url=f'{settings.pixoo_rest_root_path}{app.openapi_url}', title=f'{app.title} - Swagger UI', oauth2_redirect_url=app.swagger_ui_oauth2_redirect_url, swagger_favicon_url=f'{settings.pixoo_rest_root_path}/static/favicon.ico', swagger_js_url=f'{settings.pixoo_rest_root_path}/static/swagger-ui-bundle.js', swagger_css_url=f'{settings.pixoo_rest_root_path}/static/swagger-ui.css' ) ``` -------------------------------- ### POST /divoom/device/lan Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Get a list of all (Pixoo-)devices in your local network. This endpoint returns the vendor API response JSON verbatim. ```APIDOC ## POST /divoom/device/lan ### Description Get a list of all (Pixoo-)devices in your local network. ### Method POST ### Endpoint /divoom/device/lan ### Parameters None ### Response #### Success Response (200) Returns the vendor API response JSON verbatim. #### Response Example (No example provided in source) ``` -------------------------------- ### POST /line - LineModel Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-draw.md Request model for drawing a line from a start point to a stop point with RGB color. Accepted by POST /line endpoint. ```APIDOC ## POST /line ### Description Draws a line from the start pixel to the stop pixel with the specified RGB color. The stop coordinates can be -1 to allow lines exiting the screen edge. ### Method POST ### Endpoint /line ### Parameters #### Request Body (form-encoded or JSON) - **r** (int) - Optional - Red color component (0-255, default 255) - **g** (int) - Optional - Green color component (0-255, default 255) - **b** (int) - Optional - Blue color component (0-255, default 255) - **push_immediately** (bool) - Optional - Whether to push the image immediately (default true) - **start_x** (int) - Optional - Horizontal pixel position to start with (>= 0, default 0) - **start_y** (int) - Optional - Vertical pixel position to start with (>= 0, default 0) - **stop_x** (int) - Optional - Horizontal pixel position to end with (>= -1, default 0) - **stop_y** (int) - Optional - Vertical pixel position to end with (>= -1, default 0) ### Request Example ```bash curl -X POST http://localhost:8000/line \ -d "start_x=32&start_y=32&stop_x=64&stop_y=64&r=0&g=255&b=0&push_immediately=true" ``` ### Response #### Success Response (200) - No specific response body documented. #### Error Response (422) - Validation error if constraints are violated (e.g., stop_x < -1). ``` -------------------------------- ### static_file: serve static files Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Route handler for GET /static/{sub_path} that returns a FileResponse for the resolved file under the repo static/ directory. Takes a sub_path path segment. ```python @app.get('/static/{sub_path}', include_in_schema=False) async def static_file(sub_path: str) -> FileResponse: return FileResponse(STATIC_RESOURCE_PATH / Path(sub_path)) ``` -------------------------------- ### Basic sendText curl command Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-send.md Example curl command to call POST /sendText with form-encoded fields for the text model. ```bash curl -X POST http://localhost:8000/sendText \ -d "text=Hello Pixoo!&x=0&y=0&r=255&g=0&b=0&text_width=64&scroll_speed=100&scroll_direction=0&identifier=0&font=1" ``` -------------------------------- ### DialListModel usage example Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-misc.md Curl command to call the Divoom channel dial list endpoint with dial_type and page_number form data. ```bash curl -X POST http://localhost:8000/divoom/channel/dial/list \ -d "dial_type=Game&page_number=1" ``` -------------------------------- ### curl POST to /passthrough/channel/getIndex Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Example of using the HTTP route directly with curl. Sends a POST request to the passthrough endpoint with a JSON payload containing the command 'Channel/GetIndex'. ```bash curl -X POST http://localhost:8000/passthrough/channel/getIndex \ -H "Content-Type: application/json" -d '{"Command": "Channel/GetIndex"}' ``` -------------------------------- ### favicon: serve favicon.ico Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Route handler for GET /favicon.ico that returns a FileResponse for STATIC_RESOURCE_PATH / Path('favico.icon'). Note: the referenced 'favico.icon' path does not exist in the repository tree, so this route may 404. ```python @app.get('/favicon.ico', include_in_schema=False) async def favicon() -> FileResponse: return FileResponse(STATIC_RESOURCE_PATH / Path('favico.icon')) ``` -------------------------------- ### Python error handling for download/gif Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-download.md Shows a failed download/gif request returning HTTP 424 FAILED_DEPENDENCY with a ResponseModel body. The example prints the status code and the error message from the JSON response. ```python import requests r = requests.post('http://localhost:8000/download/gif', data={'url': 'http://localhost:1/nope.gif'}) print(r.status_code) # 424 print(r.json()['message']) # 'Error downloading the GIF: ...' ``` -------------------------------- ### GifModel class definition Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-download.md Defines the GifModel for the download router, inheriting from TimeoutModel, SSLVerifyModel, AnimationSpeedModel, SkipFirstFrameModel, and UserAgentModel. The url field defaults to an example duck.gif URL and is automatically resized when displayed. ```python class GifModel(TimeoutModel, SSLVerifyModel, AnimationSpeedModel, SkipFirstFrameModel, UserAgentModel): url: str = Field( default='https://raw.githubusercontent.com/4ch1m/pixoo-rest/master/examples/duck.gif', description='The URL of the animated GIF image to be downloaded and then displayed. (Automatically gets resized.)' ) ``` -------------------------------- ### POST /passthrough/device/getDeviceTime Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Gets the device time. ```APIDOC ## POST /passthrough/device/getDeviceTime ### Description Gets the device time. ### Method POST ### Endpoint /passthrough/device/getDeviceTime ### Parameters #### Request Body - **Command** (string) - Required - The command string, e.g., "Device/GetDeviceTime". ### Request Example { "Command": "Device/GetDeviceTime" } ``` -------------------------------- ### Initialize the pixoo submodule Source: https://github.com/4ch1m/pixoo-rest/blob/master/README.md Updates and initializes the pixoo submodule as required by the project. ```bash git submodule update --init ``` -------------------------------- ### Programmatic ASGI usage for tests or embedding Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Shows how to import the app from the package root for programmatic ASGI usage, e.g., with uvicorn.run(app) or any ASGI server. ```python from pixoo_rest import app # re-exported by the package root # app is a FastAPI/Starlette ASGI application: # uvicorn.run(app) or serve via any ASGI server ``` -------------------------------- ### POST /passthrough/channel/getIndex Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Gets the current channel index from the device. ```APIDOC ## POST /passthrough/channel/getIndex ### Description Gets the current channel index from the device. ### Method POST ### Endpoint /passthrough/channel/getIndex ### Parameters #### Request Body - **Command** (string) - Required - The command string, e.g., "Channel/GetIndex". ### Request Example { "Command": "Channel/GetIndex" } ``` -------------------------------- ### POST /fill Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Fills the device buffer with a color. Accepts color and push settings as form fields. Pushes to the device only if push_immediately is true. ```APIDOC ## POST /fill ### Description Fills the device buffer with a solid color. The color and push settings are provided as form fields. ### Method POST ### Endpoint /fill ### Parameters #### Request Body (application/x-www-form-urlencoded) - **r** (int) - Optional - Red color component, default 255, range 0-255. - **g** (int) - Optional - Green color component, default 255, range 0-255. - **b** (int) - Optional - Blue color component, default 255, range 0-255. - **push_immediately** (bool) - Optional - Whether to push to device immediately, default true. ### Request Example ```bash curl -X POST -d "r=255&g=0&b=0&push_immediately=true" "http://localhost:8000/fill" ``` ### Response #### Success Response (200) - **message** (str) - "OK" #### Response Example { "message": "OK" } ### Error Handling - 422: Validation error - 500: Decode or draw failure ``` -------------------------------- ### Settings.get() static factory method Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/configuration.md Cached static method returning a Settings instance. Logs the settings as JSON. Used throughout the project via Settings.get(). Constructor takes no required parameters; fields bootstrap from environment variables or defaults. ```python @staticmethod @lru_cache def get() -> Settings: settings = Settings() logger.info(settings.model_dump_json(indent=4)) return settings ``` -------------------------------- ### PUT /screen/on/{boolean} Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Turns the screen on or off based on the boolean value. Returns a ResponseModel with message 'OK'. ```APIDOC ## PUT /screen/on/{boolean} ### Description Turns the screen on or off based on the boolean value. Returns a ResponseModel with message 'OK'. ### Method PUT ### Endpoint /screen/on/{boolean} ### Parameters #### Path Parameters - **boolean** (bool) - Required - Screen on. ### Response #### Success Response (200) - **message** (string) - Always 'OK'. #### Response Example { "message": "OK" } ``` -------------------------------- ### lifespan: startup connection check with retries Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Async context manager that runs at application startup. If settings.pixoo_connection_check is true, it probes http://{pixoo_host}/get every 30 seconds using helpers.try_to_request. On final failure, it calls sys.exit with the message 'Failed to connect to [{settings.pixoo_host}]. Exiting.' and the process terminates. Shutdown does nothing. ```python @asynccontextmanager async def lifespan(_: FastAPI) -> AsyncGenerator[None, Any]: if settings.pixoo_connection_check: for connection_test_count in range(settings.pixoo_connection_check_retries + 1): if helpers.try_to_request(f'http://{settings.pixoo_host}/get'): break if connection_test_count == settings.pixoo_connection_check_retries: sys.exit(f'Failed to connect to [{settings.pixoo_host}]. Exiting.') else: time.sleep(30) yield ... # no shutdown tasks atm ``` -------------------------------- ### Create FastAPI app instance Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Configures the FastAPI application with title, version, description, contact, tags, root path, and disables default docs routes. ```python app = FastAPI( title='Pixoo REST', version=project_metadata['project']['version'], description='A RESTful API to easily interact with the Wi-Fi enabled {} devices.'.format( 'Divoom Pixoo' ), terms_of_service='', contact={ 'name': '4ch1m / GitHub', 'url': 'https://github.com/4ch1m/pixoo-rest' }, base_path=settings.pixoo_rest_root_path, url_prefix=settings.pixoo_rest_root_path, tags_metadata=[ { 'name': APITags.DRAW.value, 'description': 'draw lines, pixels, rectangles, etc. on your Pixoo' }, { 'name': APITags.SEND.value, 'description': 'send text, GIFs, etc. to your Pixoo' }, { 'name': APITags.SET.value, 'description': 'set brightness, channel, clock, etc. on your Pixoo' }, { 'name': APITags.PASSTHROUGH.value, 'description': "directly pass commands to your Pixoo's built-in HTTP-API" }, { 'name': APITags.DIVOOM.value, 'description': f'send requests to the external vendor API ({settings.divoom_api_url})' }, { 'name': APITags.DOWNLOAD.value, 'description': 'automatically download and send resources to your Pixoo' } ], root_path=settings.pixoo_rest_root_path, debug=settings.pixoo_rest_debug, lifespan=lifespan, docs_url=None, redoc_url=None ) ``` -------------------------------- ### GET /docs/oauth2-redirect Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Serves the OAuth2 redirect page for Swagger UI. This endpoint is not included in the OpenAPI schema. ```APIDOC ## GET /docs/oauth2-redirect ### Description Serves the OAuth2 redirect page for Swagger UI. The path is configured via `SWAGGER_UI_OAUTH2_REDIRECT_URL`. ### Method GET ### Endpoint `/docs/oauth2-redirect` ### Response #### Success Response (200) - **Content-Type** (string) - `text/html` #### Response Example HTML content of the OAuth2 redirect page. ``` -------------------------------- ### Build and run pixoo-rest container with Docker Compose Source: https://github.com/4ch1m/pixoo-rest/blob/master/README.md Builds the container and runs it. To change the port, add PIXOO_REST_PORT to the .env file. ```bash docker compose up ``` -------------------------------- ### swagger_ui_redirect: OAuth2 redirect page Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Route handler for GET /docs/oauth2-redirect that returns the FastAPI OAuth2 redirect HTML page. ```python @app.get(SWAGGER_UI_OAUTH2_REDIRECT_URL, include_in_schema=False) async def swagger_ui_redirect() -> HTMLResponse: return get_swagger_ui_oauth2_redirect_html() ``` -------------------------------- ### Handle GIF upload with handle_gif Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/helpers.md Opens a GIF file, reads it into a PIL Image object, and calls handle_gif with speed=100 and skip_first_frame=True. The comment notes that it uploads up to 59 frames to the device. ```python import io from PIL import Image from pixoo_rest.helpers import handle_gif with open('duck.gif', 'rb') as f: gif = Image.open(io.BytesIO(f.read())) handle_gif(gif=gif, speed=100, skip_first_frame=True) # uploads <= 59 frames to the device ``` -------------------------------- ### POST /image Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Draws an image on the device buffer. Accepts an image file upload and optional position and push settings. Pushes to the device only if push_immediately is true. ```APIDOC ## POST /image ### Description Draws an image on the device buffer. The image file is required. The image is pushed to the device only if push_immediately is true. ### Method POST ### Endpoint /image ### Parameters #### Query Parameters - **x** (int) - Optional - X coordinate, default 0, must be >= 0. - **y** (int) - Optional - Y coordinate, default 0, must be >= 0. - **push_immediately** (bool) - Optional - Whether to push to device immediately, default true. #### Request Body (multipart/form-data) - **image_file** (UploadFile) - Required - The image file to draw. ### Request Example ```bash curl -X POST -F "image_file=@image.png" "http://localhost:8000/image?x=0&y=0&push_immediately=true" ``` ### Response #### Success Response (200) - **message** (str) - "OK" #### Response Example { "message": "OK" } ### Error Handling - 422: Validation error - 500: Decode or draw failure ``` -------------------------------- ### POST /divoom/channel/dial/types Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Get a list of all "dial" types. This endpoint returns the vendor API response JSON verbatim. ```APIDOC ## POST /divoom/channel/dial/types ### Description Get a list of all "dial" types. ### Method POST ### Endpoint /divoom/channel/dial/types ### Parameters None ### Response #### Success Response (200) Returns the vendor API response JSON verbatim. #### Response Example (No example provided in source) ``` -------------------------------- ### Define passthrough_routes list with PassthroughModel entries Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Defines the `passthrough_routes` list containing `PassthroughModel` instances. Each entry specifies a `route_path`, a `payload_filename` under `pixoo_rest/resources/passthrough_payloads/`, and a description. The list contains 28 entries total; the shown entry is the first one. ```python passthrough_routes = [ PassthroughModel( route_path='/passthrough/channel/setIndex', payload_filename='channel_set_index.json', description='Select channel. (index: 0=Faces, 1=Cloud, 2=Visualizer, 3=Custom)'), # ... 27 more entries, see endpoints.md for the full table ] ``` -------------------------------- ### Run pixoo-rest with custom host and port Source: https://github.com/4ch1m/pixoo-rest/blob/master/README.md Overrides the default host and port (0.0.0.0:8000) using --host and --port flags. ```bash uv run fastapi run --host 127.0.0.1 --port 8080 pixoo_rest ``` -------------------------------- ### POST /text Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Draws text on the device buffer. Accepts text content, position, color, and push settings as form fields. Pushes to the device only if push_immediately is true. ```APIDOC ## POST /text ### Description Draws text on the device buffer. The text content, position, color, and push settings are provided as form fields. ### Method POST ### Endpoint /text ### Parameters #### Request Body (application/x-www-form-urlencoded) - **text** (str) - Optional - Text to draw, default 'Hello Pixoo!'. - **x** (int) - Optional - X coordinate, default 0, must be >= 0. - **y** (int) - Optional - Y coordinate, default 0, must be >= 0. - **r** (int) - Optional - Red color component, default 255, range 0-255. - **g** (int) - Optional - Green color component, default 255, range 0-255. - **b** (int) - Optional - Blue color component, default 255, range 0-255. - **push_immediately** (bool) - Optional - Whether to push to device immediately, default true. ### Request Example ```bash curl -X POST -d "text=Hello&x=0&y=0&r=255&g=255&b=255&push_immediately=true" "http://localhost:8000/text" ``` ### Response #### Success Response (200) - **message** (str) - "OK" #### Response Example { "message": "OK" } ### Error Handling - 422: Validation error - 500: Decode or draw failure ``` -------------------------------- ### GET /health Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Health check endpoint used by Docker HEALTHCHECK and Helm liveness probe. Returns a simple JSON response with a message field. ```APIDOC ## GET /health ### Description Health check endpoint used by Docker HEALTHCHECK and Helm liveness probe. Returns a simple JSON response with a message field. ### Method GET ### Endpoint `/health` ### Response #### Success Response (200) - **message** (string) - Always `"OK"`. #### Response Example { "message": "OK" } ``` -------------------------------- ### Re-export all six routers in pixoo_rest/routers/__init__.py Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Imports each functional router and re-exports them for pixoo_rest.main. This is the standard import block used to aggregate the routers. ```python from .divoom import router as divoom_router from .download import router as download_router from .draw import router as draw_router from .passthrough import router as passthrough_router from .send import router as send_router from .set import router as set_router ``` -------------------------------- ### POST /passthrough/channel/getIndex Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Sends a passthrough command to the Pixoo device to get the current channel index. This endpoint is used by consumer code via HTTP. ```APIDOC ## POST /passthrough/channel/getIndex ### Description Sends a passthrough command to the Pixoo device to get the current channel index. ### Method POST ### Endpoint /passthrough/channel/getIndex ### Parameters #### Request Body - **Command** (string) - Required - The command to send, e.g., "Channel/GetIndex" ### Request Example { "Command": "Channel/GetIndex" } ### Response #### Success Response (200) No response schema documented. #### Response Example No response example documented. ``` -------------------------------- ### PUT /brightness/{percentage} Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Sets the display brightness to the given percentage value (0-100). Returns a ResponseModel with message 'OK'. ```APIDOC ## PUT /brightness/{percentage} ### Description Sets the display brightness to the given percentage value (0-100). Returns a ResponseModel with message 'OK'. ### Method PUT ### Endpoint /brightness/{percentage} ### Parameters #### Path Parameters - **percentage** (int) - Required - Percentage value of display brightness. Must be between 0 and 100. ### Response #### Success Response (200) - **message** (string) - Always 'OK'. #### Response Example { "message": "OK" } ``` -------------------------------- ### Error handling for text length validation Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-send.md Python example showing that a text longer than 511 characters is rejected with HTTP 422 and error type 'string_too_long'. ```python import requests r = requests.post('http://localhost:8000/sendText', data={'text': 'x' * 512}) print(r.status_code) # 422 print(r.json()['detail'][0]['type']) # 'string_too_long' ``` -------------------------------- ### POST /fill - FillModel Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-draw.md Request model for filling the entire screen with a solid RGB color. Accepted by POST /fill endpoint. ```APIDOC ## POST /fill ### Description Fills the entire screen with the specified RGB color. ### Method POST ### Endpoint /fill ### Parameters #### Request Body (form-encoded or JSON) - **r** (int) - Optional - Red color component (0-255, default 255) - **g** (int) - Optional - Green color component (0-255, default 255) - **b** (int) - Optional - Blue color component (0-255, default 255) - **push_immediately** (bool) - Optional - Whether to push the image immediately (default true) ### Request Example ```bash curl -X POST http://localhost:8000/fill \ -d "r=0&g=0&b=255&push_immediately=true" ``` ### Response #### Success Response (200) - No specific response body documented. #### Error Response (422) - Validation error if constraints are violated. ``` -------------------------------- ### POST /divoom/channel/dial/list Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Get a list of all "dial" elements. This endpoint accepts a form-encoded DialListModel and returns the vendor API response JSON verbatim. ```APIDOC ## POST /divoom/channel/dial/list ### Description Get a list of all "dial" elements. ### Method POST ### Endpoint /divoom/channel/dial/list ### Parameters #### Request Body (Form Data) - **dial_list_model** (DialListModel) - Required - Form-encoded model containing dial type and page number. ### Response #### Success Response (200) Returns the vendor API response JSON verbatim. #### Response Example (No example provided in source) ``` -------------------------------- ### Define static resource path Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Defines the path to the static directory that self-hosts Swagger UI and ReDoc assets. ```python STATIC_RESOURCE_PATH = Path(__file__).parent.parent / Path('static') ``` -------------------------------- ### Change directory to pixoo-rest Source: https://github.com/4ch1m/pixoo-rest/blob/master/README.md Changes the current directory to the cloned pixoo-rest project. ```bash cd pixoo-rest ``` -------------------------------- ### POST /passthrough/device/setHighLightMode Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Sets the highlight mode. The Mode parameter is 0=close, 1=open. ```APIDOC ## POST /passthrough/device/setHighLightMode ### Description Sets the highlight mode. The Mode parameter is 0=close, 1=open. ### Method POST ### Endpoint /passthrough/device/setHighLightMode ### Parameters #### Request Body - **Command** (string) - Required - The command string, e.g., "Device/SetHighLightMode". - **Mode** (integer) - Required - The highlight mode (0=close, 1=open). ### Request Example { "Command": "Device/SetHighLightMode", "Mode": 0 } ``` -------------------------------- ### ResponseModel class definition Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/models-misc.md Defines the common response payload with a required message field. Returned by all set and draw handlers, send_text, send_gif, download_gif, download_image, and GET /health. ```python class ResponseModel(BaseModel): message: str ``` -------------------------------- ### PUT /visualizer/{number} Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Sets the visualizer to the given visualizer number. Returns a ResponseModel with message 'OK'. ```APIDOC ## PUT /visualizer/{number} ### Description Sets the visualizer to the given visualizer number. Returns a ResponseModel with message 'OK'. ### Method PUT ### Endpoint /visualizer/{number} ### Parameters #### Path Parameters - **number** (int) - Required - Visualizer number. Must be greater than or equal to 0. ### Response #### Success Response (200) - **message** (string) - Always 'OK'. #### Response Example { "message": "OK" } ``` -------------------------------- ### POST /passthrough/device/setWhiteBalance Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Sets the white balance using RGB values. ```APIDOC ## POST /passthrough/device/setWhiteBalance ### Description Sets the white balance using RGB values. ### Method POST ### Endpoint /passthrough/device/setWhiteBalance ### Parameters #### Request Body - **Command** (string) - Required - The command string, e.g., "Device/SetWhiteBalance". - **RValue** (integer) - Required - The red value. - **GValue** (integer) - Required - The green value. - **BValue** (integer) - Required - The blue value. ### Request Example { "Command": "Device/SetWhiteBalance", "RValue": 100, "GValue": 100, "BValue": 100 } ``` -------------------------------- ### Route registration loop for passthrough routes Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/routers.md Registers 28 POST routes on the router. For each route in `passthrough_routes`, it adds an API route with the path, a name derived by removing the `/passthrough/` prefix, the description, and the endpoint created by `create_endpoint`. ```python for passthrough_route in passthrough_routes: router.add_api_route( name=passthrough_route.route_path.removeprefix('/passthrough/'), methods=['POST'], path=passthrough_route.route_path, description=passthrough_route.description, endpoint=create_endpoint(passthrough_route) ) ``` -------------------------------- ### POST /passthrough/channel/onOffScreen Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/endpoints.md Turns the screen on or off. The OnOff parameter is 1 for on and 0 for off. ```APIDOC ## POST /passthrough/channel/onOffScreen ### Description Turns the screen on or off. The OnOff parameter is 1 for on and 0 for off. ### Method POST ### Endpoint /passthrough/channel/onOffScreen ### Parameters #### Request Body - **Command** (string) - Required - The command string, e.g., "Channel/OnOffScreen". - **OnOff** (integer) - Required - 1=on, 0=off. ### Request Example { "Command": "Channel/OnOffScreen", "OnOff": 1 } ``` -------------------------------- ### health: health check endpoint Source: https://github.com/4ch1m/pixoo-rest/blob/master/_autodocs/api-reference/main.md Route handler for GET /health that returns a ResponseModel with message='OK', producing {"message": "OK"}. Used by Docker HEALTHCHECK and Helm liveness probe. ```python @app.get('/health', response_model=ResponseModel) async def health() -> ResponseModel: return ResponseModel(message='OK') ``` -------------------------------- ### Clone the pixoo-rest repository Source: https://github.com/4ch1m/pixoo-rest/blob/master/README.md Clones the pixoo-rest repository from GitHub. ```bash git clone https://github.com/4ch1m/pixoo-rest.git ```