MultiTimer API (Android)

# MultiTimer API Guide

The API lets external apps, automation tools, or ADB control timers, stopwatches, counters, and other MultiTimer instruments. Commands are sent as an Android broadcast with the action `com.multitimer.api`.

## Quick Start

Send the command to the `com.persapps.multitimer` app:

```sh

adb shell am broadcast \

  --include-stopped-packages \

  -a com.multitimer.api \

  -p com.persapps.multitimer \

  --es action start

```

This command starts every instrument that supports the `start` action. To target a specific instrument, add the `board`, `instrument`, `model`, or `state` filters.

```sh

adb shell am broadcast \

  --include-stopped-packages \

  -a com.multitimer.api \

  -p com.persapps.multitimer \

  --es action pause \

  --es instrument "Workout"

```

## Command Format

The broadcast must include the `action` extra.

| Extra | Type | Required | Purpose |

| --- | --- | --- | --- |

| `action` | string | yes | The command to execute. |

| `value` | string | no | Numeric value for `start`, `add_time`, and `add_value`. |

| `board` | string | no | Board name to search within. |

| `instrument` | string | no | Instrument name. |

| `model` | string | no | Instrument type. |

| `state` | string | no | Current instrument state. |

If no filters are provided, the command is applied to all matching instruments.

## Actions

| `action` | `value` | Description |

| --- | --- | --- |

| `tap` | none | Performs the instrument's primary action, like tapping it in the app UI. |

| `run` | none | Runs a button in the Buttons instrument. |

| `start` | none | Starts an instrument. |

| `start` | seconds | Starts a Quick timer with the specified duration. |

| `reset` | none | Resets an instrument. |

| `pause` | none | Pauses an instrument. |

| `continue` | none | Continues an instrument after a pause. |

| `next` | none | Moves an Interval timer to the next interval. |

| `lap` | none | Adds a lap to a Stopwatch. |

| `add_time` | seconds | Adds time to a timer. |

| `add_value` | integer | Changes a Counter value. |

| `get_value` | none | Returns the current value without changing state. |

`value` is always passed as a string. Time values are expressed in seconds.

## Target Filters

Filters can be combined. The command is executed only for instruments that match every provided condition.

### Instrument Type

The `model` extra supports these values:

| `model` | Instrument |

| --- | --- |

| `countdown` | Countdown timer |

| `quick` | Quick timer |

| `interval` | Interval timer |

| `pomodoro` | Pomodoro timer |

| `countup` | Countup timer |

| `stopwatch` | Stopwatch |

| `counter` | Counter |

| `button` | Buttons |

### State

The `state` extra supports these values:

| `state` | Meaning |

| --- | --- |

| `inactive` | The instrument is inactive. |

| `running` | The instrument is running. |

| `waiting` | The instrument is waiting or paused. |

| `completed` | The instrument is completed. |

## ADB Examples

Start a specific timer:

```sh

adb shell am broadcast \

  --include-stopped-packages \

  -a com.multitimer.api \

  -p com.persapps.multitimer \

  --es action start \

  --es instrument "Tea"

```

Start a Quick timer for 5 minutes:

```sh

adb shell am broadcast \

  --include-stopped-packages \

  -a com.multitimer.api \

  -p com.persapps.multitimer \

  --es action start \

  --es model quick \

  --es value 300

```

Pause all running timers on the `Kitchen` board:

```sh

adb shell am broadcast \

  --include-stopped-packages \

  -a com.multitimer.api \

  -p com.persapps.multitimer \

  --es action pause \

  --es board "Kitchen" \

  --es state running

```

Add 1 minute to a timer:

```sh

adb shell am broadcast \

  --include-stopped-packages \

  -a com.multitimer.api \

  -p com.persapps.multitimer \

  --es action add_time \

  --es instrument "Workout" \

  --es value 60

```

Increase a counter by 3:

```sh

adb shell am broadcast \

  --include-stopped-packages \

  -a com.multitimer.api \

  -p com.persapps.multitimer \

  --es action add_value \

  --es model counter \

  --es instrument "Sets" \

  --es value 3

```

Get the current value:

```sh

adb shell am broadcast \

  --include-stopped-packages \

  -a com.multitimer.api \

  -p com.persapps.multitimer \

  --es action get_value \

  --es instrument "Sets"

```

For `get_value` and other commands that return a result, the app puts the value into the `result` extra. Timers return the result in seconds, and counters return an integer.

## Calling from an Android App

Use an ordered broadcast if you need to read `result`.

```kotlin

val intent = Intent("com.multitimer.api")

    .setPackage("com.persapps.multitimer")

    .putExtra("action", "get_value")

    .putExtra("instrument", "Sets")

context.sendOrderedBroadcast(

    intent,

    null,

    object : BroadcastReceiver() {

        override fun onReceive(context: Context, intent: Intent) {

            if (resultCode != Activity.RESULT_OK) return

            val value = resultExtras?.getInt("result")

        }

    },

    null,

    Activity.RESULT_CANCELED,

    null,

    null

)

```

If you do not need a result, you can send a regular broadcast:

```kotlin

val intent = Intent("com.multitimer.api")

    .setPackage("com.persapps.multitimer")

    .putExtra("action", "pause")

    .putExtra("state", "running")

context.sendBroadcast(intent)

```

## Results and Errors

If the command is handled without an internal error, the ordered broadcast returns `Activity.RESULT_OK`. This also applies when the selected instrument does not change state, for example when `reset` is sent to an already reset timer. If the command is not recognized or an execution error occurs, the broadcast returns `Activity.RESULT_CANCELED`.

A command may fail if the instrument is not found, the action is not supported by the selected instrument type, or `value` is missing where it is required. If a command is applied to multiple instruments, the time or counter `result` is the sum of the values from all affected instruments.