Getting Started with the Smartylighting Streetlights API

Welcome, API developers! This guide will help you quickly understand and integrate with the Smartylighting Streetlights API. Our goal is to empower you to build innovative solutions for managing city lights, making urban environments smarter and more efficient. Let's get started!

What Does This API Do, and Why Is It Useful?

The Smartylighting Streetlights API provides a powerful interface to remotely manage and monitor streetlights within a smart city infrastructure. This API is built on Kafka, enabling real-time, event-driven communication for highly responsive and scalable applications.

With this API, you can:

• Turn a specific streetlight on/off 🌃: Gain granular control over individual streetlights, allowing for energy conservation and adaptive lighting based on various conditions.
• Dim a specific streetlight 😎: Adjust the brightness of streetlights to optimize energy consumption and enhance public safety or ambiance.
• Receive real-time information about environmental lighting conditions 📈: Get immediate updates on light measurements from streetlights, enabling dynamic adjustments and data-driven insights into urban lighting.

This API is incredibly useful for developing applications that:

• Implement intelligent lighting schedules.
• Respond to real-time environmental changes (e.g., dimming lights during bright daylight).
• Integrate with smart city dashboards for centralized monitoring.
• Enable remote maintenance and troubleshooting of lighting infrastructure.
• Contribute to significant energy savings and reduced operational costs for municipalities.

Prerequisites

To effectively use the Smartylighting Streetlights API, you'll need the following:

• Kafka Client Library: Since this API communicates over Kafka, you'll need a Kafka client library compatible with your chosen programming language (e.g., confluent-kafka-python for Python, kafka-clients for Java, node-rdkafka for Node.js).
• Access to a Kafka Broker: You'll need access to a Kafka broker. For testing, you can use our test broker at test.mykafkacluster.org:8092. For production, ensure you have a secure and reliable Kafka cluster configured.
• Authentication Credentials: As detailed in the Authentication section below, you'll need SASL/SCRAM credentials to connect to the Kafka broker.
• Basic Understanding of Kafka: Familiarity with Kafka concepts such as topics, producers, and consumers will be beneficial.

Resources and Capabilities

The following table outlines the key resources (topics) and the actions you can perform with this API:

Resource (Kafka Topic Pattern)	Description	Capabilities	Message Type
smartylighting.streetlights.1.0.event.{streetlightId}.lighting.measured	This topic is used to inform about environmental lighting conditions of a particular streetlight.	Publish: Send light measurement data.	lightMeasured (Payload: lumens, sentAt)
smartylighting.streetlights.1.0.action.{streetlightId}.turn.on	This topic is used to command a particular streetlight to turn the lights on.	Subscribe: Receive commands to turn on lights.	turnOnOff (Payload: command: true, sentAt)
smartylighting.streetlights.1.0.action.{streetlightId}.turn.off	This topic is used to command a particular streetlight to turn the lights off.	Subscribe: Receive commands to turn off lights.	turnOnOff (Payload: command: false, sentAt)
smartylighting.streetlights.1.0.action.{streetlightId}.dim	This topic is used to command a particular streetlight to dim the lights.	Subscribe: Receive commands to dim lights.	dimLight (Payload: percentage, sentAt)

Authentication

To securely connect to our Kafka broker and utilize the Smartylighting Streetlights API, you must authenticate using SASL/SCRAM (SCRAM-SHA-256).

How to Authenticate:

When configuring your Kafka client, you will need to provide your username and password for SASL/SCRAM authentication. The specific configuration will vary depending on your chosen Kafka client library and programming language, but the general principle remains the same.

Here's a conceptual example of how you might configure a Kafka producer or consumer with SASL/SCRAM:

Important: Replace 'YOUR_USERNAME' and 'YOUR_PASSWORD' with the actual credentials provided to you. Keep your credentials secure and do not expose them in public repositories.

By following these steps, you'll be well on your way to building powerful and intelligent streetlight management applications. Happy coding!