lighting-controller/COLOR_API_QUICK_REF.md

Color Palette API - Quick Reference Card

🎯 Endpoints

Method	URL	Purpose
GET	http://10.42.0.1:8765/api/color-palette	Get current palette
POST	http://10.42.0.1:8765/api/color-palette	Update palette/selection
PUT	http://10.42.0.1:8765/api/color-palette	Same as POST

Backup: Same endpoints available on port 8766

---

📦 Data Structure

{
  palette: [
    {r: 255, g: 0, b: 0},    // Slot 0
    {r: 0, g: 255, b: 0},    // Slot 1
    {r: 0, g: 0, b: 255},    // Slot 2
    {r: 255, g: 255, b: 0},  // Slot 3
    {r: 255, g: 0, b: 255},  // Slot 4
    {r: 0, g: 255, b: 255},  // Slot 5
    {r: 255, g: 128, b: 0},  // Slot 6
    {r: 255, g: 255, b: 255} // Slot 7
  ],
  selected_indices: [0, 1]   // Active colors
                             // [0] = Primary RGB for patterns
                             // [1] = Reserved for future use
}

---

💻 Copy-Paste Code

Get Palette

const res = await fetch('http://10.42.0.1:8765/api/color-palette');
const {palette, selected_indices} = await res.json();

Update Color (e.g., slot 3 to purple)

const current = await fetch('http://10.42.0.1:8765/api/color-palette')
  .then(r => r.json());

const newPalette = [...current.palette];
newPalette[3] = {r: 128, g: 0, b: 128};

await fetch('http://10.42.0.1:8765/api/color-palette', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({palette: newPalette})
});

Select Colors (e.g., slots 2 and 5)

await fetch('http://10.42.0.1:8765/api/color-palette', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({selected_indices: [2, 5]})
});

---

🛠️ Helper Functions

RGB ↔ Hex Conversion

const rgbToHex = ({r, g, b}) => 
  '#' + [r, g, b].map(x => x.toString(16).padStart(2, '0')).join('');

const hexToRgb = (hex) => {
  const result = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(hex);
  return result ? {
    r: parseInt(result[1], 16),
    g: parseInt(result[2], 16),
    b: parseInt(result[3], 16)
  } : null;
};

---

✅ Validation Rules

• 8 colors in palette (exactly)
• RGB values 0-255 (integers)
• 2 selected indices (exactly)
• Indices 0-7 (valid range)

---

🧪 Test

# Get
curl http://10.42.0.1:8765/api/color-palette | jq

# Update selection
curl -X POST http://10.42.0.1:8765/api/color-palette \
  -H "Content-Type: application/json" \
  -d '{"selected_indices": [0, 2]}'

# Run full test suite
./test_color_api.sh 10.42.0.1

---

📝 Notes

• First selected color (index 0) is used as the primary RGB for LED patterns
• Changes auto-save to lighting_config.json
• Invalid data is ignored (not rejected)
• Validate client-side before sending
• WebSocket is at ws://10.42.0.1:8765/ws (different path)

---

📚 Full Docs

See COLOR_PALETTE_API.md for complete documentation