Control device development

To register as a developer of control devices:

1. Sign in to your Realer account.
2. Click at the top right of any Realer page and select Account.
3. Click on Register as control device developer.
   If you are already registered as developer, you will see Control device developer account.
4. Provide your developer account details e.g. business name, logo, and website.
5. Click Register as developer.

To get control device API keys:

1. Go to your developer account page on Realer.
   You need to register as a control device developer.
2. From your developer account page, click New developer license.
3. Choose the subscription plan for the control device that you want to develop and click the corresponding button with the price.
4. Follow the on-screen instructions to make the payment.

After checkout, Realer redirects you to the control device page containing the generated API keys. Keep the client_id and client_secret secure; firmware uses them at the OAuth token endpoint to obtain access tokens for device API calls.

Plan the integration first, then build firmware against the Realer API documentation. API Docs define the exact OAuth client-credentials authentication, runtime bootstrap, catalog, desired-state, feed-data, MQTT payload, field, and response-code contracts.

Use the integration planning guide to confirm the runtime path: HTTPS polling or MQTT broker messaging over TLS. Then use the API Docs getting started page when you are ready to implement.

Before writing firmware, decide what the device physically controls or observes, how it connects to the Internet, which Realer control-device record it belongs to, and which runtime capability it will use.

• Create or select the control-device record and get API keys for firmware provisioning.
• Confirm the runtime path assigned to the device. A device uses one runtime path: HTTPS polling or MQTT broker messaging over TLS. Use the API Docs runtime page for the exact split.
• Plan OAuth token handling early. The firmware authenticates as the device through OAuth client credentials, then reads the runtime bootstrap descriptor before protected API work.

The integration planning guide covers the decision path. Use the API Docs getting started page when you need exact implementation references.

Deployment intent tells Realer how a control device is meant to be used before setup additions, updates, or retirements start.

Use this checklist when you are unsure:

• If the device is intended to move between resources or customers, choose standalone reusable.
• If removing the device would change the fixed asset or product it belongs to, choose integrated fixed-device.
• If the real-world use changes later, Realer may require review or reclassification instead of silently changing the classification.

Deployment intent is classification only. It does not grant resource control, Technical Support, Operational Support, firmware access, credentials, secrets, diagnostics, billing, dashboard access, or marketplace approval.

After choosing the intent, return to setup changes. Before connecting live equipment, review firmware safety testing.

Design the device contract before coding the firmware loop. Decide which outputs are commands, which inputs are sensors, how Realer desired-state requests should be applied, and which values the device must report back.

• Use runtime bootstrap at startup and the device catalog API Docs to understand how Realer represents active command and sensor setup.
• Use feed-data API Docs to distinguish command state reports from sensor readings.
• Choose meaningful measurement units and quantity contexts for numeric values.
• Keep UI text separate from firmware identifiers: resource and dashboard rows use row labels, while a sensor description is extra UI detail. Firmware should rely on technical catalog fields such as kind, quantity context, measurement unit, and pin or port.

Keep command, sensor, desired-state, and feed-data design at the guide level. Use field semantics for retry, ordering, correlation, expiry, and result-handling rules.

Use setup changes when a control device needs actuator or sensor setup added, updated, or retired. A setup change is reviewed before it becomes active setup.

• A control device owner or admin starts from the control device page, opens Control device setup changes, chooses the available action, explains the reason, and submits the setup change package.
• A developer can propose only the setup changes their current role or Technical Support access allows. A control device owner/admin, or bounded Realer staff review when required, accepts setup changes before they apply. Support chat history is useful evidence, but it is not authority by itself.
• Realer checks the current control device, selected setup, device type, plan limits, and Technical Support access again before a submitted package can be accepted by an authorized owner/admin or staff reviewer.
• An accepted add creates control-device setup only. Updating changes only the supported setup fields, and Retire setup removes selected setup from active setup without deleting its history.

Setup changes do not grant resource control, command writes, telemetry access, API secrets, billing access, dashboard membership, firmware updates, marketplace support, or permanent deletion (hard delete). Using new setup on a resource requires separate resource admin approval.

If Realer asks for deployment intent first, use the deployment intent guide to choose between standalone reusable and integrated fixed-device.

Before proposing setup, first design the commands, measurements, and feed data the device should expose.

Use an assisted setup correction when the latest accepted exact setup update contains a supported field value that should be corrected. Realer derives a new setup change package from accepted evidence and current setup; it does not edit the accepted history.

To prepare the correction:

1. Open the control device's setup changes and package history. Find the latest accepted update for the exact actuator or sensor setup, then choose Review assisted correction.
2. Review the current and proposed corrected values. A single update produces one exact target. An accepted multi-item update produces its complete original exact set; you cannot select a subset.
3. Explain why the update should be corrected and prepare the new package. Preparing the package records a proposal; it does not change active setup.
4. An authorized reviewer accepts the package after Realer rechecks every target and field. A multi-item correction is atomic: if any item fails revalidation, none of its items are applied.

Who can prepare and accept the package:

• For a standalone reusable device, a control device owner or control device admin can prepare and accept it through the public setup changes page. If the same person is also a developer, acceptance still uses control device admin authority.
• For a standalone reusable device, a developer-only user needs a current Technical Support setup update grant for that exact setup (setup_update) to prepare the proposal. That grant does not allow acceptance; a control device owner or control device admin must accept it.
• For an integrated fixed-device, acceptance uses the existing Realer staff-only review page. Staff review is not a general public control device admin fallback.

Realer blocks assisted correction when it can no longer prove the exact correction safely, including when:

• the source is no longer the latest accepted update for every exact target, or a target is no longer active;
• current values no longer match the accepted post-update values, or target structure such as identity, kind, pin or port, lifecycle state, or non-correctable value semantics changed;
• another open package that can still be acted on already covers an exact target, or current authority, Technical Support access, or deployment classification no longer allows the correction.

Assisted correction changes only supported update fields. It is not a snapshot restore or structural rollback, does not reverse setup additions or retirements, and does not change firmware, hardware, resource authority or state, live telemetry, or send a command. Snapshots and history remain evidence only.

Use the setup changes guide for the normal package workflow. Before applying setup around live equipment, review firmware safety testing.

Test firmware in a controlled environment before connecting it to live equipment or exposing it to other users. A Realer control device can affect physical actuators, sensors, and safety-critical systems.

• Keep API keys out of public repositories, logs, client-side code, and shared screenshots.
• Use isolated hardware, simulated loads, or disabled outputs when validating command handling and feed-data reporting.
• Verify local fallback behavior for lost Internet, expired credentials, rejected API responses, and broker disconnects before production use.

For the safety baseline, read developer responsibility before live testing.

Firmware should treat Realer as a cloud control plane that can be temporarily unavailable, reject invalid data, or stop accepting cloud operations when the subscription or credentials are no longer active.

• For rejected HTTPS results, use response codes and field semantics to decide whether to retry, ignore, reconcile, or enter local safe behavior.
• For authentication, bootstrap, and MQTT runtime failures, renew OAuth tokens and short-lived MQTT credentials through the flows documented in authentication and MQTT flow.
• For subscription or entitlement loss, expect cloud API access to stop and follow the subscription ending guide.

The API failure handling guide covers firmware behavior. Use API Docs for exact request, payload, and response contracts.

The measurement-unit reference helps when a numeric command or sensor value needs the right engineering unit.

The quantity-context reference helps when a numeric value needs the right physical or domain meaning.