Lights Management
Table of Contents
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.
{
"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"
}
]
}
// 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.
{
"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"
}
}
// 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.
{
"status": "OK",
"message": "Light updated successfully"
}
// 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.
{
"status": "OK",
"message": "Light removed successfully"
}
// 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.
{
"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"
}
]
}
]
}
]
}
]
}
// 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.
// 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();
*/