Difference between revisions of "Developer:LPEC"

From LinnDocs
Jump to: navigation, search
Line 28: Line 28:
 
LPEC can be accessed by connecting a raw socket session to port 23 of the device.<br>
 
LPEC can be accessed by connecting a raw socket session to port 23 of the device.<br>
  
= <br> Control<br> =
+
= <br>Control<br> =
  
 
Each service contains actions, which are like methods that can be called on the device with input and output arguments.
 
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:
 
An action can be perfomed by sending a message of the following form:
<blockquote>ACTION [sub-device]/[type] [version] [action] "[inarg1]" "[inarg2]" ... "[inargn]"</blockquote>  
+
<blockquote>ACTION [sub-device]/[type] [version] [action] "[inarg1]" "[inarg2]" ... "[inargn]"</blockquote>
 
e.g.
 
e.g.
<blockquote>ACTION MediaRenderer/RenderingControl 1 SetVolume "0" "Master" "50"</blockquote>  
+
<blockquote>ACTION MediaRenderer/RenderingControl 1 SetVolume "0" "Master" "50"</blockquote>
 
All messages sent using LPEC get a response. The response to an ACTION message is a RESPONSE message that reports the values of all the output arguments:
 
All messages sent using LPEC get a response. The response to an ACTION message is a RESPONSE message that reports the values of all the output arguments:
<blockquote>RESPONSE "[outarg1]" "[outarg2]" ... "[outargn]"</blockquote>  
+
<blockquote>RESPONSE "[outarg1]" "[outarg2]" ... "[outargn]"</blockquote>
 
The SetVolume example given above has no output arguments, so the message received will simply be a &lt;CR&gt;&lt;LF&gt; terminated RESPONSE message.
 
The SetVolume example given above has no output arguments, so the message received will simply be a &lt;CR&gt;&lt;LF&gt; terminated RESPONSE message.
  
Line 43: Line 43:
 
<blockquote>ACTION MediaRenderer/RenderingControl 1 GetVolume "0" "Master"</blockquote><blockquote>
 
<blockquote>ACTION MediaRenderer/RenderingControl 1 GetVolume "0" "Master"</blockquote><blockquote>
 
RESPONSE "50"
 
RESPONSE "50"
</blockquote>  
+
</blockquote>
 
It should be mentioned that all input and output arguments are escaped according to XML escaping rules and enclosed in double-quotes.<br>
 
It should be mentioned that all input and output arguments are escaped according to XML escaping rules and enclosed in double-quotes.<br>
  
Line 49: Line 49:
  
 
In order to subscribe to a service's events, issue a SUBSCRIBE message of the following form:
 
In order to subscribe to a service's events, issue a SUBSCRIBE message of the following form:
<blockquote>SUBSCRIBE [sub-device]/[type]<br></blockquote>  
+
<blockquote>SUBSCRIBE [sub-device]/[type]<br></blockquote>
 
The device responds with:<br>
 
The device responds with:<br>
<blockquote>SUBSCRIBE [subscription-id]<br></blockquote>  
+
<blockquote>SUBSCRIBE [subscription-id]<br></blockquote>
and follows this with an initial event message, which contains the current state of all the service's evented variables:<br>
+
and follows this with an initial event message, which contains the current state of all the services' evented variables:<br>
<blockquote>EVENT [subscription-id] 0 [var1-name] "[var1]" [var2-name] "[var2]" ... [varn-name] "[varn]"<br></blockquote>  
+
<blockquote>EVENT [subscription-id] 0 [var1-name] "[var1]" [var2-name] "[var2]" ... [varn-name] "[varn]"<br></blockquote>
 
e.g<br>
 
e.g<br>
<blockquote>SUBSCRIBE Ds/Product<br>SUBSCRIBE 49<br>EVENT 49 0 ProductName "Sneaky Music DS" ProductRoom "Main Room" ProductStandby "true" ProductSourceIndex "0"</blockquote>  
+
<blockquote>SUBSCRIBE Ds/Product<br>SUBSCRIBE 49<br>EVENT 49 0 ProductName "Sneaky Music DS" ProductRoom "Main Room" ProductStandby "true" ProductSourceIndex "0"</blockquote>
 
Subsequent changes to the service's evented variables cause unsolicited EVENT messages to be sent from the device of the form:
 
Subsequent changes to the service's evented variables cause unsolicited EVENT messages to be sent from the device of the form:
<blockquote>EVENT [subscription-id] [sequence-no] [var1-name] "[var1]" [var2-name] "[var2]" ... [varn-name] "[varn]"</blockquote>  
+
<blockquote>EVENT [subscription-id] [sequence-no] [var1-name] "[var1]" [var2-name] "[var2]" ... [varn-name] "[varn]"</blockquote>
 
Only those variables that have changed value are reported.
 
Only those variables that have changed value are reported.
  
 
The sequence number is a 32-bit unsigned number which increments with each event message and wraps around to 1.
 
The sequence number is a 32-bit unsigned number which increments with each event message and wraps around to 1.
  
A sequence number of 0 is reserved for the initial EVENT message, which contains the current state of all the service's evented variables (see above)
+
A sequence number of 0 is reserved for the initial EVENT message, which contains the current state of all the services' evented variables (see above)
  
 
By issuing multiple SUBSCRIBE messages, it is possible to subscribe to up to 16 services simultaneously.<br>
 
By issuing multiple SUBSCRIBE messages, it is possible to subscribe to up to 16 services simultaneously.<br>
  
 
In order to unsubscribe from a service, send an UNSUBSCRIBE message of the form:<br>
 
In order to unsubscribe from a service, send an UNSUBSCRIBE message of the form:<br>
<blockquote>UNSUBSCRIBE [subscription-id]<br></blockquote>  
+
<blockquote>UNSUBSCRIBE [subscription-id]<br></blockquote>
 
alternatively:<br>
 
alternatively:<br>
<blockquote>UNSUBSCRIBE [sub-device]/[type]<br></blockquote>  
+
<blockquote>UNSUBSCRIBE [sub-device]/[type]<br></blockquote>
 
or, to unsubscribe from all previous subscriptions, just:<br>
 
or, to unsubscribe from all previous subscriptions, just:<br>
<blockquote>UNSUBSCRIBE<br></blockquote>  
+
<blockquote>UNSUBSCRIBE<br></blockquote>
 
In all instances, the response will be:<br>
 
In all instances, the response will be:<br>
<blockquote>UNSUBSCRIBE [subscription-id]<br></blockquote>  
+
<blockquote>UNSUBSCRIBE [subscription-id]<br></blockquote>
 
When using the form that unsubscribes from all previous subscriptions, multiple UNSUBSCRIBE responses may be received.<br>
 
When using the form that unsubscribes from all previous subscriptions, multiple UNSUBSCRIBE responses may be received.<br>
  
 
e.g.
 
e.g.
 
<blockquote>UNSUBSCRIBE<br>UNSUBSCRIBE 62<br>UNSUBSCRIBE 61<br></blockquote>
 
<blockquote>UNSUBSCRIBE<br>UNSUBSCRIBE 62<br>UNSUBSCRIBE 61<br></blockquote>
 
 
= Discovery =
 
= Discovery =
  
Line 84: Line 83:
  
 
When an LPEC connection is made, the device sends an ALIVE messages for each sub-device that is currently available:<br>
 
When an LPEC connection is made, the device sends an ALIVE messages for each sub-device that is currently available:<br>
<blockquote>ALIVE [sub-device] [udn]<br></blockquote>  
+
<blockquote>ALIVE [sub-device] [udn]<br></blockquote>
 
e.g. (from a Sneaky Music DS)<br>
 
e.g. (from a Sneaky Music DS)<br>
<blockquote>ALIVE Ds 4c494e4e-0050-c221-71e5-df000003013f<br>ALIVE Preamp 4c494e4e-0050-c221-71e5-df0000030133<br>ALIVE MediaRenderer 4c494e4e-0050-c221-71e5-df0000030171</blockquote>  
+
<blockquote>ALIVE Ds 4c494e4e-0050-c221-71e5-df000003013f<br>ALIVE Preamp 4c494e4e-0050-c221-71e5-df0000030133<br>ALIVE MediaRenderer 4c494e4e-0050-c221-71e5-df0000030171</blockquote>
It is possible for these sub-devices to be disabled and enabled during the normal operation of a product. if this occurs, further BYEBYE and ALIVE messages are issued accordingly.
+
It is possible for these sub-devices to be disabled and enabled during the normal operation of a product. If this occurs, further BYEBYE and ALIVE messages are issued accordingly.
  
 
If a device is rebooted, the appropriate BYEBYE messages are sent and the LPEC connection is closed by the device.
 
If a device is rebooted, the appropriate BYEBYE messages are sent and the LPEC connection is closed by the device.
Line 96: Line 95:
  
 
After sending an ACTION, SUBSCRIBE, or UNSUBSCRIBE message, it is possible to receive an ERROR message of the form:
 
After sending an ACTION, SUBSCRIBE, or UNSUBSCRIBE message, it is possible to receive an ERROR message of the form:
<blockquote>ERROR [code] "[description]"</blockquote>  
+
<blockquote>ERROR [code] "[description]"</blockquote>
 
The following errors are defined:<br>
 
The following errors are defined:<br>
<blockquote>ERROR 101 "Command not recognised"<br>ERROR 102 "Service not specified"<br>ERROR 103 "Service not found"<br>ERROR 104 "Version invalid"<br>ERROR 105 "Version not specified"<br>ERROR 106 "Version not supported"<br>ERROR 107 "Method not specified"<br>ERROR 108 "Method execution exception"<br>ERROR 201 "Boolean argument invalid"<br>ERROR 202 "String argument invalid"<br>ERROR 203 "Unsigned numeric argument invalid"<br>ERROR 204 "Signed numeric invalid"<br>ERROR 205 "Binary argument invalid"<br>ERROR 206 "Invalid argument escaping"<br>ERROR 301 "Argument list incomplete"<br>ERROR 302 "Argument not quoted"<br>ERROR 303 "Argument incomplete"<br>ERROR 401 "Already subscribed"<br>ERROR 402 "Client has too many subscriptions"<br>ERROR 403 "Service has too many subscriptions"<br>ERROR 404 "Subscription not found"<br>ERROR 405 "Service not subscribed"<br>ERROR 406 "Invalid XML escaping"<br></blockquote>  
+
<blockquote>ERROR 101 "Command not recognised"<br>ERROR 102 "Service not specified"<br>ERROR 103 "Service not found"<br>ERROR 104 "Version invalid"<br>ERROR 105 "Version not specified"<br>ERROR 106 "Version not supported"<br>ERROR 107 "Method not specified"<br>ERROR 108 "Method execution exception"<br>ERROR 201 "Boolean argument invalid"<br>ERROR 202 "String argument invalid"<br>ERROR 203 "Unsigned numeric argument invalid"<br>ERROR 204 "Signed numeric invalid"<br>ERROR 205 "Binary argument invalid"<br>ERROR 206 "Invalid argument escaping"<br>ERROR 301 "Argument list incomplete"<br>ERROR 302 "Argument not quoted"<br>ERROR 303 "Argument incomplete"<br>ERROR 401 "Already subscribed"<br>ERROR 402 "Client has too many subscriptions"<br>ERROR 403 "Service has too many subscriptions"<br>ERROR 404 "Subscription not found"<br>ERROR 405 "Service not subscribed"<br>ERROR 406 "Invalid XML escaping"<br></blockquote>
 
Action-specific error messages may also be sent.
 
Action-specific error messages may also be sent.
  
 
+
<br>
  
 
= Examples =
 
= Examples =
  
Play, Pause, Skip a Ds product using the UPnP AVTransport service:
+
Play, Pause, Skip a DS player using the UPnP AVTransport service:
<blockquote>
+
<blockquote>ACTION MediaRenderer/AVTransport 1 Play</blockquote><blockquote>
ACTION MediaRenderer/AVTransport 1 Play
 
</blockquote><blockquote>
 
 
ACTION MediaRenderer/AVTransport 1 Pause
 
ACTION MediaRenderer/AVTransport 1 Pause
 
</blockquote><blockquote>
 
</blockquote><blockquote>
Line 114: Line 111:
 
</blockquote><blockquote>
 
</blockquote><blockquote>
 
ACTION MediaRenderer/AVTransport 1 Previous
 
ACTION MediaRenderer/AVTransport 1 Previous
</blockquote> <blockquote></blockquote>
+
</blockquote><blockquote></blockquote>
Get the volume of a Linn Preamp product using the Linn Preamp service
+
Get the volume of a Linn pre-amplifier using the Linn Preamp service
<blockquote>
+
<blockquote>ACTION Preamp/Preamp 1 Volume</blockquote><blockquote>
ACTION Preamp/Preamp 1 Volume
 
</blockquote><blockquote>
 
 
RESPONSE "40"
 
RESPONSE "40"
 
</blockquote>
 
</blockquote>
Set mute on a Linn Preamp product using the Linn Preamp service
+
Set mute on a Linn pre-amplifier using the Linn Preamp service
<blockquote>
+
<blockquote>ACTION Preamp/Preamp 1 SetMute "true"</blockquote><blockquote>
ACTION Preamp/Preamp 1 SetMute "true"
 
</blockquote><blockquote>
 
 
RESPONSE
 
RESPONSE
 
</blockquote>
 
</blockquote>
 
 
= Other Considerations<br> =
 
= Other Considerations<br> =
  
 
If a control point closes an LPEC session, all outstanding subscriptions are automatically cleaned up by the device.
 
If a control point closes an LPEC session, all outstanding subscriptions are automatically cleaned up by the device.
  
Each product supports only one concurrent LPEC session<br>
+
Each product supports only one concurrent LPEC session.<br>

Revision as of 12:50, 20 June 2008

Introduction

This article provides the specification of the Linn Protocol for Eventing and Control.  This is a IP point-2-point protocol that can be used to control Linn's home network products (e.g. DS players).

Linn's UPnP products can be controlled over a home network in an ever increasing number of ways. The primary means of control is, of course, UPnP itself.  LPEC provides an alternative mechanism of using UPnP services over a basic "telnet-like" protocol.

The UPnP architecture subdivides product control into smaller named units called "services". A DS player, 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 the Bute software and later software releases, to control a Linn UPnP product using 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 address of the device to be controlled. With this knowledge, LPEC can be accessed by connecting a raw socket session to port 23.

The rest of this article describes the format of the messages that LPEC expects and delivers.  Examples are given.

Connection

LPEC can be accessed by connecting a raw socket session to port 23 of the device.


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 [sub-device]/[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 is a RESPONSE message that reports the values of all the output arguments:

RESPONSE "[outarg1]" "[outarg2]" ... "[outargn]"

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 [sub-device]/[type]

The device responds with:

SUBSCRIBE [subscription-id]

and follows this with an initial event message, which contains the current state of all the services' evented variables:

EVENT [subscription-id] 0 [var1-name] "[var1]" [var2-name] "[var2]" ... [varn-name] "[varn]"

e.g

SUBSCRIBE Ds/Product
SUBSCRIBE 49
EVENT 49 0 ProductName "Sneaky Music DS" ProductRoom "Main Room" ProductStandby "true" ProductSourceIndex "0"

Subsequent changes to the service's evented variables cause unsolicited EVENT messages to be sent from the device of the form:

EVENT [subscription-id] [sequence-no] [var1-name] "[var1]" [var2-name] "[var2]" ... [varn-name] "[varn]"

Only those variables that have changed value are reported.

The sequence number is a 32-bit unsigned number which increments with each event message and wraps around to 1.

A sequence number of 0 is reserved for the initial EVENT message, which contains the current state of all the services' evented variables (see above)

By issuing multiple SUBSCRIBE messages, it is possible to subscribe to up to 16 services simultaneously.

In order to unsubscribe from a service, send an UNSUBSCRIBE message of the form:

UNSUBSCRIBE [subscription-id]

alternatively:

UNSUBSCRIBE [sub-device]/[type]

or, to unsubscribe from all previous subscriptions, just:

UNSUBSCRIBE

In all instances, the response will be:

UNSUBSCRIBE [subscription-id]

When using the form that unsubscribes from all previous subscriptions, multiple UNSUBSCRIBE responses may be received.

e.g.

UNSUBSCRIBE
UNSUBSCRIBE 62
UNSUBSCRIBE 61

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 an ALIVE messages for each sub-device that is currently available:

ALIVE [sub-device] [udn]

e.g. (from a Sneaky Music DS)

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, further BYEBYE and ALIVE messages are issued accordingly.

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

When a sub-device is disabled, all subscriptions to the services on that sub-device are forcibly revoked. A BYEBYE message may therefore have a number of unsolicited UNSUBSCRIBE messages preceding it.

Errors

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

ERROR [code] "[description]"

The following errors are defined:

ERROR 101 "Command not recognised"
ERROR 102 "Service not specified"
ERROR 103 "Service not found"
ERROR 104 "Version invalid"
ERROR 105 "Version not specified"
ERROR 106 "Version not supported"
ERROR 107 "Method not specified"
ERROR 108 "Method execution exception"
ERROR 201 "Boolean argument invalid"
ERROR 202 "String argument invalid"
ERROR 203 "Unsigned numeric argument invalid"
ERROR 204 "Signed numeric invalid"
ERROR 205 "Binary argument invalid"
ERROR 206 "Invalid argument escaping"
ERROR 301 "Argument list incomplete"
ERROR 302 "Argument not quoted"
ERROR 303 "Argument incomplete"
ERROR 401 "Already subscribed"
ERROR 402 "Client has too many subscriptions"
ERROR 403 "Service has too many subscriptions"
ERROR 404 "Subscription not found"
ERROR 405 "Service not subscribed"
ERROR 406 "Invalid XML escaping"

Action-specific error messages may also be sent.


Examples

Play, Pause, Skip a DS player using the UPnP AVTransport service:

ACTION MediaRenderer/AVTransport 1 Play

ACTION MediaRenderer/AVTransport 1 Pause

ACTION MediaRenderer/AVTransport 1 Next

ACTION MediaRenderer/AVTransport 1 Previous

Get the volume of a Linn pre-amplifier using the Linn Preamp service

ACTION Preamp/Preamp 1 Volume

RESPONSE "40"

Set mute on a Linn pre-amplifier using the Linn Preamp service

ACTION Preamp/Preamp 1 SetMute "true"

RESPONSE

Other Considerations

If a control point closes an LPEC session, all outstanding subscriptions are automatically cleaned up by the device.

Each product supports only one concurrent LPEC session.