Skip to main content

# Send Controller Logs (LCC.log)

## Signature​

    LCC.log(id, ...)
    LCC.log(log_map)

## Parameters​

- id
  Integer from 1 to 6, pointing to one of the controller's six log channels.
- ...
  Variadic arguments. Strings, tables, or `ImageObject`; regular tables are serialised with `table.deep_dump`, and strings can embed `[DATE]` and `[LINE]` placeholders.
- log_map
  Table whose keys match the aliases defined via `set_log_aliases`; values can be strings, tables, `ImageObject`, or array tables containing mixed text and images.

## Returns​

- none

## Notes​

> Validates that a controller address has been configured, otherwise raises an error.
> Retries on network issues until the log is delivered; during retries a `sys.toast` notification is shown.
> When using the alias map form, only keys that match an alias are sent, routed to the corresponding channel number. If no alias keys match, the call returns without sending a request.

## Example​

    LCC.log(1, "[DATE] sync starting", { count = 128 })

    LCC.log({
        ["Status"] = "Sync complete",
        ["Error"] = "0"
    })

## Image Logs​

`LCC.log` supports mixed text, regular tables, and images. Passing an `ImageObject` writes the image as PNG by default. Passing a string in the form `data:image/png;base64,...` or `data:image/jpeg;base64,...` is also detected as an image.

    LCC.log(1, "Start", screen.image(100, 100, 200, 200), "Done")

If you want a smaller payload, compress the image yourself and pass a JPEG data URL:

    local img = screen.image(100, 100, 200, 200)
    local jpg = "data:image/jpeg;base64," .. img:jpeg_data(0.7):base64_encode()
    LCC.log(1, "Compressed screenshot", jpg)
    img:destroy()

The alias map form supports image logs too. A regular table without images is still rendered through `table.deep_dump`; an array table containing images is rendered in array order as mixed text and images.

    LCC.set_log_aliases({ "Status", "Error" })

    LCC.log({
        ["Status"] = { "Hello", screen.image(243, 247, 336, 345), "World" },
        ["Error"] = "0"
    })

Image logs are best used for diagnostics or important visual evidence, not as part of routine progress logging. A single image can be up to 20 MiB, all images in one log entry can total up to 20 MiB, each image can be up to 12 megapixels, and one log entry can contain up to 8 images. If a limit is exceeded or the image format is unsupported, `LCC.log` raises an error. Images are uploaded together with the log request; when many devices are active, capture regions are large, or logs are emitted very frequently, image payloads can add noticeable LAN traffic, server decoding work, and disk I/O, which may slow down other control requests. Prefer logging screenshots only at important checkpoints and crop them to the area you need to inspect; for continuous sampling, lower the frequency or pass a self-compressed JPEG data URL.

Log history displays thumbnails. Clicking a thumbnail opens the original image preview, and the preview can be opened in the Color Picker. When exporting logs that contain images, you can choose plain text only or a zip file containing the original images and a browsable HTML file. If an original image file is already missing, the HTML export shows a missing-image placeholder while keeping the other log content and available images.