> For the complete documentation index, see [llms.txt](https://docs.chirpwireless.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.chirpwireless.io/devices/commands/creating-commands.md).
# Setting up a command
A command is a saved action with a friendly name — "Turn on", "Set brightness", "Warm white" — that you create once and then use again and again. After it's set up, you (or anyone you share your home with) can run it without ever seeing the technical bits.
Open the device, go to the **Commands & States** tab, stay on the **Commands** part, and tap **Add new command**. The setup screen is split into four short steps.
## 1. Name it
* **Command name** — Required. Pick something you'll recognize at a glance, like `Turn on` or `Movie lighting`. Each command on a device needs its own name.
* **Description** — Optional. A quick note about what it does.
## 2. Point it at your device
This tells Chirp how to reach the device. What you see depends on how the device is connected.
### Devices on MQTT (most smart home gear)
* **MQTT topic** — The address the message is sent to.
* On Chirp's hosted broker, the first part of the address (the prefix) is filled in for you; you add the rest, like `living-room-lamp/set`. Your device needs to be listening on the full address.
* On your own broker, type the full topic exactly as your device expects it.
* If another command already uses the same address, Chirp gives you a heads-up so two actions don't clash.
### Devices on LoRaWAN
* **fPort** — A number from **1 to 223** that tells the device which "channel" the message is for. Your device's manual will tell you which to use.
* **Confirmed downlink** — A switch: leave it **On** to have the network wait for the device to confirm it got the message, or **Off** to simply send and move on.
## 3. What the command does
This is where you set up any choices the command offers and the message it sends.
### Inputs (parameters)
If your command needs a value — a brightness level, a color temperature, a mode — add it as a **parameter** with **Add Parameter**. For each one:
* Give it a **Name** and a short **Description** (the description is what you'll see when you run the command).
* Pick a **Type**:
* **Integer** or **Float** for numbers, with an optional smallest (**Min**), largest (**Max**), and starting (**Default**) value — great for a 0–100 brightness.
* **String** for text, with an optional list of allowed choices (an **Enum** like `auto, manual, off`).
* **Boolean** for a simple on/off or true/false.
Setting a Min and Max means you can never accidentally send a brightness of 500% — Chirp keeps the value sensible for you.
### The message itself
For MQTT devices, you choose how the message is built:
* **Send as-is** — send the message straight through (best when your device understands plain JSON).
* **Process with encoder** — run it through a small converter first.
When a converter is used (and it always is for LoRaWAN, where messages have to be turned into raw bytes), you write a short **template** with `{{ placeholders }}` that get filled in with your inputs — so a "set brightness" command drops the brightness number into the right spot. Most of the time the converter that came with your device's setup is all you need; advanced users can supply their own.
## Test it before you save
Whenever a converter is involved, there's a **Try it** tool right in the setup screen. Put in some test values and run it to see exactly what will be sent — including the technical form of the message and whether it ran cleanly. It's a no-risk way to be sure the command is right *before* it ever reaches your device.
## Save
Tap **Save**. The command shows up straight away in your list of commands and on the **States** tab, ready to use. You can **Edit** it later, or **Delete** it if you no longer need it.
## What's next
* Decide how Chirp confirms the command worked — [Making sure it worked](/devices/commands/verification.md).
* Actually press the button — [Sending a command](/devices/commands/executing-commands.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.chirpwireless.io/devices/commands/creating-commands.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.