aes67-daemon/daemon/README.html
Andrea Bondavalli 259e99afbc First import
2020-01-28 20:16:30 +01:00

550 lines
19 KiB
HTML

<h1>AES67 Daemon</h1>
<p>AES67 daemon uses the Merging Technologies device driver (MergingRavennaALSA.ko) to implement basic AES67 functionalities. See <a href="https://bitbucket.org/MergingTechnologies/ravenna-alsa-lkm/src/master/README.md">ALSA RAVENNA/AES67 Driver README</a> for additional information.</p>
<p>The daemon is responsible for:</p>
<ul>
<li>communication and configuration of the device driver</li>
<li>provide an HTTP REST API for the daemon control and configuration</li>
<li>SAP discovery protocol implementation </li>
<li>IGMP handling for SAP and RTP sessions</li>
</ul>
<h2>Configuration file</h2>
<p>The daemon uses a JSON file to store the configuration parameters. <br />
The config file must be specified at startup time and it gets updated when new params are set via the REST interface (WebUI).
See <a href="#config">JSON config params</a> for additional info on the configuration parameters.
If a status file is specified in the daemon's configuration the server will load it at startup ad will save it at termination.
The status file contains all the configured sources and sinks (streams).
See <a href="#rtp-stream">JSON streams</a> for additional info on the status file format and its parameters.</p>
<h2>HTTP REST API</h2>
<p>The daemon implements a REST API interface to configure and control the driver.
All operations returns an HTTP <em>200</em> status code in case of success and a HTTP <em>4xx</em> or a <em>5xx</em> status code in case of failure. <br />
In case of failure the server returns a <strong>text/plain</strong> content type with the category and a description of the error occurred. <br />
<strong><em>NOTE:</em></strong> At present the embedded HTTP server doesn't implement neither HTTPS nor user authentication.</p>
<h3>Get Daemon Configuration</h3>
<ul>
<li><strong>URL</strong> /api/config </li>
<li><strong>Method</strong> GET </li>
<li><strong>URL Params</strong> none </li>
<li><strong>Body Type</strong> application/json </li>
<li><strong>Body</strong> <a href="#config">Config params</a></li>
</ul>
<h3>Set Daemon Configuration</h3>
<ul>
<li><strong>URL</strong> /api/config </li>
<li><strong>Method</strong> POST </li>
<li><strong>URL Params</strong> none </li>
<li><strong>Body Type</strong> application/json </li>
<li><strong>Body</strong> <a href="#config">Config params</a></li>
</ul>
<h3>Get PTP Configuration</h3>
<ul>
<li><strong>URL</strong> /api/ptp/config </li>
<li><strong>Method</strong> GET </li>
<li><strong>URL Params</strong> none </li>
<li><strong>Body Type</strong> application/json </li>
<li><strong>Body</strong> <a href="#ptp-config">PTP Config params</a></li>
</ul>
<h3>Set PTP Configuration</h3>
<ul>
<li><strong>URL</strong> /api/ptp/config</li>
<li><strong>Method</strong> POST</li>
<li><strong>URL Params</strong> none</li>
<li><strong>Body Type</strong> application/json </li>
<li><strong>Body</strong> <a href="#ptp-config">PTP Config params</a></li>
</ul>
<h3>Add RTP Source</h3>
<ul>
<li><strong>Description</strong> add or update the RTP source specified by the <em>id</em> </li>
<li><strong>URL</strong> /api/source/:id </li>
<li><strong>Method</strong> PUT </li>
<li><strong>URL Params</strong> id=[integer in the range (0-63)] </li>
<li><strong>Body Type</strong> application/json </li>
<li><strong>Body</strong> <a href="#rtp-source">RTP Source params</a></li>
</ul>
<h3>Remove RTP Source</h3>
<ul>
<li><strong>Description</strong> remove the RTP sink specified by the <em>id</em> </li>
<li><strong>URL</strong> /api/source/:id </li>
<li><strong>Method</strong> DELETE </li>
<li><strong>URL Params</strong> id=[integer in the range (0-63)] </li>
<li><strong>Body</strong> none </li>
</ul>
<h3>Get RTP Source SDP file</h3>
<ul>
<li><strong>Description</strong> retrieve the SDP of the source specified by <em>id</em> </li>
<li><strong>URL</strong> /api/source/sdp/:id </li>
<li><strong>Method</strong> GET </li>
<li><strong>URL Params</strong> id=[integer in the range (0-63)] </li>
<li><strong>Body Type</strong> application/sdp </li>
<li><strong>Body</strong> <a href="#rtp-source-sdp">Example SDP file for a source</a></li>
</ul>
<h3>Add RTP Sink</h3>
<ul>
<li><strong>Description</strong> add or update the RTP sink specified by the <em>id</em> </li>
<li><strong>URL</strong> /api/sink/:id </li>
<li><strong>Method</strong> PUT </li>
<li><strong>URL Params</strong> id=[integer in the range (0-63)] </li>
<li><strong>Body Type</strong> application/json </li>
<li><strong>Body</strong> <a href="#rtp-sink">RTP Sink params</a></li>
</ul>
<h3>Remove RTP Sink</h3>
<ul>
<li><strong>Description</strong> remove the RTP sink specified by <em>id</em> </li>
<li><strong>URL</strong> /api/sink/:id </li>
<li><strong>Method</strong> DELETE </li>
<li><strong>URL Params</strong> id=[integer in the range (0-63)] </li>
<li><strong>Body</strong> none </li>
</ul>
<h3>Get RTP Sink status</h3>
<ul>
<li><strong>Description</strong> retrieve the status of the sink specified by <em>id</em></li>
<li><strong>URL</strong> /api/sink/status/:id </li>
<li><strong>Method</strong> GET </li>
<li><strong>URL Params</strong> id=[integer in the range (0-63)] </li>
<li><strong>Body Type</strong> application/json </li>
<li><strong>Body</strong> <a href="#rtp-sink-status">RTP Sink status params</a></li>
</ul>
<h3>Get all configured RTP Sources</h3>
<ul>
<li><strong>URL</strong> /api/sources </li>
<li><strong>Method</strong> GET </li>
<li><strong>URL Params</strong> none </li>
<li><strong>Body type</strong> application/json </li>
<li><strong>Body</strong> <a href="#rtp-sources">RTP Sources params</a></li>
</ul>
<h3>Get all configured RTP Sinks</h3>
<ul>
<li><strong>URL</strong> /api/sinks </li>
<li><strong>Method</strong> GET </li>
<li><strong>URL Params</strong> none </li>
<li><strong>Body type</strong> application/json </li>
<li><strong>Body</strong> <a href="#rtp-sinks">RTP Sinks params</a></li>
</ul>
<h3>Get all configured RTP Sources and Sinks (Streams)</h3>
<ul>
<li><strong>URL</strong> /api/streams </li>
<li><strong>Method</strong> GET </li>
<li><strong>URL Params</strong> none </li>
<li><strong>Body type</strong> application/json </li>
<li><strong>Body</strong> <a href="#rtp-streams">RTP Streams params</a></li>
</ul>
<h2>HTTP REST API structures</h2>
<h3>JSON Config<a name="config"></a></h3>
<p>Example</p>
<pre><code>{
"interface_name": "lo",
"http_port": 8080,
"log_severity": 2,
"syslog_proto": "none",
"syslog_server": "255.255.255.254:1234",
"rtp_mcast_base": "239.2.0.1",
"status_file": "./status.json",
"rtp_port": "5004",
"ptp_domain": 0,
"ptp_dscp": 46,
"playout_delay": 0,
"frame_size_at_1fs": 192,
"sample_rate": 44100,
"max_tic_frame_size": 1024,
"sap_interval": 30,
"mac_addr": "01:00:5e:01:00:01",
"ip_addr": "127.0.0.1"
}
</code></pre>
<p>where:</p>
<blockquote>
<p><strong>interface_name</strong>
JSON string specifying the network interface used by the daemon and the driver for both the RTP, PTP, SAP and HTTP traffic.</p>
<p><strong>http_port</strong>
JSON number specifying the HTTP port number used by the embedded web server in the daemon implementing the REST interface.</p>
<p><strong>log_severity</strong>
JSON integer specifying the process log severity level (0 to 5). <br />
All traces major or equal to the specified level are enabled. (0=trace, 1=debug, 2=info, 3=warning, 4=error, 5=fatal).</p>
<p><strong>syslog_proto</strong>
JSON string specifying the syslog protocol used for logging. <br />
This can be an empty string to log to the local syslog, "udp" to send syslog messages
to a remote server or "none" to disable the syslog logging.
When "none" is used the client writes the logs to the standard output.</p>
<p><strong>syslog_server</strong>
JSON string specifying the syslog server address used for logging.</p>
<p><strong>status_file</strong>
JSON string specifying the file that will contain the sessions status. <br />
The file is loaded when the daemon starts and is saved when the daemon exits.</p>
<p><strong>rtp_mcast_base</strong>
JSON string specifying the default base RTP IPv4 multicast address used by a source. <br />
The specific multicast RTP address is the base address plus the source id number. <br />
For example if the base address is 239.2.0.1 and source id is 1 the RTP source address used is 239.2.0.2.</p>
<p><strong>rtp_port</strong>
JSON number specifying the RTP port used by the sources.</p>
<p><strong>ptp_domain</strong>
JSON number specifying the PTP clock domain of the master clock the driver will attempt to synchronize to.</p>
<p><strong>ptp_dscp</strong>
JSON number specifying the IP DSCP used in IPv4 header for PTP traffic.
Valid values are 48 (CS6) and 46 (EF).</p>
<p><strong>sample_rate</strong>
JSON number specifying the default sample rate.
Valid values are 44100Hz, 48000Hz and 96000Hz.</p>
<p><strong>playout_delay</strong>
JSON number specifying the default safety playout delay at 1FS in samples.</p>
<p><strong>tic_frame_size_at_1fs</strong>
JSON number specifying the RTP frame size at 1FS in samples.</p>
<p><strong>max_tic_frame_size</strong>
JSON number specifying the max tick frame size. <br />
In case of a high value of <em>tic_frame_size_at_1fs</em>, this must be set to 8192.</p>
<p><strong>sap_interval</strong>
JSON number specifying the SAP interval to use. Use 0 for automatic and RFC compliant interval. Default is 30secs.</p>
<p><strong>mac_addr</strong>
JSON string specifying the MAC address of the specified network device.
<strong><em>NOTE:</em></strong> This parameter is read-only and cannot be set. The server will determine the MAC address of the network device at startup time.</p>
<p><strong>ip_addr</strong>
JSON string specifying the IP address of the specified network device.
<strong><em>NOTE:</em></strong> This parameter is read-only and cannot be set. The server will determine the IP address of the network device at startup time and will monitor it periodically.</p>
</blockquote>
<h3>JSON PTP Config<a name="ptp-config"></a></h3>
<p>Example</p>
<pre><code>{
"domain": 0,
"dscp": 46
}
</code></pre>
<p>where:</p>
<blockquote>
<p><strong>domain</strong>
JSON number specifying the PTP clock domain of the master clock the driver will attempt to synchronize to. </p>
<p><strong>dscp</strong>
JSON number specifying the IP DSCP used in IPv4 header for PTP traffic. <br />
Valid values are 48 (CS6) and 46 (EF).</p>
</blockquote>
<h3>JSON RTP source<a name="rtp-source"></a></h3>
<p>Example:</p>
<pre><code>{
"enabled": true,
"name": "ALSA Source 0",
"io": "Audio Device",
"codec": "L16",
"max_samples_per_packet": 48,
"ttl": 15,
"payload_type": 98,
"dscp": 34,
"refclk_ptp_traceable": true,
"map": [0, 1]
}
</code></pre>
<p>where:</p>
<blockquote>
<p><strong>enabled</strong>
JSON bool specifying whether the source is enabled and will be announced or not. </p>
<p><strong>name</strong>
JSON string specifying the source name.</p>
<p><strong>io</strong>
JSON string specifying the IO name.</p>
<p><strong>codec</strong>
JSON string specifying codec in use.
Valid values are L16 and L24.</p>
<p><strong>max_sample_per_packet</strong>
JSON number specifying the max number of samples contained in one RTP packet.
Valid values are 12, 16, 18, 96, 192.</p>
<p><strong>ttl</strong>
JSON number specifying RTP packets Time To Live.</p>
<p><strong>payload_type</strong>
JSON number specifying RTP Payload Type.</p>
<p><strong>dscp</strong>
JSON number specifying the IP DSCP used in IPv4 header for RTP traffic.
Valid values are 46 (EF), 34 (AF41), 26 (AF31), 0 (BE).</p>
<p><strong>refclk_ptp_traceable</strong>
JSON boolean specifying whether the PTP reference clock is traceable or not.
A reference clock source is traceable if it is known to be delivering traceable time.</p>
<p><strong>map</strong>
JSON array of integers specifying the mapping between the RTP source and the ALSA playback device channels used during playback. The length of this map determines number of channels of the source.</p>
</blockquote>
<h3>RTP source SDP<a name="rtp-source-sdp"></a></h3>
<p>Example:</p>
<pre><code>v=0
o=- 0 0 IN IP4 127.0.0.1
s=ALSA Source 0
c=IN IP4 239.1.0.1/15
t=0 0
a=clock-domain:PTPv2 0
m=audio 5004 RTP/AVP 98
c=IN IP4 239.1.0.1/15
a=rtpmap:98 L16/44100/2
a=sync-time:0
a=framecount:48
a=ptime:1.08843537415
a=mediaclk:direct=0
a=ts-refclk:ptp=traceable
a=recvonly
</code></pre>
<h3>JSON RTP sink<a name="rtp-sink"></a></h3>
<p>Example:</p>
<pre><code>{
"name": "ALSA Sink 0",
"io": "Audio Device",
"delay": 576,
"use_sdp": false,
"source": "http://127.0.0.1:8080/api/source/sdp/0",
"sdp": "v=0\no=- 0 0 IN IP4 127.0.0.1\ns=ALSA Source 0\nc=IN IP4 239.1.0.1/15\nt=0 0\na=clock-domain:PTPv2 0\nm=audio 5004 RTP/AVP 98\nc=IN IP4 239.1.0.1/15\na=rtpmap:98 L16/44100/2\na=sync-time:0\na=framecount:48\na=ptime:1.08843537415\na=mediaclk:direct=0\na=ts-refclk:ptp=traceable\na=recvonly\n",
"ignore_refclk_gmid": false,
"map": [0, 1]
}
</code></pre>
<p>where:</p>
<blockquote>
<p><strong>name</strong>
JSON string specifying the source name.</p>
<p><strong>io</strong>
JSON string specifying the IO name.</p>
<p><strong>delay</strong>
JSON number specifying the playout delay of the sink in samples.
This value <em>must</em> be larger than the source frame size.</p>
<p><strong>use_sdp</strong>
JSON boolean specifying whether the source SDP file is fetched from the HTTP URL specified in the <strong>source</strong> parameter or the SDP in the <strong>sdp</strong> parameter is used.</p>
<p><strong>source</strong>
JSON string specifying the HTTP URL of the source SDP file. This parameter is mandatory if <strong>use_sdp</strong> is false.</p>
<p><strong>sdp</strong>
JSON string specifying the SDP of the source. This parameter is mandatory if <strong>use_sdp</strong> is true.
See <a href="#rtp-source-sdp">example SDP file for a source</a></p>
<p><strong>ignore_refclk_gmid</strong>
JSON boolean specifying whether the grand master reference clock ID specified in the SDP file of the source must be compared with the master reference clock to which the current PTP slave clock is syncronized.</p>
<p><strong>map</strong>
JSON array of integers specifying the mapping between the RTP sink and the ALSA capture device channels used during recording. The length of this map determines number of channels of the sink.</p>
</blockquote>
<h3>JSON RTP sink status<a name="rtp-sink-status"></a></h3>
<p>Example:</p>
<pre><code>{
"sink_flags":
{
"rtp_seq_id_error": false,
"rtp_ssrc_error": false,
"rtp_payload_type_error": false,
"rtp_sac_error": false,
"receiving_rtp_packet": false,
"some_muted": false,
"muted": true
},
"sink_min_time": 0
</code></pre>
<p>}</p>
<p>where:</p>
<blockquote>
<p><strong>sink_flags</strong>
JSON object containing a set of flags reporting the RTP sink status. </p>
<ul>
<li><p><strong>rtp_seq_id_error</strong> JSON boolean specifying whether a wrong RTP sequence was detected. </p></li>
<li><p><strong>rtp_ssrc_error</strong> JSON boolean specifying whether a wrong RTP source is contributing to the incoming stream. </p></li>
<li><p><strong>rtp_payload_type_error</strong> JSON boolean specifying whether a wrong payload type was received. </p></li>
<li><p><strong>rtp_sac_error</strong> JSON boolean specifying whether a packet with a wrong RTP timestamp was received.</p></li>
<li><p><strong>receiving_rtp_packet</strong> JSON boolean specifying whether the sink is currently receiving RTP packets from the source. </p></li>
<li><p><strong>some_muted</strong> JSON boolean (not used)</p></li>
<li><p><strong>muted</strong> JSON boolean specifying whether the sink is currently muted.</p></li>
</ul>
<p><strong>sink_min_time</strong> JSON number specifying the minimum source RTP packet arrival time. </p>
</blockquote>
<h3>JSON RTP Sources<a name="rtp-sources"></a></h3>
<p>Example:</p>
<pre><code>{
"sources": [
{
"id": 0,
"enabled": true,
"name": "ALSA Source 0",
"io": "Audio Device",
"max_samples_per_packet": 48,
"codec": "L16",
"ttl": 15,
"payload_type": 98,
"dscp": 34,
"refclk_ptp_traceable": true,
"map": [ 0, 1 ]
} ]
</code></pre>
<p>}</p>
<p>where:</p>
<blockquote>
<p><strong>sources</strong>
JSON array of the configured sources.
Every source is identified by the JSON number <strong>id</strong> (in the range 0 - 63).
See <a href="#rtp-source">RTP Source params</a> for all the other parameters.</p>
</blockquote>
<h3>JSON RTP Sinks<a name="rtp-sinks"></a></h3>
<p>Example:</p>
<pre><code>{
"sinks": [
{
"id": 0,
"name": "ALSA Sink 0",
"io": "Audio Device",
"use_sdp": true,
"source": "http://127.0.0.1:8080/api/source/sdp/0",
"sdp": "v=0\no=- 0 0 IN IP4 127.0.0.1\ns=ALSA Source 0\nc=IN IP4 239.1.0.1/15\nt=0 0\na=clock-domain:PTPv2 0\nm=audio 5004 RTP/AVP 98\nc=IN IP4 239.1.0.1/15\na=rtpmap:98 L16/44100/2\na=sync-time:0\na=framecount:48\na=ptime:1.08843537415\na=mediaclk:direct=0\na=ts-refclk:ptp=traceable\na=recvonly\n",
"delay": 576,
"ignore_refclk_gmid": false,
"map": [ 0, 1 ]
} ]
</code></pre>
<p>}</p>
<p>where:</p>
<blockquote>
<p><strong>sinks</strong>
JSON array of the configured sinks.
Every sink is identified by the JSON number <strong>id</strong> (in the range 0 - 63).
See <a href="#rtp-sink">RTP Sink params</a> for all the other parameters.</p>
</blockquote>
<h3>JSON RTP Streams<a name="rtp-streams"></a></h3>
<p>Example:</p>
<pre><code>{
"sources": [
{
"id": 0,
"enabled": true,
"name": "ALSA Source 0",
"io": "Audio Device",
"max_samples_per_packet": 48,
"codec": "L16",
"ttl": 15,
"payload_type": 98,
"dscp": 34,
"refclk_ptp_traceable": true,
"map": [ 0, 1 ]
} ],
"sinks": [
{
"id": 0,
"name": "ALSA Sink 0",
"io": "Audio Device",
"use_sdp": true,
"source": "http://127.0.0.1:8080/api/source/sdp/0",
"sdp": "v=0\no=- 0 0 IN IP4 127.0.0.1\ns=ALSA Source 0\nc=IN IP4 239.1.0.1/15\nt=0 0\na=clock-domain:PTPv2 0\nm=audio 5004 RTP/AVP 98\nc=IN IP4 239.1.0.1/15\na=rtpmap:98 L16/44100/2\na=sync-time:0\na=framecount:48\na=ptime:1.08843537415\na=mediaclk:direct=0\na=ts-refclk:ptp=traceable\na=recvonly\n",
"delay": 576,
"ignore_refclk_gmid": false,
"map": [ 0, 1 ]
} ]
}
</code></pre>
<p>where:</p>
<blockquote>
<p><strong>sources</strong>
JSON array of the configured sources.
Every source is identified by the JSON number <strong>id</strong> (in the range 0 - 63).
See <a href="#rtp-source">RTP Source params</a> for all the other parameters.</p>
<p><strong>sinks</strong>
JSON array of the configured sinks.
Every sink is identified by the JSON number <strong>id</strong> (in the range 0 - 63).
See <a href="#rtp-sink">RTP Sink params</a> for all the other parameters.</p>
</blockquote>