HTTP_API_EXAMPLES.md

Comprehensive HTTP API Testing Guide

Environment Setup

# Set your device IP and credentials
DEVICE_IP="192.168.1.100"
USER="admin"
PASS="msgboard"

Message API Tests (Existing Functionality)

GET /arg Endpoint - URL Parameters

1. Basic Message:

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Hello World!"

2. Full Parameters:

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Testing all parameters!" \
  --data-urlencode "REP=5" \
  --data-urlencode "BUZ=3" \
  --data-urlencode "DEL=30" \
  --data-urlencode "BRI=10" \
  --data-urlencode "ASC=1" \
  --data-urlencode "ALERTCHIRP=Gentle Dawn"

3. Infinite Repeat (REP=0):

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Scrolling forever!" \
  --data-urlencode "REP=0"

4. Silent Message (no buzzer):

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Silent message" \
  --data-urlencode "BUZ=0"

5. Fast Scroll:

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Speed test!" \
  --data-urlencode "DEL=10"

6. Dim Display:

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Dim mode" \
  --data-urlencode "BRI=0"

7. Bright Display:

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Max brightness!" \
  --data-urlencode "BRI=15"

8. Stop/Clear Current Message:

curl --user admin:msgboard -X GET "http://${DEVICE_IP}/arg"

8b. Force Repetitions — block new messages until done:

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Priority alert - do not interrupt!" \
  --data-urlencode "REP=5" \
  --data-urlencode "FORCEREP=true"

9. UTF-8 Special Characters:

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Símbolos: €£¥©®™°±" \
  --data-urlencode "ASC=1"

10. Custom Alert Chirp:

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Custom sound!" \
  --data-urlencode "ALERTCHIRP=Doorbell"

11. Stop/Clear Current Message:

curl --user admin:msgboard -X GET "http://${DEVICE_IP}/arg"

12. UTF-8 Special Characters (with custom chirp):

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/arg" \
  --data-urlencode "MSG=Símbolos: €£¥©®™°±" \
  --data-urlencode "ASC=1" \
  --data-urlencode "ALERTCHIRP=Cheerful"

POST /api Endpoint - JSON Messages

13. Basic JSON Message:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":"JSON test message"}'

14. Full JSON Parameters:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{
    "MSG": "Complete JSON test",
    "REP": 3,
    "BUZ": 5,
    "DEL": 25,
    "BRI": 12,
    "ASC": 1,
    "ALERTCHIRP": "Gentle Dawn"
  }'

14b. Force Repetitions via JSON:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{
    "MSG": "Priority alert - do not interrupt!",
    "REP": 5,
    "BUZ": 3,
    "FORCEREP": true
  }'

15. Minimal JSON (defaults):

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":"Quick alert"}'

16. General Settings Control (POST):

# Toggle Global Buzzer
curl --user admin:msgboard -X POST "http://${DEVICE_IP}/savegeneral" \
  -d "BuzzerEnable=off"

# Toggle Brightness Override
curl --user admin:msgboard -X POST "http://${DEVICE_IP}/savegeneral" \
  -d "BrightnessOverrideEnable=on" \
  -d "BrightnessOverrideValue=12"

17. JSON Stop Message:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":""}'

18. JSON with Special Characters:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":"Quote test: \"Hello\" and backslash: \\test","REP":2}'

19. JSON with Custom Chirp:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":"Doorbell alert!","ALERTCHIRP":"Doorbell"}'

Defaults Management

20a. Set Custom Default: Types: REP (Repeat), BUZ (Buzzer), DEL (Delay), BRI (Brightness), ALERTCHIRP (Alert Chirp)

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/setdefault" \
  --data-urlencode "type=REP" \
  --data-urlencode "value=5"

20b. Set Custom Alert Chirp Default:

curl --user admin:msgboard -X GET -G "http://${DEVICE_IP}/setdefault" \
  --data-urlencode "type=ALERTCHIRP" \
  --data-urlencode "value=Gentle Dawn"

20c. Reset All Defaults:

curl --user admin:msgboard -X GET "http://${DEVICE_IP}/resetdefaults"

Timer API Tests (New Functionality)

POST /api/timer Endpoint - Timer Configuration & Control

21a. Enable Timer (Countdown):

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/timer" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "mode": "TIMER",
    "durationSeconds": 300,
    "brightness": 10
  }'

21b. Enable Stopwatch:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/timer" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "mode": "STOPWATCH",
    "brightness": 8
  }'

21c. Start Timer/Stopwatch:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/timer/start" -d ''

21d. Pause Timer/Stopwatch:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/timer/pause" -d ''

21e. Stop/Reset Timer:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/timer/reset" -d ''

21f. Configure Timer Defaults (Auto-Repeat & Alerts):

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/timer" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "autoRepeat": true,
    "alertBuzzer": true,
    "alertBuzzerCount": 5
  }'

Clock API Tests (New Functionality)

POST /api/clock Endpoint - Clock Configuration

22. Enable Clock with Brightness:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "brightness": 10
  }'

23. Disable Clock:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

24. Set Brightness Only:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"brightness": 5}'

25. Change NTP Server:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"ntpServer": "pool.ntp.org"}'

26. Set Timezone (POSIX String):

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"tzString": "EST5EDT,M3.2.0,M11.1.0"}'

27. Set Timezone (UTC):

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"tzString": "UTC0"}'

28. Set Transition Effect:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "FADE"}'

29. Test All Transition Effects:

FADE

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "FADE"}'

WIPE

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "WIPE"}'

DISSOLVE

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "DISSOLVE"}'

BLINDS

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "BLINDS"}'

GROW

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "GROW"}'

SCROLL

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "SCROLL"}'

SCAN

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "SCAN"}'

OPENING

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "OPENING"}'

CLOSING

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "CLOSING"}'

PRINT

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "PRINT"}'

30. Set Transition Delay (speed):

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionDelayMs": 500}'

31. Enable Random Transitions:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"randomizeTransition": true}'

32. Disable Random Transitions:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"randomizeTransition": false}'

33. Set NTP Resync Interval:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"resyncIntervalHours": 12}'

34. Complete Clock Setup (all parameters):

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "brightness": 8,
    "ntpServer": "time.google.com",
    "tzString": "EST5EDT,M3.2.0,M11.1.0",
    "transitionDelayMs": 300,
    "transitionEffect": "FADE",
    "randomizeTransition": false,
    "resyncIntervalHours": 6
  }'

Validation Error Tests (Should Return 400)

35. Invalid Brightness (too high):

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"brightness": 99}'

36. Invalid GMT Offset:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"gmtOffsetSeconds": 999999}'

37. Invalid Transition Effect:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionEffect": "INVALID"}'

38. Invalid DST Offset:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"dstOffsetSeconds": 1800}'

39. Invalid Resync Interval:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"resyncIntervalHours": 0}'

40. Invalid Transition Delay:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"transitionDelayMs": 99999}'

Configuration Management Tests

41. Export Configuration:

curl --user admin:msgboard "http://${DEVICE_IP}/exportconfig" > config_backup.json

42. Import Configuration:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/importconfig" \
  -H "Content-Type: application/json" \
  -d @config_backup.json

Boolean Format Tests (Clock API)

The parseBoolean() helper accepts multiple formats:

43. Enable with string "on":

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"enabled": "on"}'

44. Enable with string "true":

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"enabled": "true"}'

45. Enable with integer 1:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"enabled": 1}'

46. Randomize with string "off":

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"randomizeTransition": "off"}'

Common Use Case Scenarios

47. Morning Routine - Enable clock at 6 AM:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "brightness": 5}'

48. Evening Routine - Show message before bed:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":"Good night!","REP":2,"BRI":3}'

49. Doorbell Alert:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":"Visitor at door!","REP":3,"BUZ":10,"BRI":15,"ALERTCHIRP":"Doorbell"}'

50. Weather Update:

curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":"Today: Sunny 75°F","REP":5,"DEL":40}'

51. Switch from Clock to Message:

# Disable clock
curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'

# Show message
curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":"Important notification!"}'

52. Switch from Message back to Clock:

# Clear message
curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":""}'

# Enable clock
curl --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

Quick Test Script (Linux/Mac/Git Bash)

Save this as test_api.sh:

#!/bin/bash
DEVICE_IP="192.168.1.100"

echo "Testing Message API..."
curl -s --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
  -H "Content-Type: application/json" \
  -d '{"MSG":"API Test 1/3"}'
sleep 3

echo "Testing Clock Enable..."
curl -s --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"brightness":10}'
sleep 5

echo "Testing Clock Disable..."
curl -s --user admin:msgboard -X POST "http://${DEVICE_IP}/api/clock" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'
sleep 2

echo "Done!"

Force Repetitions (FORCEREP)

FORCEREP is a per-message flag that locks the display for the full repeat cycle of the current message, causing any new incoming message to be rejected with 409 Conflict until all repetitions have completed.

Default: false — omitting the parameter never blocks.

Accepted values: true, 1, on (case-insensitive). Anything else is treated as false.

How it works

When FORCEREP=true is included with a message:

1. The message displays normally and runs through all REP repetitions.
2. Any new message received via HTTP GET, HTTP POST, or MQTT JSON while the repetitions are still in progress is rejected.
3. Once all repetitions complete and curMessage is cleared, the lock is released automatically — the next message will be accepted normally.

The lock is entirely runtime state. It resets to false on device reboot, and any message sent without FORCEREP=true clears the flag for the next sender.

HTTP response codes

Code	Meaning
204 No Content	Message accepted and queued
403 Forbidden	Rejected — sleep mode is active
409 Conflict	Rejected — forced repetition in progress
401 Unauthorized	Bad credentials

Detecting board availability from a sender

Use the 409 response to know the board is busy and retry later:

#!/bin/bash
DEVICE_IP="192.168.1.100"
MAX_RETRIES=10
RETRY_DELAY=5

for i in $(seq 1 $MAX_RETRIES); do
  HTTP_CODE=$(curl -s -o /dev/null -w "%{http_code}" \
    --user admin:msgboard -X POST "http://${DEVICE_IP}/api" \
    -H "Content-Type: application/json" \
    -d '{"MSG":"New alert","REP":3}')

  if [ "$HTTP_CODE" = "204" ]; then
    echo "Message accepted."
    break
  elif [ "$HTTP_CODE" = "409" ]; then
    echo "Attempt $i: Board busy (forced repetition). Retrying in ${RETRY_DELAY}s..."
    sleep $RETRY_DELAY
  elif [ "$HTTP_CODE" = "403" ]; then
    echo "Board in sleep mode. Aborting."
    break
  else
    echo "Unexpected response: $HTTP_CODE"
    break
  fi
done

Use cases

• Critical alerts — fire alarm, security event, or urgent notification that must not be overridden mid-display.
• Queuing systems — a sender can detect 409 and back off rather than silently dropping its message.
• Kiosk / public display — ensure a sponsored or scheduled message runs its full cycle before the next one takes over.

Interaction with other blocking features

Condition	Response	Priority
Sleep mode active	403	Checked first
Forced repetition in progress	409	Checked second
Normal operation	204	Message accepted

Sleep mode is evaluated before the force-rep guard, so a sleep-mode block always wins regardless of FORCEREP.

---

Expected Responses

Success (204 No Content):

(empty body)

Authentication Error (401):

HTTP Basic: Access denied.

Sleep Mode Active (403):

Sleep mode active

or (JSON endpoint):

{"error":"Sleep mode active"}

Forced Repetition In Progress (409):

Forced repetition in progress

or (JSON endpoint):

{"error":"Forced repetition in progress"}

Validation Error (400):

{"error":"Brightness must be 0-15"}
{"error":"Invalid transition effect"}
{"error":"GMT offset out of range"}

Invalid JSON (400):

{"error":"Invalid JSON"}

This comprehensive guide covers all existing message API functionality plus the clock API features implemented!