Entities and State

Entities are the user-facing values and controls exposed by a device. Use them for sensor readings, relay state, status values, counters, and dashboard commands. [image:device entity list with temperature, relay, status, and command controls]

Define entities

Use an Entity object when you want a typed reference to an entity key.

// By entity key — matches the "key" field in dashboard
Entity temperature("temperature");

// By GPIO pin — matches the "gpio_pin" field in dashboard
Entity relay1(1);
Entity relay2(2);

You can also use string or int keys directly when the sketch is small.

Push state

Use pushEntity() for a single value update. This is useful for sensors, relay feedback, or any state that changes over time.

void loop() {
  fngin.loop();

  static unsigned long lastPush = 0;
  if (millis() - lastPush >= 10000) {
    lastPush = millis();
    fngin.pushEntity("temperature", "25.5");
    fngin.pushEntity(relay1, "1");
  }
}

For multiple values at once, use the batch builder.

bool sent = fngin.pushBatchEntities()
  .add("temperature", "25.5")
  .add(relay1, "1")
  .add(relay2, "0")
  .add("humidity", "80")
  .add("status", "ONLINE")
  .send();

if (sent) {
  Serial.println("Batch state sent");
}

Receive commands

Use entity callbacks to receive commands sent from Firmngin to the device. The command includes an entity key and value, so the firmware can route it to the correct GPIO or component.

Entity relay1(1);

ON_ENTITY(relay1, [](EntityCommand &cmd) {
  digitalWrite(2, cmd.value() == "1" ? HIGH : LOW);
});

For multiple entity commands, register one global entity command callback and switch by key.

fngin.on(ENTITIES, [](EntityCommand &cmd) {
  if (cmd.key() == "1") {
    digitalWrite(2, cmd.value() == "1" ? HIGH : LOW);
  }

  if (cmd.key() == "2") {
    digitalWrite(4, cmd.value() == "1" ? HIGH : LOW);
  }

  if (cmd.key() == "temperature") {
    Serial.print("Temperature: ");
    Serial.println(cmd.value());
  }
});

Request init

Call requestInit() when the firmware needs the latest device configuration after connection or reconnect.

void setup() {
  // Connect Wi-Fi first.
  fngin.begin();
  fngin.requestInit();
}

Typed callbacks

The Arduino library supports typed callback objects for common flows.

Callback type	Use it for
`EntityCommand`	Entity commands from the dashboard or automation.
`DeviceStates`	Device lifecycle and monetization state changes.
`Inits`	Initial entity, merchant, and verification configuration.
`Payments`	Pending and successful payment events.
`Verifications`	PIN display and verification result events.
`Usages`	Usage limit state.
`ActiveSession`	Device-side checks for an active paid session.

Use the typed objects instead of parsing raw payloads unless you specifically need raw metadata.

Getting started

Core concepts

Monetization

Libraries

Define entities

Push state

Receive commands

Request init

Typed callbacks

​Define entities

​Push state

​Receive commands

​Request init

​Typed callbacks

Define entities

Push state

Receive commands

Request init

Typed callbacks