DOCSEARCHbyAlgolia
Submit Docs

cybergarage-upnp

repository·master·Indexed 19 days ago

https://github.com/cybergarage/cybergarage-upnp

A Java-based development framework for implementing UPnP™ protocols. It abstracts network protocols including SSDP, SOAP, GENA, HTTPU, and HTTP to simplify the creation of UPnP devices (such as media servers and IoT appliances) and control points. The framework is available via Maven through the org.cybergarage.upnp:core and org.cybergarage.upnp:std modules.

Tokens
7.3K
Snippets
17
Records
27
Agent score
62%

What's inside cybergarage-upnp

  1. Overview of cybergarage-upnp

    master
    cybergarage-upnp is a Java development package designed to automate the implementation of UPnP™ (Universal Plug and Play) protocols. It simplifies the creation of UPnP™ devices and control points by handling complex protocol standards such as GENA, SSDP, SOAP, HTTPU, and HTTP. Developers can use this package to build networked services like media servers, players, and various IoT devices.

  2. Introduction to cybergarage-upnp

    master
    cybergarage-upnp is a development package designed for developers building UPnP™ (Universal Plug and Play) devices and control points. It abstracts the complexity of underlying standard protocols such as GENA, SSDP, SOAP, HTTPU, and HTTP, allowing for the rapid creation of networked devices and services (e.g., media servers and players) without requiring manual implementation of these protocols.

  3. Trigger event notifications for subscribers

    master

    The device automatically manages UPnP™ subscriptions. When a control point subscribes to a service, the device tracks the subscriber list.

    To notify subscribers of a state change, simply update the value of a StateVariable using ServiceStateVariable::setValue(Object value). The device will automatically detect this change and send the updated state to all active subscribers.

    // Updating a state variable automatically triggers an event to all subscribers
Device clockDevice = ...;
StateVariable timeVar = clockDevice.getStateVariable("Time");
timeVar.setValue("12:00:01");

  4. How device announcement and notification works

    master

    The Device class manages UPnP™ network announcements automatically:

    • Starting: When Device::start() is called, the device sends an ssdp::alive notify message to the network.
    • Stopping: When Device::stop() is called, the device sends an ssdp::byebye message.
    • Manual Control: You can manually trigger announcements using Device::announce() or Device::byebye().
    • M-SEARCH: When a control point sends an M-SEARCH request, the device automatically responds.
    • Lease Renewal: The device automatically repeats announcements within the configured lease time.

  5. Handle device discovery and notification events

    master

    The ControlPoint automatically manages the device list based on network notifications. You can intercept these events by implementing specific listener interfaces:

    Receive Notify Events

    Implement NotifyListener to receive raw SSDPPacket messages when devices send notifications. Use addNotifyListener(this) to register.

    Monitor Device Changes

    Implement DeviceChangeListener to specifically track when devices are added or removed from the control point. Use addDeviceChangeListener(this) to register.

    Handle Search Responses

    To manually trigger a search and handle the results, call search(String target) and implement SearchResponseListener. Use addSearchResponseListener(this) to register.

    // Example: Implementing NotifyListener
public class MyCtrlPoint extends ControlPoint implements NotifyListener {
  public MyCtrlPoint() {
    addNotifyListener(this);
    start();
  }

  public void deviceNotifyReceived(SSDPPacket ssdpPacket) {
    String uuid = ssdpPacket.getUSN();
    String target = ssdpPacket.getNT();
    String subType = ssdpPacket.getNTS();
    String location = ssdpPacket.getLocation();
  }
}

// Example: Implementing DeviceChangeListener
public class MyCtrlPoint extends ControlPoint implements DeviceChangeListener {
  public MyCtrlPoint() {
    addDeviceChangeListener(this);
    start();
  }

  public void deviceAdded(Device dev) {
    // Handle added device
  }

  public void deviceRemoved(Device dev) {
    // Handle removed device
  }
}

// Example: Implementing SearchResponseListener
public class MyCtrlPoint extends ControlPoint implements SearchResponseListener {
  public MyCtrlPoint() {
    addSearchResponseListener(this);
    start();
    search("upnp:rootdevice");
  }

  public void deviceSearchResponseReceived(SSDPPacket ssdpPacket) {
    String uuid = ssdpPacket.getUSN();
    String target = ssdpPacket.getST();
    String location = ssdpPacket.getLocation();
  }
}

  7. Install cybergarage-upnp modules via Maven

    master

    The package is available in the Maven Central Repository under the group ID org.cybergarage.upnp. It is split into two primary modules depending on your development needs:

    1. org.cybergarage.upnp:core: Provides the fundamental building blocks and core UPnP standard protocol packages. Use this for low-level device or control point development.
    2. org.cybergarage.upnp:std: Built on top of the core module, this contains pre-defined implementations of standard UPnP devices to accelerate development.

  8. Explore UPnP control point and device examples

    master

    The repository contains several examples and tools to demonstrate how to implement both controllers (control points) and devices:

    Control Point (Controller) Examples

    • UPnP multicast dump utility: Dumps multicast messages from UPnP devices.
    • UPnP control point utility: A general utility for controlling UPnP devices.
    • UPnP Internet gateway utility: Specifically for managing UPnP Internet Gateway Devices (IGD).

    UPnP Device Examples

    • Standard Devices: UPnP/AV media server implementation.
    • Custom/Non-standard Devices: Examples include a clock device, light device, remote controller, television, air conditioner, and washer.

  9. Document Methods

    master

    Method documentation should include:

    1. Summary: A one-sentence description of the method's action.
    2. Details: Side effects, behavior, or important considerations.
    3. Parameters: Use @param to describe each parameter and its constraints (e.g., null-allowed, ranges).
    4. Return Value: Use @return to describe what the value represents (omit for void).
    5. Exceptions: Use @throws or @exception to explain when and why an exception is thrown.
    6. References: Use @see for related methods.
    /**
 * One-sentence summary of what the method does.
 * 
 * <p>Additional details about the method's behavior, side effects, or important considerations.
 * 
 * @param paramName description of the parameter and its constraints
 * @param anotherParam description including valid values or ranges
 * @return description of the return value and what it represents
 * @throws ExceptionType when and why this exception is thrown
 * @see #relatedMethod()
 */
public ReturnType methodName(Type paramName, Type anotherParam) throws ExceptionType {
}
    /**
 * One-sentence summary of what the method does.
 * 
 * <p>Additional details about the method's behavior, side effects, or important considerations.
 * 
 * @param paramName description of the parameter and its constraints
 * @param anotherParam description including valid values or ranges
 * @return description of the return value and what it represents
 * @throws ExceptionType when and why this exception is thrown
 * @see #relatedMethod()
 */
public ReturnType methodName(Type paramName, Type anotherParam) throws ExceptionType {
}

  10. Initialize and start a UPnP™ Control Point

    master

    To create a UPnP™ control point, instantiate the ControlPoint class and call start(). Activating the control point automatically triggers an SSDP multicast discovery message to search for devices on the network. The control point manages its own SSDP and HTTP server processes.

    import org.cybergarage.upnp.*;
import org.cybergarage.upnp.device.*;

ControlPoint ctrlPoint = new ControlPoint();
// ...existing code...
ctrlPoint.start();

  11. Run Javadoc Quality Checks

    master

    To ensure documentation quality before committing changes, perform these three steps:

    1. Compilation: Verify that Javadoc compiles without errors.

      mvn javadoc:javadoc

    2. Visual Review: Open the generated HTML documentation in your browser to check readability.

      open target/site/apidocs/index.html

    3. Automated Review: Use the project's internal tools (code_review and codeql_checker) to run automated code and security reviews.

    mvn javadoc:javadoc
open target/site/apidocs/index.html

  12. Documenting Deprecated APIs

    master

    When an API is deprecated, use the @deprecated tag and provide guidance on what to use instead using {@link}.

    /**
 * Brief description.
 * 
 * @deprecated Use {@link NewClass#newMethod()} instead. This method
 *             will be removed in version 3.0.
 */
@Deprecated
public void oldMethod() {
}
    /**
 * Brief description.
 * 
 * @deprecated Use {@link NewClass#newMethod()} instead. This method
 *             will be removed in version 3.0.
 */
@Deprecated
public void oldMethod() {
}