Yamaha MusicCast™ v0.2.2 MusicCast.Network

A module for supervising a network of MusicCast™ devices.

The network is the heart of this MusicCast application. It is responsible for discovering devices on the local network (see MusicCast.UPnP.SSDPClient) and keeping their state synchronized.

Registry

The network act as a global registry for running MusicCast.Network.Entity processes. You can find a device on the registry with whereis/1. To get a list of registered devices, see which_devices/1.

Pub/Sub

You have the possibility to subscribe to network topoligy changes (for example, when a new device is discovered or when a device goes offline). Additionally, you can subscribe to a device’s changefeed directly. See subscribe/1 and unsubscribe/1 for more details.

Summary

Types

device_id()

Functions

add_device(addr, upnp_desc)

Adds a new device entity to the network

lookup(device_id, keys \\ :all)

Returns the device state value(s) for the given lookup key(s)

start_link(options \\ [])

Starts a network supervisor as part of a supervision tree

stop(pid, reason \\ :normal, timeout \\ :infinity)

Stops the network supervisor

subscribe(entity)

Subscribes the current process to notifications from the given entity

unsubscribe(entity)

Unsubscribes the current process from notification from the given entity

whereis(device_id)

Returns the PID for the registered device id or nil if the given device_id is not available

which_devices(keys \\ :lazy)

Returns a list of all registered devices

Types

device_id()

device_id() :: String.t

Functions

add_device(addr, upnp_desc)

add_device(MusicCast.Network.Entity.ip_address, MusicCast.UPnP.Service.t) :: Supervisor.on_start_child

Adds a new device entity to the network.

lookup(device_id, keys \\ :all)

lookup(device_id, MusicCast.Network.Entity.lookup_query) :: any

Returns the device state value(s) for the given lookup key(s).

See MusicCast.Network.Entity.__lookup__/2 for a list of allowed lookup keys.

start_link(options \\ [])

start_link(Keyword.t) :: Supervisor.on_start

Starts a network supervisor as part of a supervision tree.

stop(pid, reason \\ :normal, timeout \\ :infinity)

stop(pid, term, timeout) :: :ok

Stops the network supervisor.

subscribe(entity)

subscribe(:network | device_id) :: {:ok, pid}

Subscribes the current process to notifications from the given entity.

You can subscribe to network topology changes:

iex> MusicCast.subscribe(:network)
{:ok, #PID<0.80.0>}
iex> flush()
{:musiccast, :online, %MusicCast.Network.Entity{...}}

Or subscribe to status notifications from a specific device:

iex> MusicCast.subscribe("00A0DEDCF73E")
{:ok, #PID<0.200.0>}
iex> flush()
{:musiccast, :update, "00A0DEDCF73E", %{...}}

unsubscribe(entity)

unsubscribe(:network | device_id) :: :ok

Unsubscribes the current process from notification from the given entity.

whereis(device_id)

whereis(device_id) :: pid | nil

Returns the PID for the registered device id or nil if the given device_id is not available.

which_devices(keys \\ :lazy)

which_devices(:lazy | MusicCast.Network.Entity.lookup_query) :: [tuple]

Returns a list of all registered devices.

If you pass :lazy to this function, it will return a list of {pid, device_id} tuples:

iex> MusicCast.which_devices(:lazy)
[{#PID<0.200.0>, "00A0DEDCF73E"}]

Otherwise, you can specify a list of keys to lookup for:

iex> MusicCast.which_devices([:network_name, :host])
[{#PID<0.200.0>, ["Schlafzimmer", "192.168.0.63"]}]

See lookup/2 for more informations about available lookup options.