Developer:LPEC

Introduction

Linn's UPnP products can be controlled over a home network in an ever increaing number of ways. The primary means of control is, of course, UPnP itself, which subdivides product control into smaller units called services. A DS product, for instance, will provide some standard UPnP AV services:

AVTransport

RenderingControl

ConnectionManager

and additional Linn-specific services, such as:

Ds

Volkano

Product

Ui

It is possible in Bute and later software releases to control a Linn UPnP product using an alternative mechanism known as the Linn Protocol for Eventing and Control.

This is a basic Telnet-like protocol, which relies on the developer knowing in advance, or having discovered by some means, the TCP/IP of the device to be controlled. Knowing this, LPEC can be accessed by creating a raw socket session to port 23 of the device.

The rest of this document describes the format of the messages that LPEC expects and delivers.

Control

Each service contains actions, which are like methods that can be called on the device with input and output arguments.

An action can be perfomed by sending a message of the following form:

ACTION [id]/[type] [version] [action] "[inarg1]" "[inarg2]" ... "[inargn]"

e.g.

ACTION MediaRenderer/RenderingControl 1 SetVolume "0" "Master" "50"

All messages sent using LPEC get a response. The response to an ACTION message will be a RESPONSE message that reports the values of all the output arguments:

RESPONSE "[outarg1]" "[outarg2]" ... "[inargn]"

The SetVolume example given above has no output arguments, so the message received will simply be a <CR><LF> terminated RESPONSE message.

The following subsequent interaction better illustrates the RESPONSE message:

ACTION MediaRenderer/RenderingControl 1 GetVolume "0" "Master"

RESPONSE "50"

It should be mentioned that all input and output arguments are escaped according to XML escaping rules and enclosed in double-quotes.

Eventing

In order to subscribe to a service's events, issue a SUBSCRIBE message of the following form:

SUBSCRIBE [id]/[type] [version]

Discovery

Although LPEC does not include a mechanism for discovering devices across a home network, it does contain a mechanism for knowing about the sub-devices within a single product.

When an LPEC connection is made the device sends ALIVE messages to describe thesub-devices that are currently available:

ALIVE <id> <udn>

e.g.

ALIVE Ds 4c494e4e-0050-c221-71e5-df000003013f
ALIVE Preamp 4c494e4e-0050-c221-71e5-df0000030133
ALIVE MediaRenderer 4c494e4e-0050-c221-71e5-df0000030171

It is possible for these sub-devices to be disabled and enabled during the normal operation of a product. if this occurs, BYEBYE messages and ALIVE are issued accordingly.

If a device is rebooted, the appropriate BYEBYE messages are sent and the LPEC connection is closed by the device.

Errors

After sending an ACTION, SUBSCRIBE, or UNSUBSCRIBE message, it is possible to receive an ERROR message of the form:

ERROR [code] "[description]"