Device Onboarding & Lifecycle

Device provisioning, organization, and lifecycle management is where most integrations spend the bulk of their time. This guide walks through LoRaWAN basics, device provisioning, and lifecycle operations.

Before You Begin

You need:

• An MQcentral account with CRUD permissions for Device Administration. See Roles for details.
• At least one gateway registered and connected to the MachineQ network. See Gateway & Network Provisioning.
• The device's DevEUI, ApplicationEUI (JoinEUI/AppEUI), and ApplicationKey. These are printed on the device or supplied by the manufacturer.
• $MQ_TOKEN exported from the authentication step. See Authentication & API Access.

LoRaWAN Concepts You Need

Before adding a device, three identifiers and one secret matter:

• DevEUI: a 64-bit unique identifier for the device. Assigned by the chip manufacturer and never changes.
• ApplicationEUI (also called JoinEUI or AppEUI): a 64-bit identifier for the application or owner. Provisioned alongside the DevEUI.
• ApplicationKey: a 128-bit secret that derives session keys during the join procedure. Treated like a password.
• DevAddr: a 32-bit network-assigned address. Assigned by the network server after a successful OTAA join, not provided manually.

These come from the device manufacturer. All MachineQ devices come pre-provisioned at the time of fulfillment. For third-party devices, they are typically printed on the device or provided separately.

OTAA vs. ABP

LoRaWAN supports two activation methods:

1. OTAA (Over-the-Air Activation): the device performs a join procedure on power-up, deriving session keys dynamically. This is the modern, recommended path. Use it unless you have a specific reason not to.

2. ABP (Activation by Personalization): session keys are pre-provisioned on the device. Faster on first power-up but harder to manage at scale (no rejoin, no re-keying). Avoid unless you're constrained by hardware.

Throughout the rest of this guide, examples assume OTAA.

Provisioning a Single Device

Step 1: Look Up Required Profile IDs

Device creation requires a Service Profile ID and a Device Profile ID. Both are pre-configured in MQcentral; fetch the available options for your account:

curl -sS -H "Authorization: Bearer $MQ_TOKEN" \
  "https://api.machineq.net/v1/serviceprofiles" | jq

curl -sS -H "Authorization: Bearer $MQ_TOKEN" \
  "https://api.machineq.net/v1/deviceprofiles" | jq

Save the Id value from each response; both are required in the next step.

Step 2: Create the Device

MachineQ Devices: If you are provisioning an official MachineQ device, please contact MachineQ Support instead. All MachineQ devices are typically preprovisioned by our support team. The steps below are intended for provisioning third-party LoRaWAN devices.

curl -sS -X POST https://api.machineq.net/v1/devices \
  -H "Authorization: Bearer $MQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "DevEUI": "<dev_eui>",
    "ApplicationEUI": "<application_eui>",
    "ApplicationKey": "<application_key>",
    "Name": "quickstart-flex-01",
    "ActivationType": "OTAA",
    "ServiceProfile": "<service_profile_id>",
    "DeviceProfile": "<device_profile_id>"
  }' | jq

The response includes an Id for the newly created device. The device becomes active on its first successful join. Export the DevEUI for subsequent steps:

export MQ_DEV_EUI="<dev_eui>"

ABP-specific fields: For ABP activation, omit ApplicationEUI and ApplicationKey and instead provide DevAddr, NetworkSkey, and ApplicationSKey.

LoRaWAN 1.1: If the device uses LoRaWAN 1.1, also include NetworkKey alongside ApplicationKey.

Device Profiles

A device profile captures the hardware capabilities of a device type. Profiles are pre-configured in MQcentral; select the appropriate profile at provisioning time rather than creating one.

Each profile returns an Id and Name. Pass the Id as DeviceProfile when creating a device.

Class A vs. Class C

The most consequential aspect of device capability is the LoRaWAN class:

• Class A: the device sleeps until it sends an uplink, then briefly opens two downlink windows. Lowest power consumption and longest battery life. Best suited for sensors.
• Class C: the device's receiver stays on except while transmitting. Highest power consumption, but downlinks can arrive at any time. Best suited for actuators and Firmware Update Over The Air (FUOTA) targets.
• Class B: the device opens scheduled receive windows synchronized via beacon. Moderate power consumption, sitting between Class A and Class C. Best suited for devices that need periodic downlinks without staying always on. Rarely used in practice; Class C is usually the right answer if you need anything beyond Class A.

This choice directly affects battery life, downlink timing, and gateway air-time usage, and influences nearly every operational decision that follows.

Device Groups

Once you have more than a few hundred devices, organization becomes the limiting factor. Device groups are named collections of devices useful for fleet operations and bulk targeting.

List existing groups:

curl -sS -H "Authorization: Bearer $MQ_TOKEN" \
  "https://api.machineq.net/v1/groups/devices" | jq

Create a new group:

curl -sS -X POST https://api.machineq.net/v1/groups/devices \
  -H "Authorization: Bearer $MQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "warehouse-east-sensors",
    "DeviceList": [
      "2CC407FFFE500C3F",
      "2CC407FFFE500C40"
    ]
  }' | jq

DeviceList is an array of DevEUI strings. Name is the only required field; DeviceList can be populated at creation or updated later.

Managing Devices

Updating a Device

Use PATCH to update individual fields without affecting the rest:

curl -sS -X PATCH https://api.machineq.net/v1/devices/$MQ_DEV_EUI \
  -H "Authorization: Bearer $MQ_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Name": "warehouse-temp-sensor-001-renamed",
    "DevEUI": "2CC407FFFE500C3F"
  }' | jq

Patchable fields: Name, DevEUI, ServiceProfile, DeviceProfile, DecoderType, OutputProfile, PrivateData, RemoveOutputProfile. Both Name and DevEUI are required even for a partial update.

Use PUT for a full replacement; the same fields apply, but ServiceProfile and DeviceProfile are also required.

Deleting a Device

curl -sS -X DELETE https://api.machineq.net/v1/devices/$MQ_DEV_EUI \
  -H "Authorization: Bearer $MQ_TOKEN" | jq

Warning: Deletion is permanent and cannot be undone. If you need to preserve data continuity across a hardware replacement, provision the replacement device under its own DevEUI and retire the old one rather than deleting it.

What's Next?

• Data Delivery: Output Profiles: Configure output profiles to route device data to downstream systems once devices are provisioned.
• Working with Device Data: Query uplinks, assign payload decoders, and send downlinks to your devices.