### GET /v0/devices/{deviceID}/installations/{installationID}/preview - Get Installation Preview

Source: https://tidbyt.dev/docs/tidbyt-api

Generates and retrieves a preview image for a specific app installation on a device.

```APIDOC
## GET /v0/devices/{deviceID}/installations/{installationID}/preview

### Description
Get a preview image.

### Method
GET

### Endpoint
/v0/devices/{deviceID}/installations/{installationID}/preview

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device.
- **installationID** (string) - Required - The ID of the installation to get a preview for.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **image** (google.api.HttpBody) - The preview image data.

#### Response Example
(Response body would contain image data, e.g., PNG or JPEG)
```json
{
  "image": {
    "contentType": "image/png",
    "data": "base64_encoded_image_data"
  }
}
```
```

--------------------------------

### Install Pixlet on Linux

Source: https://tidbyt.dev/docs/build/installing-pixlet

This snippet outlines the steps to install the Pixlet CLI tool on Linux. It involves downloading the binary from a release URL, extracting it, making it executable, and moving it to a directory in the system's PATH.

```shell
# Download the archive.
curl -LO https://github.com/tidbyt/pixlet/releases/download/v0.22.4/pixlet_0.22.4_linux_amd64.tar.gz

# Unpack the archive.
tar -xvf pixlet_0.22.4_linux_amd64.tar.gz

# Ensure the binary is executable.
chmod +x ./pixlet

# Move the binary into your path.
sudo mv pixlet /usr/local/bin/pixlet
```

--------------------------------

### POST /v0/devices/{deviceID}/install - Install App

Source: https://tidbyt.dev/docs/tidbyt-api

Installs an app onto a specific device.

```APIDOC
## POST /v0/devices/{deviceID}/install

### Description
Install app.

### Method
POST

### Endpoint
/v0/devices/{deviceID}/install

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device to install the app on.

#### Query Parameters
None

#### Request Body
- **appID** (string) - Required - The ID of the app to install.
- **version** (string) - Optional - The specific version of the app to install.

### Request Example
```json
{
  "appID": "app_12345",
  "version": "v1.2.0"
}
```

### Response
#### Success Response (200)
- **installation** (tidbyt.api.Installation) - Details of the new installation.

#### Response Example
```json
{
  "installation": {
    "id": "install_def456",
    "appID": "app_12345",
    "version": "v1.2.0"
  }
}
```
```

--------------------------------

### GET /v0/devices/{deviceID}/installations - List Installations

Source: https://tidbyt.dev/docs/tidbyt-api

Lists all apps installed on a specific device.

```APIDOC
## GET /v0/devices/{deviceID}/installations

### Description
List installations.

### Method
GET

### Endpoint
/v0/devices/{deviceID}/installations

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device to list installations for.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **installations** (tidbyt.api.ListOfInstallations) - A list of installations on the device.

#### Response Example
```json
{
  "installations": [
    {
      "id": "install_xyz789",
      "appID": "app_12345",
      "version": "v1.2.0"
    }
  ]
}
```
```

--------------------------------

### Verify Pixlet Installation on Windows

Source: https://tidbyt.dev/docs/build/installing-pixlet

This snippet demonstrates the command to run in PowerShell on Windows to verify that the Pixlet CLI tool has been installed correctly and is accessible in the system's PATH. This command should output the Pixlet version if the installation was successful.

```powershell
pixlet version
```

--------------------------------

### Tidbyt Device Operations API

Source: https://tidbyt.dev/docs/api

Operations for listing, getting, updating, and managing devices and their installations.

```APIDOC
## GET /v0/devices

### Description
List devices.

### Method
GET

### Endpoint
/v0/devices

### Parameters
(No parameters)

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **devices** (tidbyt.api.ListOfDevices) - A list of devices.

#### Response Example
(No example provided)

## PATCH /v0/devices/{device.id}

### Description
Update device details.

### Method
PATCH

### Endpoint
/v0/devices/{device.id}

### Parameters
#### Path Parameters
- **device.id** (string) - Required - The ID of the device to update.

#### Request Body
(Request body details not specified, likely includes fields to update)

### Request Example
(No example provided)

### Response
#### Success Response (200)
(No specific response fields mentioned)

#### Response Example
(No example provided)

## GET /v0/devices/{deviceID}

### Description
Get device details.

### Method
GET

### Endpoint
/v0/devices/{deviceID}

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device to get details for.

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **device** (tidbyt.api.Device) - Details of the specified device.

#### Response Example
(No example provided)

## POST /v0/devices/{deviceID}/install

### Description
Install an app on a device.

### Method
POST

### Endpoint
/v0/devices/{deviceID}/install

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device to install the app on.

#### Request Body
(Request body details not specified, likely includes app ID and version)

### Request Example
(No example provided)

### Response
#### Success Response (200)
(No specific response fields mentioned)

#### Response Example
(No example provided)

## GET /v0/devices/{deviceID}/installations

### Description
List installations for a device.

### Method
GET

### Endpoint
/v0/devices/{deviceID}/installations

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device to list installations for.

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **installations** (tidbyt.api.ListOfInstallations) - A list of app installations on the device.

#### Response Example
(No example provided)

## DELETE /v0/devices/{deviceID}/installations/{installationID}

### Description
Delete an app installation from a device.

### Method
DELETE

### Endpoint
/v0/devices/{deviceID}/installations/{installationID}

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device.
- **installationID** (string) - Required - The ID of the installation to delete.

### Request Example
(No example provided)

### Response
#### Success Response (200)
(No specific response fields mentioned)

#### Response Example
(No example provided)

## POST /v0/devices/{deviceID}/installations/{installationID}

### Description
Update an app installation on a device.

### Method
POST

### Endpoint
/v0/devices/{deviceID}/installations/{installationID}

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device.
- **installationID** (string) - Required - The ID of the installation to update.

#### Request Body
(Request body details not specified, likely includes updated installation parameters)

### Request Example
(No example provided)

### Response
#### Success Response (200)
(No specific response fields mentioned)

#### Response Example
(No example provided)

## GET /v0/devices/{deviceID}/installations/{installationID}/preview

### Description
Get a preview image of an app installation.

### Method
GET

### Endpoint
/v0/devices/{deviceID}/installations/{installationID}/preview

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device.
- **installationID** (string) - Required - The ID of the installation.

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **httpBody** (google.api.HttpBody) - The preview image data.

#### Response Example
(No example provided)

## POST /v0/devices/{deviceID}/push

### Description
Push content to a device.

### Method
POST

### Endpoint
/v0/devices/{deviceID}/push

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device to push to.

#### Request Body
(Request body details not specified, likely includes the content to push)

### Request Example
(No example provided)

### Response
#### Success Response (200)
(No specific response fields mentioned)

#### Response Example
(No example provided)
```

--------------------------------

### Example of using XPath module

Source: https://tidbyt.dev/docs/reference/modules

Demonstrates how to load an XML document and query for specific elements using the `xpath` module in Pixlet.

```star
load("xpath.star", "xpath")

doc = """
<foo>
    <bar>bar</bar>
    <bar>baz</bar>
</foo>
"""

def get_bars():
    x = xpath.loads(doc)
    return x.query_all("/foo/bar")

def also_get_bars():
    x = xpath.loads(doc)
    foo = x.query_node("/foo")
    return foo.query_all("/bar")
```

--------------------------------

### Install Pixlet on macOS using Homebrew

Source: https://tidbyt.dev/docs/build/installing-pixlet

This snippet shows the command to install the Pixlet CLI tool on macOS using the Homebrew package manager. It assumes Homebrew is already installed.

```shell
brew install tidbyt/tidbyt/pixlet
```

--------------------------------

### POST /v0/devices/{deviceID}/installations/{installationID} - Update Installation

Source: https://tidbyt.dev/docs/tidbyt-api

Updates an existing app installation on a device (e.g., change version).

```APIDOC
## POST /v0/devices/{deviceID}/installations/{installationID}

### Description
Updates an installation.

### Method
POST

### Endpoint
/v0/devices/{deviceID}/installations/{installationID}

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device.
- **installationID** (string) - Required - The ID of the installation to update.

#### Query Parameters
None

#### Request Body
- **version** (string) - Required - The new version of the app to install.

### Request Example
```json
{
  "version": "v1.3.0"
}
```

### Response
#### Success Response (200)
- **installation** (tidbyt.api.Installation) - Details of the updated installation.

#### Response Example
```json
{
  "installation": {
    "id": "install_xyz789",
    "appID": "app_12345",
    "version": "v1.3.0"
  }
}
```
```

--------------------------------

### Rendering App with Schema Configuration via Pixlet

Source: https://tidbyt.dev/docs/reference/schema

Example of how to render a Tidbyt app using the `pixlet render` command with specific schema configurations. This allows testing different user inputs for the 'who' and 'small' fields.

```bash
pixlet render schema_hello_world.star who="Tidbyt" small=True
```

--------------------------------

### Pixlet Serve Cache Demonstration (Shell)

Source: https://tidbyt.dev/docs/build/crypto-tracker

Demonstrates the effect of caching when running a Tidbyt application using `pixlet serve`. The output shows 'Miss! Calling CoinDesk API.' on the first request and 'Hit! Displaying cached data.' on subsequent requests within the cache's TTL (Time To Live).

```shell
$ ./pixlet serve tutorial.star
listening on tcp/8080
[tutorial.star] Miss! Calling CoinDesk API.
[tutorial.star] Hit! Displaying cached data.
[tutorial.star] Hit! Displaying cached data.

```

--------------------------------

### GET /v0/apps/{appID}/versions - List App Versions

Source: https://tidbyt.dev/docs/tidbyt-api

Lists all available versions for a specific app.

```APIDOC
## GET /v0/apps/{appID}/versions

### Description
List app versions.

### Method
GET

### Endpoint
/v0/apps/{appID}/versions

### Parameters
#### Path Parameters
- **appID** (string) - Required - The ID of the app to list versions for.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **versions** (tidbyt.api.ListOfAppVersions) - A list of app version identifiers.

#### Response Example
```json
{
  "versions": [
    "v1.0.0",
    "v1.1.0",
    "v1.2.0"
  ]
}
```
```

--------------------------------

### GET /v0/devices - List Devices

Source: https://tidbyt.dev/docs/tidbyt-api

Lists all devices associated with the user's account.

```APIDOC
## GET /v0/devices

### Description
List devices.

### Method
GET

### Endpoint
/v0/devices

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **devices** (tidbyt.api.ListOfDevices) - A list of the user's devices.

#### Response Example
```json
{
  "devices": [
    {
      "id": "device_abc123",
      "displayName": "Living Room Tidbyt",
      "installationID": "install_xyz789",
      "lastSeen": "2023-10-27T10:00:00Z"
    }
  ]
}
```
```

--------------------------------

### GET /v0/apps - List Available Apps

Source: https://tidbyt.dev/docs/tidbyt-api

Lists all available apps in the Tidbyt ecosystem.

```APIDOC
## GET /v0/apps

### Description
List available apps.

### Method
GET

### Endpoint
/v0/apps

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **apps** (tidbyt.api.ListOfApps) - A list of available apps.

#### Response Example
```json
{
  "apps": [
    {
      "id": "string",
      "title": "string",
      "author": "string",
      "description": "string",
      "installedCount": 0
    }
  ]
}
```
```

--------------------------------

### Display Bitcoin Price with Layout and Icon (Starlark)

Source: https://tidbyt.dev/docs/build/crypto-tracker

Fetches the current Bitcoin price from CoinDesk API and displays it with an icon. It uses `render.Row` for layout, `expanded=True` to use available horizontal space, and `main_align` and `cross_align` for child spacing. The `render.Box` is used for vertical centering. Dependencies include 'render.star', 'http.star', and 'encoding/base64.star'.

```starlark
load("render.star", "render")
load("http.star", "http")
load("encoding/base64.star", "base64")

COINDESK_PRICE_URL = "https://api.coindesk.com/v1/bpi/currentprice.json"

BTC_ICON = base64.decode("""
iVBORw0KGgoAAAANSUhEUgAAABEAAAARCAYAAAA7bUf6AAAAlklEQVQ4T2NkwAH+H2T/jy7FaP+
TEZtyDEG4Zi0TTPXXzoDF0A1DMQRsADbN6MZdO4NiENwQbAbERh1lWLzMmgFGo5iFZBDYEFwuwG
sISCPUIKyGgDRjAyBXYXMNIz5XgDQga8TpLboYgux8DO/AwoUuLiEqTLBFMcmxQ7V0gssgklIsL
AYozjsoBoE45OZi5DRBSnkCAMLhlPBiQGHlAAAAAElFTkSuQmCC
""")

def main():
    rep = http.get(COINDESK_PRICE_URL)
    if rep.status_code != 200:
        fail("Coindesk request failed with status %d", rep.status_code)

    rate = rep.json()["bpi"]["USD"]["rate_float"]

    return render.Root(
        child = render.Box( # This Box exists to provide vertical centering
            render.Row(
                expanded=True, # Use as much horizontal space as possible
                main_align="space_evenly", # Controls horizontal alignment
                cross_align="center", # Controls vertical alignment
                children = [
                    render.Image(src=BTC_ICON),
                    render.Text("$"%d" % rate),
                ],
            ),
        ),
    )

```

--------------------------------

### Pixlet Animation Widget Example

Source: https://tidbyt.dev/docs/reference/widgets

Demonstrates the use of the Animation widget to create a sequence of frames from child widgets. Each child widget represents a single frame in the animation. Supports CSS-like hexdecimal color specifications.

```python
render.Animation(
     children=[
          render.Box(width=10, height=10, color="#300"),
          render.Box(width=12, height=12, color="#500"),
          render.Box(width=14, height=14, color="#700"),
          render.Box(width=16, height=16, color="#900"),
          render.Box(width=18, height=18, color="#b00"),
     ],
)
```

--------------------------------

### HTTP Client with Caching (Pixlet)

Source: https://tidbyt.dev/docs/reference/modules

Illustrates using the Pixlet HTTP module, which includes caching capabilities. The `ttl_seconds` parameter controls cache duration. It handles GET requests and includes basic error checking for non-200 status codes.

```starlark
load("http.star", "http")
def get_data(url):
    res = http.get(url, ttl_seconds=3600) # cache for 1 hour
    if res.status_code != 200:
        fail("GET %s failed with status %d: %s", url, res.status_code, res.body())
    return res.json()
```

--------------------------------

### Cache Bitcoin Price API Calls (Starlark)

Source: https://tidbyt.dev/docs/build/crypto-tracker

Fetches the current Bitcoin price from CoinDesk API with caching enabled. It uses `http.get()` with the `ttl_seconds` parameter to cache responses for a specified duration, reducing redundant API calls. Includes print statements to indicate cache hits or misses for debugging. Dependencies: 'render.star', 'http.star', 'encoding/base64.star'.

```starlark
load("render.star", "render")
load("http.star", "http")
load("encoding/base64.star", "base64")

COINDESK_PRICE_URL = "https://api.coindesk.com/v1/bpi/currentprice.json"

BTC_ICON = base64.decode("""
iVBORw0KGgoAAAANSUhEUgAAABEAAAARCAYAAAA7bUf6AAAAlklEQVQ4T2NkwAH+H2T/jy7FaP+
TEZtyDEG4Zi0TTPXXzoDF0A1DMQRsADbN6MZdO4NiENwQbAbERh1lWLzMmgFGo5iFZBDYEFwuwG
sISCPUIKyGgDRjAyBXYXMNIz5XgDQga8TpLboYgux8DO/AwoUuLiEqTLBFMcmxQ7V0gssgklIsL
AYozjsoBoE45OZi5DRBSnkCAMLhlPBiQGHlAAAAAElFTkSuQmCC
""")

def main():
    rep = http.get(COINDESK_PRICE_URL, ttl_seconds = 240) # cache for 4 minutes
    if rep.status_code != 200:
        fail("Coindesk request failed with status %d", rep.status_code)
    rate = rep.json()["bpi"]["USD"]["rate_float"]

    # for development purposes: check if result was served from cache or not
    if rep.headers.get("Tidbyt-Cache-Status") == "HIT":
        print("Hit! Displaying cached data.")
    else:
        print("Miss! Calling CoinDesk API.")

    return render.Root(
        child = render.Box(
            render.Row(
                expanded=True,
                main_align="space_evenly",
                cross_align="center",
                children = [
                    render.Image(src=BTC_ICON),
                    render.Text("$"%d" % rate),
                ],
            ),
        ),
    )

```

--------------------------------

### Pixlet Box Widget Example

Source: https://tidbyt.dev/docs/reference/widgets

Illustrates the Box widget, which creates a rectangular area that can contain a child widget. Boxes are transparent by default but can be colored and sized. Supports padding around the child.

```python
render.Box(
     color="#00f",
     child=render.Box(
          width=20,
          height=10,
          color="#f00",
     )
)
```

--------------------------------

### Pixlet Circle Widget Example

Source: https://tidbyt.dev/docs/reference/widgets

Shows how to use the Circle widget to draw a circle with a specified diameter and color. An optional child widget can be placed in the center of the circle.

```python
render.Circle(
     color="#666",
     diameter=30,
     child=render.Circle(color="#0ff", diameter=10),
)
```

--------------------------------

### Generated Field Handler Example (Python)

Source: https://tidbyt.dev/docs/reference/schema

An example handler function for a 'generated' schema field. It takes the value from a source field (e.g., 'pet') and returns a list of additional schema fields based on that value.

```python
def more_options(pet):
    if pet == "dog":
        return [
            schema.Toggle(
                id = "leash",
                name = "Leash",
                desc = "A toggle to enable a dog leash.",
                icon = "gear",
                default = False,
            ),
        ]
    elif pet == "cat":
        return [
            schema.Toggle(
                id = "litter-box",
                name = "Litter Box",
                desc = "A toggle to enable a litter box.",
                icon = "gear",
                default = False,
            ),
        ]
    else:
        return []

```

--------------------------------

### Display Bitcoin Price and Icon using Pixlet

Source: https://tidbyt.dev/docs/build/crypto-tracker

Fetches Bitcoin price data and displays it alongside a custom Bitcoin icon. The icon is embedded using base64 encoding via Starlib's encoding/base64 module. A render.Row widget is used to lay out the icon and text horizontally.

```starlark
load("render.star", "render")
load("http.star", "http")
load("encoding/base64.star", "base64")

COINDESK_PRICE_URL = "https://api.coindesk.com/v1/bpi/currentprice.json"

# Load Bitcoin icon from base64 encoded data
BTC_ICON = base64.decode("""
iVBORw0KGgoAAAANSUhEUgAAABEAAAARCAYAAAA7bUf6AAAAlklEQVQ4T2NkwAH+H2T/jy7FaP+
TEZtyDEG4Zi0TTPXXzoDF0A1DMQRsADbN6MZdO4NiENwQbAbERh1lWLzMmgFGo5iFZBDYEFwuwG
sISCPUIKyGgDRjAyBXYXMNIz5XgDQga8TpLboYgux8DO/AwoUuLiEqTLBFMcmxQ7V0gssgklIsL
AYozjsoBoE45OZi5DRBSnkCAMLhlPBiQGHlAAAAAElFTkSuQmCC
""")

def main():
    rep = http.get(COINDESK_PRICE_URL)
    if rep.status_code != 200:
        fail("CoinDesk request failed with status %d", rep.status_code)

    rate = rep.json()["bpi"]["USD"]["rate_float"]

    return render.Root(
        child = render.Row( # Row lays out its children horizontally
                children = [
                    render.Image(src=BTC_ICON),
                    render.Text("$%d" % rate),
                ],
        )
    )

```

--------------------------------

### GET /v0/account

Source: https://tidbyt.dev/docs/api

GetAccountDetails returns details about your user account.

```APIDOC
## GET /v0/account

### Description
GetAccountDetails returns details about your user account.

### Method
GET

### Endpoint
/v0/account

### Parameters
#### Query Parameters
(No query parameters)

#### Request Body
(No request body)

### Request Example
(No example provided)

### Response
#### Success Response (200)
- **accountDetails** (tidbyt.api.AccountDetails) - Details about the user account.

#### Response Example
(No example provided)
```

--------------------------------

### Location Data Format Example (JSON)

Source: https://tidbyt.dev/docs/reference/schema

Illustrates the format of the location data returned when a user selects a location using the `schema.Location` field. This data can be accessed in the app via `config.get('location')`.

```json
{
	"lat": "40.6781784",
	"lng": "-73.9441579",
	"description": "Brooklyn, NY, USA",
	"locality": "Brooklyn",
	"place_id": "ChIJCSF8lBZEwokRhngABHRcdoI",
	"timezone": "America/New_York"
}

```

--------------------------------

### Create a Private App with Pixlet CLI

Source: https://tidbyt.dev/docs/build/private-apps

Command to create a new private app in the current directory using the Pixlet CLI. This is the initial step for developing a private Tidbyt application. Ensure you have Pixlet installed and are logged in.

```bash
pixlet private create
```

--------------------------------

### Fetch Bitcoin Price Data using Pixlet and Starlark

Source: https://tidbyt.dev/docs/build/crypto-tracker

Retrieves the current Bitcoin price from CoinDesk API using Starlib's http module. It checks the HTTP response status and fails if the request is unsuccessful. The current price is then extracted and displayed as text.

```starlark
load("render.star", "render")
load("http.star", "http")

COINDESK_PRICE_URL = "https://api.coindesk.com/v1/bpi/currentprice.json"

def main():
    rep = http.get(COINDESK_PRICE_URL)
    if rep.status_code != 200:
        fail("Coindesk request failed with status %d", rep.status_code)

    rate = rep.json()["bpi"]["USD"]["rate_float"]

    return render.Root(
        child = render.Text("BTC: %d USD" % rate)
    )

```

--------------------------------

### Pixlet Column Widget Example

Source: https://tidbyt.dev/docs/reference/widgets

Demonstrates the Column widget for arranging child widgets vertically. It supports alignment along both the main (vertical) and cross (horizontal) axes, and can be expanded to fill available space.

```python
render.Column(
     children=[
          render.Box(width=10, height=8, color="#a00"),
          render.Box(width=14, height=6, color="#0a0"),
          render.Box(width=16, height=4, color="#00a"),
     ],
)
```

--------------------------------

### Cache Module for Pixlet Apps

Source: https://tidbyt.dev/docs/reference/modules

Shows how to use the Pixlet cache module for storing and retrieving key-value pairs with a time-to-live (TTL). Both keys and values must be strings. The cache is unique per app, not per installation, which is a common source of bugs.

```starlark
load("cache.star", "cache")
def get_counter():
    i = cache.get("counter")
    if i == None:
        i = 0
    cache.set("counter", str(i + 1), ttl_seconds=3600)
    return i + 1
```

--------------------------------

### Hello, World! App in Starlark

Source: https://tidbyt.dev/docs/build/build-for-tidbyt

A basic 'Hello, World!' application written in Starlark, the language used for Pixlet apps. This code defines a simple text display.
Dependencies: None
Input: None
Output: Renders 'Hello, World!' text.

```starlark
load("render.star", "render")

def main():
    return render.Root(
        child = render.Text("Hello, World!")
    )
```

--------------------------------

### Tidbyt CLI Commands for App Management

Source: https://tidbyt.dev/docs/build/build-for-tidbyt

Commands to render, view, and push Tidbyt applications using the Pixlet CLI. This allows for local testing and deployment to a physical device.
Dependencies: Pixlet CLI, Tidbyt account, device ID.
Input: Starlark app file, device ID.
Output: Renders app to WebP, logs in user, lists devices, pushes app to device.

```bash
# render the bitcoin example
pixlet render examples/bitcoin.star

# login to your Tidbyt account
pixlet login

# list available Tidbyt devices
pixlet devices

# push to your favorite Tidbyt
pixlet push <YOUR DEVICE ID> examples/bitcoin.webp
```

--------------------------------

### GET /v0/devices/{deviceID} - Get Device Details

Source: https://tidbyt.dev/docs/tidbyt-api

Retrieves detailed information about a specific device.

```APIDOC
## GET /v0/devices/{deviceID}

### Description
Get device details.

### Method
GET

### Endpoint
/v0/devices/{deviceID}

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device to retrieve details for.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **device** (tidbyt.api.Device) - The details of the specified device.

#### Response Example
```json
{
  "device": {
    "id": "device_abc123",
    "displayName": "Living Room Tidbyt",
    "installationID": "install_xyz789",
    "lastSeen": "2023-10-27T10:00:00Z"
  }
}
```
```

--------------------------------

### GET /v0/account - Get Account Details

Source: https://tidbyt.dev/docs/tidbyt-api

Retrieves details about the authenticated user's account.

```APIDOC
## GET /v0/account

### Description
GetAccountDetails returns details about your user account.

### Method
GET

### Endpoint
/v0/account

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **accountDetails** (tidbyt.api.AccountDetails) - Details of the user account.

#### Response Example
```json
{
  "accountDetails": {
    "id": "string",
    "displayName": "string",
    "username": "string",
    "createdAt": "string",
    "updatedAt": "string"
  }
}
```
```

--------------------------------

### Basic Hello World App

Source: https://tidbyt.dev/docs/reference/schema

A simple Tidbyt app that displays 'Hello, World!' without any configuration options. This serves as a baseline before introducing schema.

```starlark
load("render.star", "render")

def main():
    return render.Root(
        child = render.Text("Hello, World!"),
    )

```

--------------------------------

### DELETE /v0/devices/{deviceID}/installations/{installationID} - Delete Installation

Source: https://tidbyt.dev/docs/tidbyt-api

Removes an installed app from a specific device.

```APIDOC
## DELETE /v0/devices/{deviceID}/installations/{installationID}

### Description
Delete an installation.

### Method
DELETE

### Endpoint
/v0/devices/{deviceID}/installations/{installationID}

### Parameters
#### Path Parameters
- **deviceID** (string) - Required - The ID of the device.
- **installationID** (string) - Required - The ID of the installation to delete.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
No specific response body mentioned, typically an empty success response or a confirmation message.

#### Response Example
```json
{
  "message": "Installation deleted successfully."
}
```
```

--------------------------------

### Render root widget with child

Source: https://tidbyt.dev/docs/reference/modules

Illustrates the basic usage of the `render` module to create a root widget with a child box, specifying dimensions and color.

```star
load("render.star", r="render")
def main():
    return r.Root(child=r.Box(width=12, height=14, color="#ff0"))
```

--------------------------------

### Performance Profiling with Pixlet

Source: https://tidbyt.dev/docs/build/authoring-apps

Shows how to use the `pixlet profile` command to analyze the performance of a Tidbyt app. This helps identify functions consuming the most CPU time, enabling targeted optimization for complex animations or scripts.

```shell
$ pixlet profile path_to_your_app.star
```

--------------------------------

### Hello World App with Schema Configuration

Source: https://tidbyt.dev/docs/reference/schema

An enhanced Tidbyt app that uses schema to allow users to configure the 'who' to greet and whether to use a small font. It demonstrates the `get_schema()` function and how to access configuration values within the `main` function.

```starlark
load("render.star", "render")
load("schema.star", "schema")

DEFAULT_WHO = "World"

def main(config):
    message = "Hello, %s!" % config.str("who", DEFAULT_WHO)

    if config.bool("small"):
        msg = render.Text(message, font = "CG-pixel-3x5-mono")
    else:
        msg = render.Text(message)

    return render.Root(
        child = msg,
    )

def get_schema():
    return schema.Schema(
        version = "1",
        fields = [
            schema.Text(
                id = "who",
                name = "Who?",
                desc = "Who to say hello to.",
                icon = "user",
            ),
            schema.Toggle(
                id = "small",
                name = "Display small text",
                desc = "A toggle to display smaller text.",
                icon = "compress",
                default = False,
            ),
        ],
    )

```

--------------------------------

### GET /v0/apps/{appID}/logs - List App Logs

Source: https://tidbyt.dev/docs/tidbyt-api

Retrieves logs for a specific (private) app.

```APIDOC
## GET /v0/apps/{appID}/logs

### Description
List logs for a (private) app.

### Method
GET

### Endpoint
/v0/apps/{appID}/logs

### Parameters
#### Path Parameters
- **appID** (string) - Required - The ID of the app to get logs for.

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (200)
- **logs** (tidbyt.api.ListOfAppLogs) - A list of log entries.

#### Response Example
```json
{
  "logs": [
    {
      "timestamp": "string",
      "message": "string"
    }
  ]
}
```
```

--------------------------------

### Get Device Information

Source: https://tidbyt.dev/docs/integrate/building-integrations

Retrieve information about a specific Tidbyt device. This endpoint requires API token authentication.

```APIDOC
## GET /v0/devices/{deviceId}

### Description
Retrieves detailed information about a specific Tidbyt device, identified by its Device ID.

### Method
GET

### Endpoint
https://api.tidbyt.com/v0/devices/<Device ID HERE>

### Parameters
#### Path Parameters
- **deviceId** (string) - Required - The unique identifier for the Tidbyt device.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -H "Authorization: Bearer <API Token HERE>" https://api.tidbyt.com/v0/devices/<Device ID HERE>
```

### Response
#### Success Response (200)
- **id** (string) - The device ID.
- **displayName** (string) - The user-defined name of the device.
- **brightness** (integer) - The current brightness level of the device (0-100).
- **autoDim** (boolean) - Indicates if auto-dimming is enabled.

#### Response Example
```json
{
  "id": "<Device ID>",
  "displayName": "My Tidbyt",
  "brightness": 20,
  "autoDim": false
}
```
```

--------------------------------

### Get day of the week

Source: https://tidbyt.dev/docs/reference/modules

Returns an integer representing the day of the week for a given `time.Time` object, where Sunday is 0 and Saturday is 6.

```star
day_of_week(date)
```

--------------------------------

### Create a Root Widget

Source: https://tidbyt.dev/docs/reference/widgets

The render.Root widget serves as the base for a widget tree, drawing its child on a 64x32 canvas. It can control animation delay and data expiration time (max_age). If no child is provided, it returns an empty list.

```python
render.Root(
  child=render.YourWidgetHere(),
  delay=1000,
  max_age=60
)

```

--------------------------------

### App Configuration Handling in Starlark

Source: https://tidbyt.dev/docs/build/authoring-apps

Demonstrates how to access and use configuration values within a Tidbyt app's main function using Starlark. It shows how to retrieve values, provide defaults, and use helper methods for type conversion.

```python
def main(config):
    who = config.get("who")
    print("Hello, %s" % who)
```

```python
DEFAULT_WHO = "world"

def main(config):
    who = config.get("who", DEFAULT_WHO)
    print("Hello, %s" % who)
```

```python
# config.str("foo") # returns a string, or None if not found
# config.bool("foo") # returns a boolean (True or False), or None if not found
```

--------------------------------

### Pixlet Cache Module

Source: https://tidbyt.dev/docs/reference/modules

The Pixlet cache module provides functions to store and retrieve key-value pairs with an expiration time. Note that the cache is shared across all installations of an app.

```APIDOC
## Pixlet Cache Module

Provides functions for caching data within an app.

__NOTE__: The cache is unique per app and shared across all installations.

### Functions
- **set(key, value, ttl_seconds=60)**: Writes a key-value pair to the cache with an expiration TTL.
  - **key** (string) - The key for the cache entry.
  - **value** (string) - The value to store.
  - **ttl_seconds** (integer) - Optional, defaults to 60. The time-to-live in seconds.
- **get(key)**: Retrieves a value by its key.
  - **key** (string) - The key of the cache entry to retrieve.
  - Returns the value if found and not expired, otherwise `None`.

Keys and values must be strings. Developers are responsible for serializing non-string data.

### Request Example
```starlark
load("cache.star", "cache")

def get_counter():
    i = cache.get("counter")
    if i == None:
        i = 0
    cache.set("counter", str(i + 1), ttl_seconds=3600)
    return i + 1
```
```

--------------------------------

### POST /v0/apps - Create App

Source: https://tidbyt.dev/docs/tidbyt-api

Creates a new app. Requires app details in the request body.

```APIDOC
## POST /v0/apps

### Description
Create a new app.

### Method
POST

### Endpoint
/v0/apps

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **app** (tidbyt.api.CreateAppRequest) - Required - The details of the app to create.

### Request Example
```json
{
  "app": {
    "title": "My New App",
    "author": "My Name",
    "description": "A cool new app for Tidbyt."
  }
}
```

### Response
#### Success Response (200)
- **app** (tidbyt.api.App) - The newly created app details.

#### Response Example
```json
{
  "app": {
    "id": "app_12345",
    "title": "My New App",
    "author": "My Name",
    "description": "A cool new app for Tidbyt.",
    "installedCount": 0
  }
}
```
```

--------------------------------

### Loading Pixlet Modules (Starlark)

Source: https://tidbyt.dev/docs/reference/modules

Demonstrates how to load modules in Starlark scripts. This includes assigning loaded modules to specific identifiers or aliasing them to different symbols. The `load` statement is used for this purpose.

```starlark
load("render.star", "render")
```

```starlark
load("render.star", r = "render")
```

--------------------------------

### Color Picker Schema Definition (Python)

Source: https://tidbyt.dev/docs/reference/schema

Defines a color picker field for app configuration using the schema library. It allows users to select a hex color string, which is directly usable in widgets. An optional 'palette' parameter can guide user selections.

```python
def get_schema():
    return schema.Schema(
        version = "1",
        fields = [
            schema.Color(
                id = "color",
                name = "Color",
                desc = "Color of the screen.",
                icon = "brush",
                default = "#7AB0FF",
            ),
        ],
    )

```

```python
def get_schema():
    return schema.Schema(
        version = "1",
        fields = [
            schema.Color(
                id = "color",
                name = "Color",
                desc = "Color of the screen.",
                icon = "brush",
                default = "#7AB0FF",
                palette = [
                    "#7AB0FF",
                    "#BFEDC4",
                    "#78DECC",
                    "#DBB5FF",
                ],
            ),
        ],
    )

```

--------------------------------

### Deploy a Private App with Pixlet CLI

Source: https://tidbyt.dev/docs/build/private-apps

Command to upload and deploy a private app to Tidbyt. This command should be run from the same directory where the app was created. It makes the app available within your Tidbyt account or organization.

```bash
pixlet private upload
```

--------------------------------

### render.Root Widget

Source: https://tidbyt.dev/docs/reference/widgets

The render.Root widget is the base for all widget trees, defining the canvas size and animation properties.

```APIDOC
## render.Root

### Description
Every Widget tree has a Root. The child widget, and all its descendants, will be drawn on a 64x32 canvas. Root places its child in the upper left corner of the canvas.

### Method
render.Root

### Endpoint
N/A (Widget)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **child** (Widget) - Required - The main widget to render within the root.
- **delay** (int) - Optional - The delay between animation frames in milliseconds.
- **max_age** (int) - Optional - The expiration time in seconds for the displayed content.
- **show_full_animation** (bool) - Optional - If true, the animation will be shown in its entirety, regardless of app cycle speed.

### Request Example
```python
return render.Root(
  child=render.Text("Hello World"),
  delay=100,
  max_age=30,
)
```

### Response
#### Success Response (200)
N/A (Widget)

#### Response Example
N/A (Widget)
```

--------------------------------

### List All Tidbyt Apps

Source: https://tidbyt.dev/docs/integrate/building-integrations

Retrieve a list of all available Tidbyt apps. This endpoint does not require authentication.

```APIDOC
## GET /v0/apps

### Description
Retrieves a list of all available Tidbyt applications.

### Method
GET

### Endpoint
https://api.tidbyt.com/v0/apps

### Parameters
None

### Request Example
```bash
curl "https://api.tidbyt.com/v0/apps"
```

### Response
#### Success Response (200)
- **apps** (array) - A list of app objects, each containing 'id', 'name', and 'description'.

#### Response Example
```json
{
  "apps": [
    {
      "id": "nationaltoday",
      "name": "NationalToday",
      "description": "Displays today's holidays from NationalToday."
    },
    {
      "id": "date-progress",
      "name": "Date Progress",
      "description": "Shows todays date as colorful progressbars, you can show the progress of the current day, month and year."
    }
  ]
}
```
```

--------------------------------

### Calculate Sunrise and Sunset Times with Pixlet Sunrise Module

Source: https://tidbyt.dev/docs/reference/modules

The `sunrise` module calculates sunrise and sunset times based on GPS coordinates and a timestamp. It provides functions to get sunrise time, sunset time, sun elevation at a specific time, and the times a specific elevation is reached.