Lights Management

Overview

Lights are the core devices in the RCAMS system that provide visual emergency notifications throughout school facilities. Each light is identified by a unique MAC address and can be assigned to a specific group within a school. This section details the API endpoints for managing lights, including listing, retrieving, updating, and deleting lights.

Note: All light management endpoints require basic authentication. The user must have appropriate permissions for the requested operations.

Light Management API Endpoints
Operation Endpoint Action Parameter
List Lights /lightlist.php N/A
Get Light /light.php get
Update Light /light.php update
Delete Light /light.php remove
Get Light Data /lightdata.php N/A

List Lights

Retrieves lights based on filtering criteria such as school ID or group ID.

POST/lightlist.php

Returns a list of lights matching the specified criteria.

Request Parameters
Parameter Type Required Description
school_id String Conditional ID of the school to filter by (required if group_id is not provided)
group_id String Conditional ID of the group to filter by (required if school_id is not provided)

Note: At least one of school_id or group_id must be provided in the request.

Response

Returns a list of lights with their details.

Example Response
{
  "status": "OK",
  "message": "Light data retrieved successfully.",
  "lights": [
    {
      "light_id": 46,
      "light_name": "j01",
      "light_topic": "rcams_topic_8145CEBD724",
      "light_mac": "8145CEBD724",
      "group_id": 1,
      "group_name": "Main Building",
      "ssid_name": "NETGEAR51",
      "ssid_password": "boldhippo192"
    },
    {
      "light_id": 26,
      "light_name": "JMLight0028",
      "light_topic": "rcams_topic_JCBD2G5D2EA2C",
      "light_mac": "JCBD2G5D2EA2C",
      "group_id": 1,
      "group_name": "Main Building",
      "ssid_name": "NETGEAR51",
      "ssid_password": "boldhippo192"
    },
    {
      "light_id": 29,
      "light_name": "JMLight0029",
      "light_topic": "rcams_topic_JCBD2G5D2EA2D",
      "light_mac": "JCBD2G5D2EA2D",
      "group_id": 1,
      "group_name": "Main Building",
      "ssid_name": "NETGEAR51",
      "ssid_password": "boldhippo192"
    }
  ]
}
Example Request (JavaScript)
// Set up the request
const jsonData = {
  "school_id": "1",
  "group_id": "1"
};

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/lightlist.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Lights:', data.lights);
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Get Light

Retrieves details for a specific light device.

POST/light.php

Returns detailed information about a specific light device.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to get
light_mac String Yes MAC address of the light to retrieve
Response

Returns the details of the specified light.

Example Response
{
  "status": "OK",
  "message": "Light found",
  "data": {
    "LightId": "26",
    "LightName": "JMLight0028",
    "Topic": "rcams_topic_JCBD2G5D2EA2C",
    "Lightmac": "JCBD2G5D2EA2C",
    "LightUser": "rcams_usr_JCBD2G5D2EA2C",
    "LightPass": "1c4d75af323e0d7f977439f4257c3edd",
    "GroupId": "1",
    "Group": "Main Building",
    "WIFI_SSID": "NETGEAR51",
    "SSID_password": "boldhippo192",
    "ServerName": "fb9ebee9.ala.us-east-1.emqxsl.com",
    "ServerPort": "8883"
  }
}
Example Request (JavaScript)
// Set up the request
const jsonData = {
  "action": "get",
  "light_mac": "JCBD2G5D2EA2C"
};

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/light.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Light details:', data.data);
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Update Light

Updates an existing light device's properties.

POST/light.php

Updates the details of an existing light device.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to update
light_mac String Yes MAC address of the light to update
light_name String Yes New name for the light
group_id String Yes New group ID for the light
Response

Returns confirmation that the light was updated.

Example Response
{
  "status": "OK",
  "message": "Light updated successfully"
}
Example Request (JavaScript)
// Set up the request
const jsonData = {
  "action": "update",
  "light_mac": "JCBD2G5D2EA2C",
  "light_name": "Classroom 101",
  "group_id": "2"
};

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/light.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Light updated successfully');
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Delete Light

Deactivates a light in the system.

Warning: Deleting a light will remove it from the system and it will no longer receive commands. This action cannot be undone.

POST/light.php

Deletes a light from the system.

Request Parameters
Parameter Type Required Description
action String Yes Must be set to remove
light_mac String Yes MAC address of the light to delete
Response

Returns confirmation that the light was deleted.

Example Response
{
  "status": "OK",
  "message": "Light removed successfully"
}
Example Request (JavaScript)
// Set up the request
const jsonData = {
  "action": "remove",
  "light_mac": "JCBD2G5D2EA2C"
};

// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/light.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  },
  body: jsonData
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Light removed successfully');
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Light Data

Retrieves comprehensive light data including districts, schools, groups, and WiFi settings.

POST/lightdata.php

Returns detailed information about all lights the user has access to, organized in a hierarchical structure.

Request Parameters
Parameter Type Required Description
Response

Returns a hierarchical structure of all lights the user has access to, organized by district, school, and group.

Example Response
{
  "status": "OK",
  "districts": [
    {
      "district_id": 101,
      "district_name": "North County School District",
      "schools": [
        {
          "school_id": 1002,
          "school_name": "Washington Elementary",
          "school_address": "456 Learning Blvd",
          "light": [
            {
              "light_id": 1,
              "light_name": "light001",
              "light_topic": "testtopic1",
              "light_mac": "1B:3C:1A:3F:7D:1B",
              "group": [
                {
                  "group_id": 5010,
                  "group_name": "Science Department"
                }
              ],
              "wifi_ssid": [
                {
                  "ssid_id": 8002,
                  "ssid_name": "LHS-THREE"
                }
              ],
              "server": [
                {
                  "server_id": 7001,
                  "server_name": "ALTUS Server",
                  "url": "https://www.lhs.edu",
                  "port": "8883",
                  "username": "scienceadmin",
                  "password": "sciencepassword",
                  "topic": "testtopic"
                }
              ]
            },
            {
              "light_id": 2,
              "light_name": "light002",
              "light_topic": "testtopic1",
              "light_mac": "1B:3C:1A:3F:7D:1C",
              "group": [
                {
                  "group_id": 5002,
                  "group_name": "Faculty Staff"
                }
              ],
              "wifi_ssid": [
                {
                  "ssid_id": 8001,
                  "ssid_name": "LHS-STAFF3"
                }
              ],
              "server": [
                {
                  "server_id": 5019,
                  "server_name": "New Server",
                  "url": "https://www.lhs.edu",
                  "port": "8883",
                  "username": "scienceadmin",
                  "password": "sciencepassword",
                  "topic": "testtopic"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}
Example Request (JavaScript)
// Set up the request
// Make the API call
fetch('https://rcamsapi.spheronomics.com/api/v2/lightdata.php', {
  method: 'POST',
  headers: {
    'Authorization': 'Basic ' + btoa('api_username:api_password')
  }
})
.then(response => response.json())
.then(data => {
  if (data.status === 'OK') {
    console.log('Light data:', data.districts);
    
    // Process the hierarchical data
    data.districts.forEach(district => {
      console.log(`District: ${district.district_name}`);
      
      district.schools.forEach(school => {
        console.log(`  School: ${school.school_name}`);
        
        school.light.forEach(light => {
          console.log(`    Light: ${light.light_name} (${light.light_mac})`);
          console.log(`      Group: ${light.group[0].group_name}`);
          console.log(`      WiFi: ${light.wifi_ssid[0].ssid_name}`);
          console.log(`      Server: ${light.server[0].server_name}`);
        });
      });
    });
  } else {
    console.error('Error:', data.message);
  }
})
.catch(error => console.error('Error:', error));

Code Examples

Light Management Example

The following example demonstrates a complete flow for light management, including listing, retrieving, updating, and deleting lights.

Complete Light Management Example (JavaScript)
// Helper function for API requests
async function makeApiRequest(endpoint, params) {
  // API credentials - replace with actual values
  const apiUsername = 'your_api_username';
  const apiPassword = 'your_api_password';
  
  // Create form data from params
  const json = {};
  for (const [key, value] of Object.entries(params)) {
    json[key] = value;
  }
  const jsonString = JSON.stringify(json);
  
  try {
    const response = await fetch(`https://rcamsapi.spheronomics.com/api/v2/${endpoint}`, {
      method: 'POST',
      headers: {
        'Authorization': 'Basic ' + btoa(`${apiUsername}:${apiPassword}`)
      },
      body: jsonString
    });
    
    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

// Example usage - Light Management
async function lightManagementExample( schoolId, groupId) {
  try {
    // 1. List all lights in the school and group
    console.log(`Listing all lights in school ${schoolId}, group ${groupId}...`);
    const listResponse = await makeApiRequest('lightlist.php', {
      school_id: schoolId,
      group_id: groupId
    });
    
    if (listResponse.status === 'OK' && listResponse.lights && listResponse.lights.length > 0) {
      console.log(`Found ${listResponse.lights.length} lights:`, listResponse.lights);
      
      // 2. Get details of the first light
      const firstLight = listResponse.lights[0];
      const lightMac = firstLight.light_mac;
      
      console.log(`Getting details for light: ${lightMac}...`);
      const getResponse = await makeApiRequest('light.php', {
        action: 'get',
        light_mac: lightMac
      });
      
      if (getResponse.status === 'OK') {
        console.log('Light details:', getResponse.data);
        
        // 3. Update the light
        console.log('Updating light...');
        const updateResponse = await makeApiRequest('light.php', {
          action: 'update',
          light_mac: lightMac,
          light_name: `${firstLight.light_name}_Updated`,
          group_id: groupId
        });
        
        console.log('Update result:', updateResponse.message);
        
        // 4. Get the updated light details
        console.log('Getting updated light details...');
        const updatedResponse = await makeApiRequest('light.php', {
          action: 'get',
          light_mac: lightMac
        });
        
        console.log('Updated light details:', updatedResponse.data);
        
        // 5. Delete the light (commented out for safety)
        // Uncomment to actually delete the light
        /*
        console.log('Deleting light...');
        const deleteResponse = await makeApiRequest('light.php', {
          action: 'remove',
          light_mac: lightMac
        });
        
        console.log('Delete result:', deleteResponse.message);
        */
      }
      
      // 6. Get comprehensive light data
      console.log('Getting comprehensive light data...');
      const lightDataResponse = await makeApiRequest('lightdata.php', {
      });
      
      console.log('Light data overview:', lightDataResponse.districts.map(d => d.district_name));
    } else {
      console.log('No lights found or error occurred:', listResponse.message);
    }
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

// Run the example (you would need a valid school ID, and group ID)
/*
async function runExample() {
  const loginResponse = await makeApiRequest('login.php', {
    user: 'user@example.com',
    pass: 'password123'
  });
  
  if (loginResponse.status === 'OK') {
    await lightManagementExample('1', '1'); // Replace with actual school and group IDs
  } else {
    console.error('Login failed:', loginResponse.message);
  }
}

runExample();
*/