Hardware WebSocket Communication Module Documentation

WebSocket Endpoint

• URL: wss://api.duckycart.me:8000/ws/hardware/cart
• Protocol: WebSocket
• Description: Real-time communication channel for hardware cart clients.

---

Server-to-Hardware Messages

1. Session Start Command

Triggered When: QR code is scanned and session is successfully created

Message Format:

{
  "type": "start_session",
  "data": 456
}

Sent From:

• Function: create_session()
• Timing: After session record is saved to database and cart status updated to 'in_use'

---

2. Payment Created Command

Triggered When: Payment is successfully generated and saved to database

Message Format:

{
  "type": "payment_created", 
  "data": 456
}

Sent From:

• Timing: After payment record is created and before client notification

---

3. Session End Command

Triggered When: Session is finished after successful payment completion

Message Format:

{
  "type": "end_session",
  "data": 456
}

Sent From:

• Timing: After session is deactivated, cart status changed to 'available', and analytics logged

---

Message Delivery Flow

Session Lifecycle Messages

1. QR Scan → start_session command sent
2. Shopping Period → No WebSocket messages
3. Payment Creation → payment_created command sent
4. Payment Completion → end_session command sent

---

Message Timing

start_session

• Before: Cart status = 'available'
• Trigger: QR code validation successful
• After: Cart status = 'in_use', Session created, Message sent

payment_created

• Before: Shopping complete, payment request initiated
• Trigger: Payment record saved successfully
• After: Payment URL generated, Hardware notified

end_session

• Before: Payment processed successfully
• Trigger: finish_session() called
• After: Session deactivated, Cart available, Analytics logged

---

Hardware Expected Actions

On start_session

Hardware should initialize shopping mode (display activation, scanner ready, etc.)

On payment_created

Hardware should indicate payment is ready (show payment status, guide user to payment)

On end_session

Hardware should return to idle state (cleanup, thank you message, reset systems)

---

WebSocket Connection Requirements

Connection URL

wss://api.duckycart.me:8000/ws/hardware/cart

Message Format

• Protocol: JSON over WebSocket
• Encoding: UTF-8
• Structure: All messages contain type (command) and data (session_id) fields

Hardware Client Setup

Hardware clients should:

1. Connect to WebSocket endpoint
2. Listen for incoming JSON messages
3. Parse type field to determine action
4. Use data field to get session_id for tracking
5. Register with specific cart_id for message routing