MachineQ Developer Documentation logo DOCS
Back to Docs

Quick Start Guide

This guide walks you through running your first FUOTA campaign using the API: authenticating, creating a device group, uploading a firmware image, starting a campaign, and checking its status. You can use the same token you use for the MQcentral APIs.

Before You Begin

You need:

  • An MQcentral account with provisioned devices and gateways.
  • A list of DevEUIs you wish to update. A DevEUI is a unique device identifier, usually printed on the back of the device (for example 2CC407FFFE501234). Contact the manufacturer if you cannot find it.
  • A firmware image to push to the devices. The image is a binary file (.bin, .hex, or .sfb), usually provided by the device manufacturer.
  • Optionally, a nearby gateway's NodeID if you plan to select gateways manually. See Gateway Selection.
  • $MQ_TOKEN exported from the authentication step below.

Step 1: Authenticate

Fetch an access token from the MachineQ token provider to access the FUOTA API. For detailed instructions on obtaining and using your token, see the MQcentral Quick Start Guide.

Export your access token as an environment variable so the remaining examples can reuse it:

Export your access token
export MQ_TOKEN="<access_token_from_response>"

Step 2: Create a Device Group

Create a device group to describe the devices you want to update. You will get a device_group_id in the response, which you pass to the campaign later.

Create a device group
curl -sS -X POST "https://fuota.machineq.net/api/v3.2/device_groups" \
  -H "Authorization: Bearer $MQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "quickstart-device-group",
    "devices": ["0102030405060708", "0011223344556677"],
  }' | jq
API reference:

Step 3: Upload the Firmware Image

Upload the firmware image you want to push to the devices. Note the returned image name to reference it when creating the campaign.

Upload the firmware image
curl -sS -X POST "https://fuota.machineq.net/api/v3.2/images" \
  -H "Authorization: Bearer $MQ_TOKEN" \
  -F "file=@fuota_v2.0.0.bin" | jq
API reference:

Step 4: Create and Start a Campaign

Create and start a new campaign using the device_group_id from Step 2 and the image name from Step 3. You will get a campaign_id in the response.

Create the campaign
curl -sS -X POST "https://fuota.machineq.net/api/v3.2/campaigns" \
-H "Authorization: Bearer $MQ_TOKEN" \
-H "Content-Type: application/json" \
-d '{
  "device_group_id": "<device_group_id>",
  "image_name": "fuota_v2.0.0.bin"
}' | jq
API reference:

Note: Many campaign parameters, such as the multicast data rate (mcast_dr) and frequency (mcast_freq), can be tuned. See the create campaign API schema for the full list, and Choosing Multicast Setup Time for scheduling guidance.

Step 5: Check Campaign Status

Poll the short status endpoint to monitor the campaign as it runs.

Check the campaign status
curl -sS "https://fuota.machineq.net/api/v3.2/campaigns/short-status?campaign_id=<campaign_id>" \
  -H "Authorization: Bearer $MQ_TOKEN" | jq
API reference:

What's Next?

FUOTA API Overview Gateway Selection