JWan Wiki

Here is the complete, chronological workflow of how your virtual POS device interacts with Home Assistant via MQTT. This order covers everything from establishing the connection to handling active data and disconnecting.

Before your app sends any data, it connects to the MQTT broker. During this initial handshake, it registers a Last Will message. This message acts as an insurance policy if your app crashes.

MQTT Configuration:

• Will Topic: pos/device/availability
• Will Payload (Plain Text): offline
• Will Retain: True

Once connected, your app must tell Home Assistant how to build the device and its 3 entities. You send a strict JSON format string to unique discovery configuration topics.

• MQTT Action: Publish to the following topics with Retain: True.

• Topic: homeassistant/sensor/pos_device/apple_qty/config
• Payload (JSON):

{"name": "Apple Total Qty Sold", "unique_id": "pos_apple_qty_001", "state_topic": "pos/apple/qty/state", "availability_topic": "pos/device/availability", "payload_available": "online", "payload_not_available": "offline", "unit_of_measurement": "units", "state_class": "measurement", "device": {"identifiers": ["unique_pos_machine_id"], "name": "Point of Sale", "model": "POS Terminal v1", "manufacturer": "Custom App"}}

• Topic: homeassistant/sensor/pos_device/apple_amount/config
• Payload (JSON):

{"name": "Apple Total Amt Sold", "unique_id": "pos_apple_amount_001", "state_topic": "pos/apple/amount/state", "availability_topic": "pos/device/availability", "payload_available": "online", "payload_not_available": "offline", "unit_of_measurement": "$", "state_class": "measurement", "device": {"identifiers": ["unique_pos_machine_id"], "name": "Point of Sale", "model": "POS Terminal v1", "manufacturer": "Custom App"}}

Because the price can be adjusted from Home Assistant, your app must immediately subscribe to the command topic specified in your slider's config.

MQTT Action: Subscribe to:

• Topic: pos/apple/price/set

At this point, Home Assistant has built the device card, but all entities are greyed out as “Unavailable”. Your app must broadcast that it is officially active.

MQTT Action: Publish with Retain: True.

• Topic: pos/device/availability
• Payload (Plain Text): online

Result: The entities wake up in the Home Assistant UI and are ready for data.

This is the day-to-day loop while your app is running. Data is exchanged using lightweight Plain Text payloads.

Your app publishes numerical changes to the state topics (Retain: True or False).

• Topic: pos/apple/qty/state → Payload: 150
• Topic: pos/apple/amount/state → Payload: 298.50
• Topic: pos/apple/price/state → Payload: 1.99

A user changes the slider to $2.50 in the HA dashboard. Home Assistant sends a message down to your subscription.

• Topic Received: pos/apple/price/set → Payload: 2.50
• Your App's Job: Accept the 2.50 internally, change the price in your local software database, and publish 2.50 back to pos/apple/price/state to confirm the update.

The MQTT broker notices your app dropped off. The broker instantly acts on the policy created in Step 1 and broadcasts the word offline to pos/device/availability.

• Result: Home Assistant immediately greys out your POS entities as “Unavailable” so users don't see frozen, inaccurate data.

If you decide to retire this project, you instruct your app (or MQTTX) to wipe the configurations out of Home Assistant's database by publishing empty messages.

• MQTT Action: Publish an empty string (“”) with Retain: True to your three Step 2 configuration topics:

homeassistant/sensor/pos_device/apple_qty/config
homeassistant/sensor/pos_device/apple_amount/config
homeassistant/number/pos_device/apple_price/config

• Result: Home Assistant completely deletes the “Point of Sale” device from your smart home.