LinuxMCE - User contributions [en]

How to setup Local Authoritative DNS

2008-09-05T23:00:03Z

Juanfe: /* Installation */

[[category: Tutorials]]
=How to setup Local Authoritative DNS=

I was wanting an authoritative name server for my local intranet. I also wanted any dynamic IP's to be visible to the name server. The name server included with linuxmce is configured as a recursive name server. Here's the changes I did to configure my core's name server to be authoritative and support dynamic IPs. Note, the machines on my intranet are private, i.e., not known to the outside world.

3 Feb 2008 - Developed and tested on LinuxMCE 0710 Beta 3 amd64.

I named my intranet "wright.local". Using a "local" top level domain (TLD) is recommended for private intranets. Some may prefer to use "lan". You do not want to use any of the standard TLDs like "com", "net", "org",...

I used the core's default intranet addresses, 192.168.80.0/24 with the core at 192.168.80.1.

I've attempted to verbosely document each config file. :)

The directions for adapting the config files are included in the named.conf file.

==Installation==

If you want to try this, I would suggest building the config in new directories then swapping with the originals when you are ready (I had a little mess when my core hung and I had to restart with only half the configs ready) :)

So start with creating two directories:

sudo mkdir /etc/bind.new
sudo mkdir /etc/dhcp3.new

Now copy the contents of the original directories:

sudo cp -arp /etc/bind/* /etc/bind.new
sudo cp -arp /etc/dhcp3/* /etc/dhcp3.new

Also create a new resolve.conf file:

sudo touch /etc/resolv.conf.new

You will be creating or editing the following config files in these new directories:

/etc/bind.new/named.conf
/etc/bind.new/named.conf.options
/etc/bind.new/logging.conf
/etc/bind.new/rndc.conf
/etc/bind.new/rndc.key
/etc/bind.new/db.wright.local.zone
/etc/bind.new/db.wright.local.rev
/etc/dhcp3.new/dhcpd.conf
/etc/resolv.conf.new

The full text of the files you will be editing is at the foot of this page. The original author named his network "wright"; you should replace all instances of "wright" with the name of your network.

==Notes on Editing Files==

===rndc.key and dhcpd.conf key values===

To create a key for use in rndc.key and dhcpd.conf:

sudo dnssec-keygen -a HMAC-MD5 -b 256 -n user rndc

Now get the key from the private file:

sudo cat Krndc.*.private
Private-key-format: v1.2
Algorithm: 157 (HMAC_MD5)
Key: 3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=
Bits: AAA=

Now cut the key which is to the right of "Key: " and paste where needed (replace "<paste your key here>" with the key in the config files). So an example using the above key would look like:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

becomes:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=";
};

===Check directory ownership===
Make the logging directory:

sudo mkdir /var/log/named
sudo chown bind:bind /var/log/named
sudo chmod 755 /var/log/named

===Setting default domain===
You probably ought to check and change the defaultdomain:

domainname

will probably show

pluto

if so, then set it by:
sudo domainname yourdomain.local

where "yourdomain.local" is your domain. :-)

===File Permissions===
Change all the file permissions per instructions in named.conf:

File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//

===Double check. Everything===
Double check everything. Roll Eyes

==Wrapping up==
When and if you are feeling lucky, rename the original directories and then rename the new directories to take their place:

sudo mv /etc/bind /etc/bind.original
sudo mv /etc/bind.new /etc/bind
sudo mv /etc/dhcp3 /etc/dhcp3.original
sudo mv /etc/dhcp3.new /etc/dhcp3
sudo mv /etc/resolve.conf /etc/resolve.conf.original
sudo mv /etc/resolve.conf.new /etc/resolve.conf

Finally restart the bind and dhcpd services:

sudo rndc reload
sudo /etc/init.d/dhcp3-server restart

Check the syslog for any errors:

grep named /var/log/syslog
grep dhcpd /var/log/syslog

==Config Files==

===/etc/bind/named.conf===
<pre>
// This is the primary configuration file for the BIND DNS server named.
//
// This configuration supports an authoritative local zone (wright.local on
// 192.168.80.0/24) and allows DHCP to update the local zone.
// To customize to your setup:
// 1) replace "wright.local" with your internal domain name.
// 2) edit db.wright.local.zone and db.wright.local.rev and replace
// my static names/addresses with your network's static names/addresses.
// Make sure to increment the serial number of any file edited.
// Note, format of serial number is: YYYYMMDDNN where YYYY is year,
// MM is month, DD is day, NN is update number for that day (i.e., 01,
// 02, 03,...)
// 3) rename db.wright.local.zone to match your domain name.
// 4) rename db.wright.local.rev to match your domain name.
// 5) If you changed the internal network IP from the LinuxMCE default of
// 192.168.80.0/24, then replace "192.168.80" with your network
// ip and replace it's reverse "80.168.192" wity your network ip's
// reverse.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
//
// references:
// http://www.arda.homeunix.net/dnssetup.html
// http://www.madboa.com/geek/soho-bind/
//
// notes:
// 1) The following command should be ran about twice a year to keep
// the root servers current:
// dig @a.root-servers.net . ns > /etc/bin/db.root
// Root name servers don’t change very often so updating this file more
// than twice a year is probably overkill. Frequent updates also put undo
// load on the root name servers; they have enough to do as it is.
//
// 2) File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//
// Manually Updating Zone Files
// 1. Use rndc to stop BIND.
// sudo rndc stop
// 2. Remove any .jnl files from the zone file directory.
// sudo rm /etc/bind/*.jnl
// 3. Edit the zone files as necessary. Make sure to increment the serial
// number of any file edited. Note, format of serial number is:
// YYYYMMDDNN where YYYY is year, MM is month, DD is day, NN is update
// number for that day (i.e., 01, 02, 03,...)
// 4. Start BIND using its startup script.
// sudo /etc/init.d/bind9 start

// secret must be the same as in /etc/bind/rndc.conf
include "/etc/bind/rndc.key";

// access control list used to limit queries to local net
acl "internal-net" { 192.168.80/24; 127.0.0.1; };

controls {
inet 127.0.0.1 allow { any; } keys { "rndc-key"; };
};

include "/etc/bind/named.conf.options";

// The single dot (.) is the root of all DNS namespace, so
// this zone tells named where to start looking for any
// name on the Internet
zone "." IN {
type hint;
file "/etc/bind/db.root";
};

// local intranet zones and reverse zones
// intranet is wright.local and 192.168.80.0/24
// the DHCP servers is on linuxmce-dhcp
// an optional second nameserver would be on linuxmce-ns2

zone "wright.local" IN {
type master;
file "/etc/bind/db.wright.local.zone";
// both allow-update and update-policy can enable DHCP updates,
// but update-policy allows more control over what kinds of
// updates DHCP can perform on a zone.
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain wright.local. A TXT; };
// allow-transfer { key "linuxmce-ns2"; };
// notify on zone transfers
notify yes;
};

zone "80.168.192.in-addr.arpa" IN {
type master;
file "/etc/bind/db.wright.local.rev";
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain 80.168.192.in-addr.arpa. PTR TXT; };
// allow-transfer { key "linuxmce-ns2"; };
notify yes;
};

// be authoritative for the localhost forward and reverse zones, and for
// broadcast zones as per RFC 1912 (http://www.ietf.org/rfc/rfc1912.txt)

// Where the localhost hostname is defined
zone "localhost" IN {
// a master type means that this server needn't look
// anywhere else for information; the localhost buck
// stops here.
type master;
file "/etc/bind/db.local";
// don't allow dynamic DNS clients to update info
// about the localhost zone
allow-update { none; };
};

// Where the 127.0.0.0 network is defined
zone "127.in-addr.arpa" IN {
type master;
file "/etc/bind/db.127";
allow-update { none; };
};

zone "0.in-addr.arpa" IN {
type master;
file "/etc/bind/db.0";
allow-update { none; };
};

zone "255.in-addr.arpa" IN {
type master;
file "/etc/bind/db.255";
allow-update { none; };
};

// Include logging config file
include "/etc/bind/logging.conf";

// zone "com" { type delegation-only; };
// zone "net" { type delegation-only; };

// From the release notes:
// Because many of our users are uncomfortable receiving undelegated answers
// from root or top level domains, other than a few for whom that behaviour
// has been trusted and expected for quite some length of time, we have now
// introduced the "root-delegations-only" feature which applies delegation-only
// logic to all top level domains, and to the root domain. An exception list
// should be specified, including "MUSEUM" and "DE", and any other top level
// domains from whom undelegated responses are expected and trusted.
// root-delegation-only exclude { "DE"; "MUSEUM"; };

include "/etc/bind/named.conf.local";
</pre>

===/etc/bind/named.conf.options===
<pre>
options {
// tell named where to find files mentioned below
directory "/var/cache/bind";

// file that contains the process id when bind is running
pid-file "/var/run/bind/run/named.pid";

// enable statistics
statistics-file "/var/named/named.stats";
zone-statistics yes;

dump-file "/var/named/named.dump";

// If there is a firewall between you and nameservers you want
// to talk to, you might need to uncomment the query-source
// directive below. Previous versions of BIND always asked
// questions using port 53, but BIND 8.1 and later use an unprivileged
// port by default.
// query-source address * port 53;

// If your ISP provided one or more IP addresses for stable
// nameservers, you probably want to use them as forwarders.
// Uncomment the following block, and insert the addresses replacing
// the all-0's placeholder.

// The forwarders option tells BIND to not use iterative queries itself
// for information it doesn’t already know about but to forward a
// recursive query to the name servers specified instead.
include "/etc/bind/named.conf.forwarders";

// conform to RFC1035
auth-nxdomain no;

// on a multi-homed host, you might want to tell named
// to listen for queries only on certain interfaces
listen-on-v6 { any; };
listen-on { "internal-net"; };

// to allow only specific hosts to use the DNS server:
allow-query { "internal-net"; };

// sets BIND’s default behaviour to refuse all zone transfers.
// Without setting this option, anyone can transfer any zone.
allow-transfer { none; };

// do not generate notify messages for all zones on a restart.
// override for authorative zones
notify no;
};
</pre>

===/etc/bind/logging.conf===
<pre>
logging {

channel default_file {
file "/var/log/named/default.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel general_file {
file "/var/log/named/general.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel database_file {
file "/var/log/named/database.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel security_file {
file "/var/log/named/security.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel config_file {
file "/var/log/named/config.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel resolver_file {
file "/var/log/named/resolver.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-in_file {
file "/var/log/named/xfer-in.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-out_file {
file "/var/log/named/xfer-out.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel notify_file {
file "/var/log/named/notify.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel client_file {
file "/var/log/named/client.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel unmatched_file {
file "/var/log/named/unmatched.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel queries_file {
file "/var/log/named/queries.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel network_file {
file "/var/log/named/network.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel update_file {
file "/var/log/named/update.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dispatch_file {
file "/var/log/named/dispatch.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dnssec_file {
file "/var/log/named/dnssec.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel lame-servers_file {
file "/var/log/named/lame-servers.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};

category lame-servers {
lame-servers_file;
};
category dnssec {
dnssec_file;
};
category dispatch {
dispatch_file;
};
category update {
update_file;
};
category network {
network_file;
};
category queries {
queries_file;
};
category unmatched {
unmatched_file;
};
category client {
client_file;
};
category notify {
notify_file;
};
category xfer-out {
xfer-out_file;
};
category xfer-in {
xfer-in_file;
};
category resolver {
resolver_file;
};
category config {
config_file;
};
category security {
security_file;
};
category database {
database_file;
};
category general {
general_file;
};
category default {
default_file;
};
};
</pre>

===/etc/bind/rndc.conf===
<pre>
options {
default-server localhost;
default-key "rndc-key";
default-port 953;
};

server localhost {
key "rndc-key";
};

key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/rndc.key===
<pre>
key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-ns2" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/db.wright.local.zone===
<pre>
;
; BIND data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; Address records specify an IP address to assign to a name
;
dcerouter IN A 192.168.80.1
thenameofamachine IN A 192.168.80.21
thenameofanothermachine IN A 192.168.80.20
;
; Canonical name records, maps one name to another.
;
linuxmce IN CNAME dcerouter
</pre>

===/etc/bind/db.wright.local.rev===
<pre>

;
; BIND reverse data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$ORIGIN 80.168.192.in-addr.arpa.
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; PTR — PoinTeR record, designed to point to another part of the namespace.
;
1 IN PTR dcerouter.wright.local.
21 IN PTR dad-kubuntu.wright.local.
20 IN PTR royw-gentoo.wright.local.
</pre>

===/etc/dhcp3/dhcpd.conf===
<pre>
option domain-name-servers 192.168.80.1;
authoritative;

option routers 192.168.80.1;
option subnet-mask 255.255.255.0;

# lease IPs for 1 day, maximum 1 week
default-lease-time 86400;
max-lease-time 604800;

# dynamic DNS updates
ddns-updates on;
ddns-update-style interim;
ddns-domainname "wright.local.";
ddns-rev-domainname "in-addr.arpa.";
ddns-ttl 14400;

# don't let clients modify their own A records
ignore client-updates;

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

zone wright.local {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

zone 80.168.192.in-addr.arpa {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

option space pxelinux;
option pxelinux.magic code 208 = string;
option pxelinux.configfile code 209 = text;
option pxelinux.pathprefix code 210 = text;
option pxelinux.reboottime code 211 = unsigned integer 32;

subnet 192.168.80.0 netmask 255.255.255.0 {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

option domain-name "wright.local";
option domain-name-servers 192.168.80.1;
option routers 192.168.80.1;

default-lease-time 86400;
max-lease-time 604800;
pool {
allow unknown-clients;
range 192.168.80.129 192.168.80.254;
}
}

# PXE booting machines
group {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

}

# regular machines
group {
}

# CORE (1) has bad mac address:

</pre>

===/etc/resolv.conf===
<pre>
domain wright.local
nameserver localhost
</pre>

How to setup Local Authoritative DNS

2008-09-05T22:37:35Z

Juanfe: /* /etc/bind/db.wright.local.zone */

[[category: Tutorials]]
=How to setup Local Authoritative DNS=

I was wanting an authoritative name server for my local intranet. I also wanted any dynamic IP's to be visible to the name server. The name server included with linuxmce is configured as a recursive name server. Here's the changes I did to configure my core's name server to be authoritative and support dynamic IPs. Note, the machines on my intranet are private, i.e., not known to the outside world.

3 Feb 2008 - Developed and tested on LinuxMCE 0710 Beta 3 amd64.

I named my intranet "wright.local". Using a "local" top level domain (TLD) is recommended for private intranets. Some may prefer to use "lan". You do not want to use any of the standard TLDs like "com", "net", "org",...

I used the core's default intranet addresses, 192.168.80.0/24 with the core at 192.168.80.1.

I've attempted to verbosely document each config file. :)

The directions for adapting the config files are included in the named.conf file.

==Installation==

If you want to try this, I would suggest building the config in new directories then swapping with the originals when you are ready (I had a little mess when my core hung and I had to restart with only half the configs ready) :)

So start with creating two directories:

sudo mkdir /etc/bind.new
sudo mkdir /etc/dhcp3.new

Now copy the contents of the original directories:

sudo cp -arp /etc/bind/* /etc/bind.new
sudo cp -arp /etc/dhcp3/* /etc/dhcp3.new

Also create a new resolve.conf file:

sudo touch /etc/resolv.conf.new

You will be creating or editing the following config files in these new directories:

/etc/bind.new/named.conf
/etc/bind.new/named.conf.options
/etc/bind.new/logging.conf
/etc/bind.new/rndc.conf
/etc/bind.new/rndc.key
/etc/bind.new/db.wright.local.zone
/etc/bind.new/db.wright.local.rev
/etc/dhcp3.new/dhcpd.conf
/etc/resolv.conf

The full text of the files you will be editing is at the foot of this page. The original author named his network "wright"; you should replace all instances of "wright" with the name of your network.

==Notes on Editing Files==

===rndc.key and dhcpd.conf key values===

To create a key for use in rndc.key and dhcpd.conf:

sudo dnssec-keygen -a HMAC-MD5 -b 256 -n user rndc

Now get the key from the private file:

sudo cat Krndc.*.private
Private-key-format: v1.2
Algorithm: 157 (HMAC_MD5)
Key: 3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=
Bits: AAA=

Now cut the key which is to the right of "Key: " and paste where needed (replace "<paste your key here>" with the key in the config files). So an example using the above key would look like:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

becomes:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=";
};

===Check directory ownership===
Make the logging directory:

sudo mkdir /var/log/named
sudo chown bind:bind /var/log/named
sudo chmod 755 /var/log/named

===Setting default domain===
You probably ought to check and change the defaultdomain:

domainname

will probably show

pluto

if so, then set it by:
sudo domainname yourdomain.local

where "yourdomain.local" is your domain. :-)

===File Permissions===
Change all the file permissions per instructions in named.conf:

File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//

===Double check. Everything===
Double check everything. Roll Eyes

==Wrapping up==
When and if you are feeling lucky, rename the original directories and then rename the new directories to take their place:

sudo mv /etc/bind /etc/bind.original
sudo mv /etc/bind.new /etc/bind
sudo mv /etc/dhcp3 /etc/dhcp3.original
sudo mv /etc/dhcp3.new /etc/dhcp3
sudo mv /etc/resolve.conf /etc/resolve.conf.original
sudo mv /etc/resolve.conf.new /etc/resolve.conf

Finally restart the bind and dhcpd services:

sudo rndc reload
sudo /etc/init.d/dhcp3-server restart

Check the syslog for any errors:

grep named /var/log/syslog
grep dhcpd /var/log/syslog

==Config Files==

===/etc/bind/named.conf===
<pre>
// This is the primary configuration file for the BIND DNS server named.
//
// This configuration supports an authoritative local zone (wright.local on
// 192.168.80.0/24) and allows DHCP to update the local zone.
// To customize to your setup:
// 1) replace "wright.local" with your internal domain name.
// 2) edit db.wright.local.zone and db.wright.local.rev and replace
// my static names/addresses with your network's static names/addresses.
// Make sure to increment the serial number of any file edited.
// Note, format of serial number is: YYYYMMDDNN where YYYY is year,
// MM is month, DD is day, NN is update number for that day (i.e., 01,
// 02, 03,...)
// 3) rename db.wright.local.zone to match your domain name.
// 4) rename db.wright.local.rev to match your domain name.
// 5) If you changed the internal network IP from the LinuxMCE default of
// 192.168.80.0/24, then replace "192.168.80" with your network
// ip and replace it's reverse "80.168.192" wity your network ip's
// reverse.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
//
// references:
// http://www.arda.homeunix.net/dnssetup.html
// http://www.madboa.com/geek/soho-bind/
//
// notes:
// 1) The following command should be ran about twice a year to keep
// the root servers current:
// dig @a.root-servers.net . ns > /etc/bin/db.root
// Root name servers don’t change very often so updating this file more
// than twice a year is probably overkill. Frequent updates also put undo
// load on the root name servers; they have enough to do as it is.
//
// 2) File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//
// Manually Updating Zone Files
// 1. Use rndc to stop BIND.
// sudo rndc stop
// 2. Remove any .jnl files from the zone file directory.
// sudo rm /etc/bind/*.jnl
// 3. Edit the zone files as necessary. Make sure to increment the serial
// number of any file edited. Note, format of serial number is:
// YYYYMMDDNN where YYYY is year, MM is month, DD is day, NN is update
// number for that day (i.e., 01, 02, 03,...)
// 4. Start BIND using its startup script.
// sudo /etc/init.d/bind9 start

// secret must be the same as in /etc/bind/rndc.conf
include "/etc/bind/rndc.key";

// access control list used to limit queries to local net
acl "internal-net" { 192.168.80/24; 127.0.0.1; };

controls {
inet 127.0.0.1 allow { any; } keys { "rndc-key"; };
};

include "/etc/bind/named.conf.options";

// The single dot (.) is the root of all DNS namespace, so
// this zone tells named where to start looking for any
// name on the Internet
zone "." IN {
type hint;
file "/etc/bind/db.root";
};

// local intranet zones and reverse zones
// intranet is wright.local and 192.168.80.0/24
// the DHCP servers is on linuxmce-dhcp
// an optional second nameserver would be on linuxmce-ns2

zone "wright.local" IN {
type master;
file "/etc/bind/db.wright.local.zone";
// both allow-update and update-policy can enable DHCP updates,
// but update-policy allows more control over what kinds of
// updates DHCP can perform on a zone.
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain wright.local. A TXT; };
// allow-transfer { key "linuxmce-ns2"; };
// notify on zone transfers
notify yes;
};

zone "80.168.192.in-addr.arpa" IN {
type master;
file "/etc/bind/db.wright.local.rev";
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain 80.168.192.in-addr.arpa. PTR TXT; };
// allow-transfer { key "linuxmce-ns2"; };
notify yes;
};

// be authoritative for the localhost forward and reverse zones, and for
// broadcast zones as per RFC 1912 (http://www.ietf.org/rfc/rfc1912.txt)

// Where the localhost hostname is defined
zone "localhost" IN {
// a master type means that this server needn't look
// anywhere else for information; the localhost buck
// stops here.
type master;
file "/etc/bind/db.local";
// don't allow dynamic DNS clients to update info
// about the localhost zone
allow-update { none; };
};

// Where the 127.0.0.0 network is defined
zone "127.in-addr.arpa" IN {
type master;
file "/etc/bind/db.127";
allow-update { none; };
};

zone "0.in-addr.arpa" IN {
type master;
file "/etc/bind/db.0";
allow-update { none; };
};

zone "255.in-addr.arpa" IN {
type master;
file "/etc/bind/db.255";
allow-update { none; };
};

// Include logging config file
include "/etc/bind/logging.conf";

// zone "com" { type delegation-only; };
// zone "net" { type delegation-only; };

// From the release notes:
// Because many of our users are uncomfortable receiving undelegated answers
// from root or top level domains, other than a few for whom that behaviour
// has been trusted and expected for quite some length of time, we have now
// introduced the "root-delegations-only" feature which applies delegation-only
// logic to all top level domains, and to the root domain. An exception list
// should be specified, including "MUSEUM" and "DE", and any other top level
// domains from whom undelegated responses are expected and trusted.
// root-delegation-only exclude { "DE"; "MUSEUM"; };

include "/etc/bind/named.conf.local";
</pre>

===/etc/bind/named.conf.options===
<pre>
options {
// tell named where to find files mentioned below
directory "/var/cache/bind";

// file that contains the process id when bind is running
pid-file "/var/run/bind/run/named.pid";

// enable statistics
statistics-file "/var/named/named.stats";
zone-statistics yes;

dump-file "/var/named/named.dump";

// If there is a firewall between you and nameservers you want
// to talk to, you might need to uncomment the query-source
// directive below. Previous versions of BIND always asked
// questions using port 53, but BIND 8.1 and later use an unprivileged
// port by default.
// query-source address * port 53;

// If your ISP provided one or more IP addresses for stable
// nameservers, you probably want to use them as forwarders.
// Uncomment the following block, and insert the addresses replacing
// the all-0's placeholder.

// The forwarders option tells BIND to not use iterative queries itself
// for information it doesn’t already know about but to forward a
// recursive query to the name servers specified instead.
include "/etc/bind/named.conf.forwarders";

// conform to RFC1035
auth-nxdomain no;

// on a multi-homed host, you might want to tell named
// to listen for queries only on certain interfaces
listen-on-v6 { any; };
listen-on { "internal-net"; };

// to allow only specific hosts to use the DNS server:
allow-query { "internal-net"; };

// sets BIND’s default behaviour to refuse all zone transfers.
// Without setting this option, anyone can transfer any zone.
allow-transfer { none; };

// do not generate notify messages for all zones on a restart.
// override for authorative zones
notify no;
};
</pre>

===/etc/bind/logging.conf===
<pre>
logging {

channel default_file {
file "/var/log/named/default.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel general_file {
file "/var/log/named/general.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel database_file {
file "/var/log/named/database.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel security_file {
file "/var/log/named/security.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel config_file {
file "/var/log/named/config.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel resolver_file {
file "/var/log/named/resolver.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-in_file {
file "/var/log/named/xfer-in.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-out_file {
file "/var/log/named/xfer-out.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel notify_file {
file "/var/log/named/notify.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel client_file {
file "/var/log/named/client.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel unmatched_file {
file "/var/log/named/unmatched.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel queries_file {
file "/var/log/named/queries.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel network_file {
file "/var/log/named/network.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel update_file {
file "/var/log/named/update.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dispatch_file {
file "/var/log/named/dispatch.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dnssec_file {
file "/var/log/named/dnssec.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel lame-servers_file {
file "/var/log/named/lame-servers.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};

category lame-servers {
lame-servers_file;
};
category dnssec {
dnssec_file;
};
category dispatch {
dispatch_file;
};
category update {
update_file;
};
category network {
network_file;
};
category queries {
queries_file;
};
category unmatched {
unmatched_file;
};
category client {
client_file;
};
category notify {
notify_file;
};
category xfer-out {
xfer-out_file;
};
category xfer-in {
xfer-in_file;
};
category resolver {
resolver_file;
};
category config {
config_file;
};
category security {
security_file;
};
category database {
database_file;
};
category general {
general_file;
};
category default {
default_file;
};
};
</pre>

===/etc/bind/rndc.conf===
<pre>
options {
default-server localhost;
default-key "rndc-key";
default-port 953;
};

server localhost {
key "rndc-key";
};

key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/rndc.key===
<pre>
key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-ns2" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/db.wright.local.zone===
<pre>
;
; BIND data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; Address records specify an IP address to assign to a name
;
dcerouter IN A 192.168.80.1
thenameofamachine IN A 192.168.80.21
thenameofanothermachine IN A 192.168.80.20
;
; Canonical name records, maps one name to another.
;
linuxmce IN CNAME dcerouter
</pre>

===/etc/bind/db.wright.local.rev===
<pre>

;
; BIND reverse data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$ORIGIN 80.168.192.in-addr.arpa.
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; PTR — PoinTeR record, designed to point to another part of the namespace.
;
1 IN PTR dcerouter.wright.local.
21 IN PTR dad-kubuntu.wright.local.
20 IN PTR royw-gentoo.wright.local.
</pre>

===/etc/dhcp3/dhcpd.conf===
<pre>
option domain-name-servers 192.168.80.1;
authoritative;

option routers 192.168.80.1;
option subnet-mask 255.255.255.0;

# lease IPs for 1 day, maximum 1 week
default-lease-time 86400;
max-lease-time 604800;

# dynamic DNS updates
ddns-updates on;
ddns-update-style interim;
ddns-domainname "wright.local.";
ddns-rev-domainname "in-addr.arpa.";
ddns-ttl 14400;

# don't let clients modify their own A records
ignore client-updates;

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

zone wright.local {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

zone 80.168.192.in-addr.arpa {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

option space pxelinux;
option pxelinux.magic code 208 = string;
option pxelinux.configfile code 209 = text;
option pxelinux.pathprefix code 210 = text;
option pxelinux.reboottime code 211 = unsigned integer 32;

subnet 192.168.80.0 netmask 255.255.255.0 {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

option domain-name "wright.local";
option domain-name-servers 192.168.80.1;
option routers 192.168.80.1;

default-lease-time 86400;
max-lease-time 604800;
pool {
allow unknown-clients;
range 192.168.80.129 192.168.80.254;
}
}

# PXE booting machines
group {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

}

# regular machines
group {
}

# CORE (1) has bad mac address:

</pre>

===/etc/resolv.conf===
<pre>
domain wright.local
nameserver localhost
</pre>

How to setup Local Authoritative DNS

2008-09-05T22:30:51Z

Juanfe: /* Check directory ownership */

[[category: Tutorials]]
=How to setup Local Authoritative DNS=

I was wanting an authoritative name server for my local intranet. I also wanted any dynamic IP's to be visible to the name server. The name server included with linuxmce is configured as a recursive name server. Here's the changes I did to configure my core's name server to be authoritative and support dynamic IPs. Note, the machines on my intranet are private, i.e., not known to the outside world.

3 Feb 2008 - Developed and tested on LinuxMCE 0710 Beta 3 amd64.

I named my intranet "wright.local". Using a "local" top level domain (TLD) is recommended for private intranets. Some may prefer to use "lan". You do not want to use any of the standard TLDs like "com", "net", "org",...

I used the core's default intranet addresses, 192.168.80.0/24 with the core at 192.168.80.1.

I've attempted to verbosely document each config file. :)

The directions for adapting the config files are included in the named.conf file.

==Installation==

If you want to try this, I would suggest building the config in new directories then swapping with the originals when you are ready (I had a little mess when my core hung and I had to restart with only half the configs ready) :)

So start with creating two directories:

sudo mkdir /etc/bind.new
sudo mkdir /etc/dhcp3.new

Now copy the contents of the original directories:

sudo cp -arp /etc/bind/* /etc/bind.new
sudo cp -arp /etc/dhcp3/* /etc/dhcp3.new

Also create a new resolve.conf file:

sudo touch /etc/resolv.conf.new

You will be creating or editing the following config files in these new directories:

/etc/bind.new/named.conf
/etc/bind.new/named.conf.options
/etc/bind.new/logging.conf
/etc/bind.new/rndc.conf
/etc/bind.new/rndc.key
/etc/bind.new/db.wright.local.zone
/etc/bind.new/db.wright.local.rev
/etc/dhcp3.new/dhcpd.conf
/etc/resolv.conf

The full text of the files you will be editing is at the foot of this page. The original author named his network "wright"; you should replace all instances of "wright" with the name of your network.

==Notes on Editing Files==

===rndc.key and dhcpd.conf key values===

To create a key for use in rndc.key and dhcpd.conf:

sudo dnssec-keygen -a HMAC-MD5 -b 256 -n user rndc

Now get the key from the private file:

sudo cat Krndc.*.private
Private-key-format: v1.2
Algorithm: 157 (HMAC_MD5)
Key: 3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=
Bits: AAA=

Now cut the key which is to the right of "Key: " and paste where needed (replace "<paste your key here>" with the key in the config files). So an example using the above key would look like:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

becomes:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=";
};

===Check directory ownership===
Make the logging directory:

sudo mkdir /var/log/named
sudo chown bind:bind /var/log/named
sudo chmod 755 /var/log/named

===Setting default domain===
You probably ought to check and change the defaultdomain:

domainname

will probably show

pluto

if so, then set it by:
sudo domainname yourdomain.local

where "yourdomain.local" is your domain. :-)

===File Permissions===
Change all the file permissions per instructions in named.conf:

File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//

===Double check. Everything===
Double check everything. Roll Eyes

==Wrapping up==
When and if you are feeling lucky, rename the original directories and then rename the new directories to take their place:

sudo mv /etc/bind /etc/bind.original
sudo mv /etc/bind.new /etc/bind
sudo mv /etc/dhcp3 /etc/dhcp3.original
sudo mv /etc/dhcp3.new /etc/dhcp3
sudo mv /etc/resolve.conf /etc/resolve.conf.original
sudo mv /etc/resolve.conf.new /etc/resolve.conf

Finally restart the bind and dhcpd services:

sudo rndc reload
sudo /etc/init.d/dhcp3-server restart

Check the syslog for any errors:

grep named /var/log/syslog
grep dhcpd /var/log/syslog

==Config Files==

===/etc/bind/named.conf===
<pre>
// This is the primary configuration file for the BIND DNS server named.
//
// This configuration supports an authoritative local zone (wright.local on
// 192.168.80.0/24) and allows DHCP to update the local zone.
// To customize to your setup:
// 1) replace "wright.local" with your internal domain name.
// 2) edit db.wright.local.zone and db.wright.local.rev and replace
// my static names/addresses with your network's static names/addresses.
// Make sure to increment the serial number of any file edited.
// Note, format of serial number is: YYYYMMDDNN where YYYY is year,
// MM is month, DD is day, NN is update number for that day (i.e., 01,
// 02, 03,...)
// 3) rename db.wright.local.zone to match your domain name.
// 4) rename db.wright.local.rev to match your domain name.
// 5) If you changed the internal network IP from the LinuxMCE default of
// 192.168.80.0/24, then replace "192.168.80" with your network
// ip and replace it's reverse "80.168.192" wity your network ip's
// reverse.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
//
// references:
// http://www.arda.homeunix.net/dnssetup.html
// http://www.madboa.com/geek/soho-bind/
//
// notes:
// 1) The following command should be ran about twice a year to keep
// the root servers current:
// dig @a.root-servers.net . ns > /etc/bin/db.root
// Root name servers don’t change very often so updating this file more
// than twice a year is probably overkill. Frequent updates also put undo
// load on the root name servers; they have enough to do as it is.
//
// 2) File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//
// Manually Updating Zone Files
// 1. Use rndc to stop BIND.
// sudo rndc stop
// 2. Remove any .jnl files from the zone file directory.
// sudo rm /etc/bind/*.jnl
// 3. Edit the zone files as necessary. Make sure to increment the serial
// number of any file edited. Note, format of serial number is:
// YYYYMMDDNN where YYYY is year, MM is month, DD is day, NN is update
// number for that day (i.e., 01, 02, 03,...)
// 4. Start BIND using its startup script.
// sudo /etc/init.d/bind9 start

// secret must be the same as in /etc/bind/rndc.conf
include "/etc/bind/rndc.key";

// access control list used to limit queries to local net
acl "internal-net" { 192.168.80/24; 127.0.0.1; };

controls {
inet 127.0.0.1 allow { any; } keys { "rndc-key"; };
};

include "/etc/bind/named.conf.options";

// The single dot (.) is the root of all DNS namespace, so
// this zone tells named where to start looking for any
// name on the Internet
zone "." IN {
type hint;
file "/etc/bind/db.root";
};

// local intranet zones and reverse zones
// intranet is wright.local and 192.168.80.0/24
// the DHCP servers is on linuxmce-dhcp
// an optional second nameserver would be on linuxmce-ns2

zone "wright.local" IN {
type master;
file "/etc/bind/db.wright.local.zone";
// both allow-update and update-policy can enable DHCP updates,
// but update-policy allows more control over what kinds of
// updates DHCP can perform on a zone.
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain wright.local. A TXT; };
// allow-transfer { key "linuxmce-ns2"; };
// notify on zone transfers
notify yes;
};

zone "80.168.192.in-addr.arpa" IN {
type master;
file "/etc/bind/db.wright.local.rev";
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain 80.168.192.in-addr.arpa. PTR TXT; };
// allow-transfer { key "linuxmce-ns2"; };
notify yes;
};

// be authoritative for the localhost forward and reverse zones, and for
// broadcast zones as per RFC 1912 (http://www.ietf.org/rfc/rfc1912.txt)

// Where the localhost hostname is defined
zone "localhost" IN {
// a master type means that this server needn't look
// anywhere else for information; the localhost buck
// stops here.
type master;
file "/etc/bind/db.local";
// don't allow dynamic DNS clients to update info
// about the localhost zone
allow-update { none; };
};

// Where the 127.0.0.0 network is defined
zone "127.in-addr.arpa" IN {
type master;
file "/etc/bind/db.127";
allow-update { none; };
};

zone "0.in-addr.arpa" IN {
type master;
file "/etc/bind/db.0";
allow-update { none; };
};

zone "255.in-addr.arpa" IN {
type master;
file "/etc/bind/db.255";
allow-update { none; };
};

// Include logging config file
include "/etc/bind/logging.conf";

// zone "com" { type delegation-only; };
// zone "net" { type delegation-only; };

// From the release notes:
// Because many of our users are uncomfortable receiving undelegated answers
// from root or top level domains, other than a few for whom that behaviour
// has been trusted and expected for quite some length of time, we have now
// introduced the "root-delegations-only" feature which applies delegation-only
// logic to all top level domains, and to the root domain. An exception list
// should be specified, including "MUSEUM" and "DE", and any other top level
// domains from whom undelegated responses are expected and trusted.
// root-delegation-only exclude { "DE"; "MUSEUM"; };

include "/etc/bind/named.conf.local";
</pre>

===/etc/bind/named.conf.options===
<pre>
options {
// tell named where to find files mentioned below
directory "/var/cache/bind";

// file that contains the process id when bind is running
pid-file "/var/run/bind/run/named.pid";

// enable statistics
statistics-file "/var/named/named.stats";
zone-statistics yes;

dump-file "/var/named/named.dump";

// If there is a firewall between you and nameservers you want
// to talk to, you might need to uncomment the query-source
// directive below. Previous versions of BIND always asked
// questions using port 53, but BIND 8.1 and later use an unprivileged
// port by default.
// query-source address * port 53;

// If your ISP provided one or more IP addresses for stable
// nameservers, you probably want to use them as forwarders.
// Uncomment the following block, and insert the addresses replacing
// the all-0's placeholder.

// The forwarders option tells BIND to not use iterative queries itself
// for information it doesn’t already know about but to forward a
// recursive query to the name servers specified instead.
include "/etc/bind/named.conf.forwarders";

// conform to RFC1035
auth-nxdomain no;

// on a multi-homed host, you might want to tell named
// to listen for queries only on certain interfaces
listen-on-v6 { any; };
listen-on { "internal-net"; };

// to allow only specific hosts to use the DNS server:
allow-query { "internal-net"; };

// sets BIND’s default behaviour to refuse all zone transfers.
// Without setting this option, anyone can transfer any zone.
allow-transfer { none; };

// do not generate notify messages for all zones on a restart.
// override for authorative zones
notify no;
};
</pre>

===/etc/bind/logging.conf===
<pre>
logging {

channel default_file {
file "/var/log/named/default.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel general_file {
file "/var/log/named/general.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel database_file {
file "/var/log/named/database.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel security_file {
file "/var/log/named/security.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel config_file {
file "/var/log/named/config.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel resolver_file {
file "/var/log/named/resolver.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-in_file {
file "/var/log/named/xfer-in.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-out_file {
file "/var/log/named/xfer-out.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel notify_file {
file "/var/log/named/notify.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel client_file {
file "/var/log/named/client.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel unmatched_file {
file "/var/log/named/unmatched.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel queries_file {
file "/var/log/named/queries.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel network_file {
file "/var/log/named/network.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel update_file {
file "/var/log/named/update.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dispatch_file {
file "/var/log/named/dispatch.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dnssec_file {
file "/var/log/named/dnssec.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel lame-servers_file {
file "/var/log/named/lame-servers.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};

category lame-servers {
lame-servers_file;
};
category dnssec {
dnssec_file;
};
category dispatch {
dispatch_file;
};
category update {
update_file;
};
category network {
network_file;
};
category queries {
queries_file;
};
category unmatched {
unmatched_file;
};
category client {
client_file;
};
category notify {
notify_file;
};
category xfer-out {
xfer-out_file;
};
category xfer-in {
xfer-in_file;
};
category resolver {
resolver_file;
};
category config {
config_file;
};
category security {
security_file;
};
category database {
database_file;
};
category general {
general_file;
};
category default {
default_file;
};
};
</pre>

===/etc/bind/rndc.conf===
<pre>
options {
default-server localhost;
default-key "rndc-key";
default-port 953;
};

server localhost {
key "rndc-key";
};

key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/rndc.key===
<pre>
key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-ns2" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/db.wright.local.zone===
<pre>
;
; BIND data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; Address records specify an IP address to assign to a name
;
dcerouter IN A 192.168.80.1
dad-kubuntu IN A 192.168.80.21
royw-gentoo IN A 192.168.80.20
;
; Canonical name records, maps one name to another.
;
linuxmce IN CNAME dcerouter
</pre>

===/etc/bind/db.wright.local.rev===
<pre>

;
; BIND reverse data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$ORIGIN 80.168.192.in-addr.arpa.
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; PTR — PoinTeR record, designed to point to another part of the namespace.
;
1 IN PTR dcerouter.wright.local.
21 IN PTR dad-kubuntu.wright.local.
20 IN PTR royw-gentoo.wright.local.
</pre>

===/etc/dhcp3/dhcpd.conf===
<pre>
option domain-name-servers 192.168.80.1;
authoritative;

option routers 192.168.80.1;
option subnet-mask 255.255.255.0;

# lease IPs for 1 day, maximum 1 week
default-lease-time 86400;
max-lease-time 604800;

# dynamic DNS updates
ddns-updates on;
ddns-update-style interim;
ddns-domainname "wright.local.";
ddns-rev-domainname "in-addr.arpa.";
ddns-ttl 14400;

# don't let clients modify their own A records
ignore client-updates;

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

zone wright.local {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

zone 80.168.192.in-addr.arpa {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

option space pxelinux;
option pxelinux.magic code 208 = string;
option pxelinux.configfile code 209 = text;
option pxelinux.pathprefix code 210 = text;
option pxelinux.reboottime code 211 = unsigned integer 32;

subnet 192.168.80.0 netmask 255.255.255.0 {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

option domain-name "wright.local";
option domain-name-servers 192.168.80.1;
option routers 192.168.80.1;

default-lease-time 86400;
max-lease-time 604800;
pool {
allow unknown-clients;
range 192.168.80.129 192.168.80.254;
}
}

# PXE booting machines
group {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

}

# regular machines
group {
}

# CORE (1) has bad mac address:

</pre>

===/etc/resolv.conf===
<pre>
domain wright.local
nameserver localhost
</pre>

How to setup Local Authoritative DNS

2008-09-05T22:30:15Z

Juanfe: /* File Permissions */

[[category: Tutorials]]
=How to setup Local Authoritative DNS=

I was wanting an authoritative name server for my local intranet. I also wanted any dynamic IP's to be visible to the name server. The name server included with linuxmce is configured as a recursive name server. Here's the changes I did to configure my core's name server to be authoritative and support dynamic IPs. Note, the machines on my intranet are private, i.e., not known to the outside world.

3 Feb 2008 - Developed and tested on LinuxMCE 0710 Beta 3 amd64.

I named my intranet "wright.local". Using a "local" top level domain (TLD) is recommended for private intranets. Some may prefer to use "lan". You do not want to use any of the standard TLDs like "com", "net", "org",...

I used the core's default intranet addresses, 192.168.80.0/24 with the core at 192.168.80.1.

I've attempted to verbosely document each config file. :)

The directions for adapting the config files are included in the named.conf file.

==Installation==

If you want to try this, I would suggest building the config in new directories then swapping with the originals when you are ready (I had a little mess when my core hung and I had to restart with only half the configs ready) :)

So start with creating two directories:

sudo mkdir /etc/bind.new
sudo mkdir /etc/dhcp3.new

Now copy the contents of the original directories:

sudo cp -arp /etc/bind/* /etc/bind.new
sudo cp -arp /etc/dhcp3/* /etc/dhcp3.new

Also create a new resolve.conf file:

sudo touch /etc/resolv.conf.new

You will be creating or editing the following config files in these new directories:

/etc/bind.new/named.conf
/etc/bind.new/named.conf.options
/etc/bind.new/logging.conf
/etc/bind.new/rndc.conf
/etc/bind.new/rndc.key
/etc/bind.new/db.wright.local.zone
/etc/bind.new/db.wright.local.rev
/etc/dhcp3.new/dhcpd.conf
/etc/resolv.conf

The full text of the files you will be editing is at the foot of this page. The original author named his network "wright"; you should replace all instances of "wright" with the name of your network.

==Notes on Editing Files==

===rndc.key and dhcpd.conf key values===

To create a key for use in rndc.key and dhcpd.conf:

sudo dnssec-keygen -a HMAC-MD5 -b 256 -n user rndc

Now get the key from the private file:

sudo cat Krndc.*.private
Private-key-format: v1.2
Algorithm: 157 (HMAC_MD5)
Key: 3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=
Bits: AAA=

Now cut the key which is to the right of "Key: " and paste where needed (replace "<paste your key here>" with the key in the config files). So an example using the above key would look like:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

becomes:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=";
};

===Check directory ownership===
Make the logging directory:

sudo mkdir /var/log/named
sudo chown bind:bind /var/log/named
sudo chmod 755 /var/log/named

You probably ought to check and change the defaultdomain:

domainname

will probably show

pluto

if so, then set it by:
sudo domainname yourdomain.local

where "yourdomain.local" is your domain. :-)

===File Permissions===
Change all the file permissions per instructions in named.conf:

File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//

===Double check. Everything===
Double check everything. Roll Eyes

==Wrapping up==
When and if you are feeling lucky, rename the original directories and then rename the new directories to take their place:

sudo mv /etc/bind /etc/bind.original
sudo mv /etc/bind.new /etc/bind
sudo mv /etc/dhcp3 /etc/dhcp3.original
sudo mv /etc/dhcp3.new /etc/dhcp3
sudo mv /etc/resolve.conf /etc/resolve.conf.original
sudo mv /etc/resolve.conf.new /etc/resolve.conf

Finally restart the bind and dhcpd services:

sudo rndc reload
sudo /etc/init.d/dhcp3-server restart

Check the syslog for any errors:

grep named /var/log/syslog
grep dhcpd /var/log/syslog

==Config Files==

===/etc/bind/named.conf===
<pre>
// This is the primary configuration file for the BIND DNS server named.
//
// This configuration supports an authoritative local zone (wright.local on
// 192.168.80.0/24) and allows DHCP to update the local zone.
// To customize to your setup:
// 1) replace "wright.local" with your internal domain name.
// 2) edit db.wright.local.zone and db.wright.local.rev and replace
// my static names/addresses with your network's static names/addresses.
// Make sure to increment the serial number of any file edited.
// Note, format of serial number is: YYYYMMDDNN where YYYY is year,
// MM is month, DD is day, NN is update number for that day (i.e., 01,
// 02, 03,...)
// 3) rename db.wright.local.zone to match your domain name.
// 4) rename db.wright.local.rev to match your domain name.
// 5) If you changed the internal network IP from the LinuxMCE default of
// 192.168.80.0/24, then replace "192.168.80" with your network
// ip and replace it's reverse "80.168.192" wity your network ip's
// reverse.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
//
// references:
// http://www.arda.homeunix.net/dnssetup.html
// http://www.madboa.com/geek/soho-bind/
//
// notes:
// 1) The following command should be ran about twice a year to keep
// the root servers current:
// dig @a.root-servers.net . ns > /etc/bin/db.root
// Root name servers don’t change very often so updating this file more
// than twice a year is probably overkill. Frequent updates also put undo
// load on the root name servers; they have enough to do as it is.
//
// 2) File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//
// Manually Updating Zone Files
// 1. Use rndc to stop BIND.
// sudo rndc stop
// 2. Remove any .jnl files from the zone file directory.
// sudo rm /etc/bind/*.jnl
// 3. Edit the zone files as necessary. Make sure to increment the serial
// number of any file edited. Note, format of serial number is:
// YYYYMMDDNN where YYYY is year, MM is month, DD is day, NN is update
// number for that day (i.e., 01, 02, 03,...)
// 4. Start BIND using its startup script.
// sudo /etc/init.d/bind9 start

// secret must be the same as in /etc/bind/rndc.conf
include "/etc/bind/rndc.key";

// access control list used to limit queries to local net
acl "internal-net" { 192.168.80/24; 127.0.0.1; };

controls {
inet 127.0.0.1 allow { any; } keys { "rndc-key"; };
};

include "/etc/bind/named.conf.options";

// The single dot (.) is the root of all DNS namespace, so
// this zone tells named where to start looking for any
// name on the Internet
zone "." IN {
type hint;
file "/etc/bind/db.root";
};

// local intranet zones and reverse zones
// intranet is wright.local and 192.168.80.0/24
// the DHCP servers is on linuxmce-dhcp
// an optional second nameserver would be on linuxmce-ns2

zone "wright.local" IN {
type master;
file "/etc/bind/db.wright.local.zone";
// both allow-update and update-policy can enable DHCP updates,
// but update-policy allows more control over what kinds of
// updates DHCP can perform on a zone.
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain wright.local. A TXT; };
// allow-transfer { key "linuxmce-ns2"; };
// notify on zone transfers
notify yes;
};

zone "80.168.192.in-addr.arpa" IN {
type master;
file "/etc/bind/db.wright.local.rev";
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain 80.168.192.in-addr.arpa. PTR TXT; };
// allow-transfer { key "linuxmce-ns2"; };
notify yes;
};

// be authoritative for the localhost forward and reverse zones, and for
// broadcast zones as per RFC 1912 (http://www.ietf.org/rfc/rfc1912.txt)

// Where the localhost hostname is defined
zone "localhost" IN {
// a master type means that this server needn't look
// anywhere else for information; the localhost buck
// stops here.
type master;
file "/etc/bind/db.local";
// don't allow dynamic DNS clients to update info
// about the localhost zone
allow-update { none; };
};

// Where the 127.0.0.0 network is defined
zone "127.in-addr.arpa" IN {
type master;
file "/etc/bind/db.127";
allow-update { none; };
};

zone "0.in-addr.arpa" IN {
type master;
file "/etc/bind/db.0";
allow-update { none; };
};

zone "255.in-addr.arpa" IN {
type master;
file "/etc/bind/db.255";
allow-update { none; };
};

// Include logging config file
include "/etc/bind/logging.conf";

// zone "com" { type delegation-only; };
// zone "net" { type delegation-only; };

// From the release notes:
// Because many of our users are uncomfortable receiving undelegated answers
// from root or top level domains, other than a few for whom that behaviour
// has been trusted and expected for quite some length of time, we have now
// introduced the "root-delegations-only" feature which applies delegation-only
// logic to all top level domains, and to the root domain. An exception list
// should be specified, including "MUSEUM" and "DE", and any other top level
// domains from whom undelegated responses are expected and trusted.
// root-delegation-only exclude { "DE"; "MUSEUM"; };

include "/etc/bind/named.conf.local";
</pre>

===/etc/bind/named.conf.options===
<pre>
options {
// tell named where to find files mentioned below
directory "/var/cache/bind";

// file that contains the process id when bind is running
pid-file "/var/run/bind/run/named.pid";

// enable statistics
statistics-file "/var/named/named.stats";
zone-statistics yes;

dump-file "/var/named/named.dump";

// If there is a firewall between you and nameservers you want
// to talk to, you might need to uncomment the query-source
// directive below. Previous versions of BIND always asked
// questions using port 53, but BIND 8.1 and later use an unprivileged
// port by default.
// query-source address * port 53;

// If your ISP provided one or more IP addresses for stable
// nameservers, you probably want to use them as forwarders.
// Uncomment the following block, and insert the addresses replacing
// the all-0's placeholder.

// The forwarders option tells BIND to not use iterative queries itself
// for information it doesn’t already know about but to forward a
// recursive query to the name servers specified instead.
include "/etc/bind/named.conf.forwarders";

// conform to RFC1035
auth-nxdomain no;

// on a multi-homed host, you might want to tell named
// to listen for queries only on certain interfaces
listen-on-v6 { any; };
listen-on { "internal-net"; };

// to allow only specific hosts to use the DNS server:
allow-query { "internal-net"; };

// sets BIND’s default behaviour to refuse all zone transfers.
// Without setting this option, anyone can transfer any zone.
allow-transfer { none; };

// do not generate notify messages for all zones on a restart.
// override for authorative zones
notify no;
};
</pre>

===/etc/bind/logging.conf===
<pre>
logging {

channel default_file {
file "/var/log/named/default.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel general_file {
file "/var/log/named/general.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel database_file {
file "/var/log/named/database.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel security_file {
file "/var/log/named/security.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel config_file {
file "/var/log/named/config.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel resolver_file {
file "/var/log/named/resolver.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-in_file {
file "/var/log/named/xfer-in.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-out_file {
file "/var/log/named/xfer-out.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel notify_file {
file "/var/log/named/notify.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel client_file {
file "/var/log/named/client.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel unmatched_file {
file "/var/log/named/unmatched.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel queries_file {
file "/var/log/named/queries.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel network_file {
file "/var/log/named/network.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel update_file {
file "/var/log/named/update.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dispatch_file {
file "/var/log/named/dispatch.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dnssec_file {
file "/var/log/named/dnssec.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel lame-servers_file {
file "/var/log/named/lame-servers.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};

category lame-servers {
lame-servers_file;
};
category dnssec {
dnssec_file;
};
category dispatch {
dispatch_file;
};
category update {
update_file;
};
category network {
network_file;
};
category queries {
queries_file;
};
category unmatched {
unmatched_file;
};
category client {
client_file;
};
category notify {
notify_file;
};
category xfer-out {
xfer-out_file;
};
category xfer-in {
xfer-in_file;
};
category resolver {
resolver_file;
};
category config {
config_file;
};
category security {
security_file;
};
category database {
database_file;
};
category general {
general_file;
};
category default {
default_file;
};
};
</pre>

===/etc/bind/rndc.conf===
<pre>
options {
default-server localhost;
default-key "rndc-key";
default-port 953;
};

server localhost {
key "rndc-key";
};

key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/rndc.key===
<pre>
key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-ns2" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/db.wright.local.zone===
<pre>
;
; BIND data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; Address records specify an IP address to assign to a name
;
dcerouter IN A 192.168.80.1
dad-kubuntu IN A 192.168.80.21
royw-gentoo IN A 192.168.80.20
;
; Canonical name records, maps one name to another.
;
linuxmce IN CNAME dcerouter
</pre>

===/etc/bind/db.wright.local.rev===
<pre>

;
; BIND reverse data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$ORIGIN 80.168.192.in-addr.arpa.
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; PTR — PoinTeR record, designed to point to another part of the namespace.
;
1 IN PTR dcerouter.wright.local.
21 IN PTR dad-kubuntu.wright.local.
20 IN PTR royw-gentoo.wright.local.
</pre>

===/etc/dhcp3/dhcpd.conf===
<pre>
option domain-name-servers 192.168.80.1;
authoritative;

option routers 192.168.80.1;
option subnet-mask 255.255.255.0;

# lease IPs for 1 day, maximum 1 week
default-lease-time 86400;
max-lease-time 604800;

# dynamic DNS updates
ddns-updates on;
ddns-update-style interim;
ddns-domainname "wright.local.";
ddns-rev-domainname "in-addr.arpa.";
ddns-ttl 14400;

# don't let clients modify their own A records
ignore client-updates;

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

zone wright.local {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

zone 80.168.192.in-addr.arpa {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

option space pxelinux;
option pxelinux.magic code 208 = string;
option pxelinux.configfile code 209 = text;
option pxelinux.pathprefix code 210 = text;
option pxelinux.reboottime code 211 = unsigned integer 32;

subnet 192.168.80.0 netmask 255.255.255.0 {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

option domain-name "wright.local";
option domain-name-servers 192.168.80.1;
option routers 192.168.80.1;

default-lease-time 86400;
max-lease-time 604800;
pool {
allow unknown-clients;
range 192.168.80.129 192.168.80.254;
}
}

# PXE booting machines
group {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

}

# regular machines
group {
}

# CORE (1) has bad mac address:

</pre>

===/etc/resolv.conf===
<pre>
domain wright.local
nameserver localhost
</pre>

How to setup Local Authoritative DNS

2008-09-05T22:29:01Z

Juanfe: /* Installation */

[[category: Tutorials]]
=How to setup Local Authoritative DNS=

I was wanting an authoritative name server for my local intranet. I also wanted any dynamic IP's to be visible to the name server. The name server included with linuxmce is configured as a recursive name server. Here's the changes I did to configure my core's name server to be authoritative and support dynamic IPs. Note, the machines on my intranet are private, i.e., not known to the outside world.

3 Feb 2008 - Developed and tested on LinuxMCE 0710 Beta 3 amd64.

I named my intranet "wright.local". Using a "local" top level domain (TLD) is recommended for private intranets. Some may prefer to use "lan". You do not want to use any of the standard TLDs like "com", "net", "org",...

I used the core's default intranet addresses, 192.168.80.0/24 with the core at 192.168.80.1.

I've attempted to verbosely document each config file. :)

The directions for adapting the config files are included in the named.conf file.

==Installation==

If you want to try this, I would suggest building the config in new directories then swapping with the originals when you are ready (I had a little mess when my core hung and I had to restart with only half the configs ready) :)

So start with creating two directories:

sudo mkdir /etc/bind.new
sudo mkdir /etc/dhcp3.new

Now copy the contents of the original directories:

sudo cp -arp /etc/bind/* /etc/bind.new
sudo cp -arp /etc/dhcp3/* /etc/dhcp3.new

Also create a new resolve.conf file:

sudo touch /etc/resolv.conf.new

You will be creating or editing the following config files in these new directories:

/etc/bind.new/named.conf
/etc/bind.new/named.conf.options
/etc/bind.new/logging.conf
/etc/bind.new/rndc.conf
/etc/bind.new/rndc.key
/etc/bind.new/db.wright.local.zone
/etc/bind.new/db.wright.local.rev
/etc/dhcp3.new/dhcpd.conf
/etc/resolv.conf

The full text of the files you will be editing is at the foot of this page. The original author named his network "wright"; you should replace all instances of "wright" with the name of your network.

==Notes on Editing Files==

===rndc.key and dhcpd.conf key values===

To create a key for use in rndc.key and dhcpd.conf:

sudo dnssec-keygen -a HMAC-MD5 -b 256 -n user rndc

Now get the key from the private file:

sudo cat Krndc.*.private
Private-key-format: v1.2
Algorithm: 157 (HMAC_MD5)
Key: 3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=
Bits: AAA=

Now cut the key which is to the right of "Key: " and paste where needed (replace "<paste your key here>" with the key in the config files). So an example using the above key would look like:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

becomes:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=";
};

===Check directory ownership===
Make the logging directory:

sudo mkdir /var/log/named
sudo chown bind:bind /var/log/named
sudo chmod 755 /var/log/named

You probably ought to check and change the defaultdomain:

domainname

will probably show

pluto

if so, then set it by:
sudo domainname yourdomain.local

where "yourdomain.local" is your domain. :-)

===File Permissions===
Change all the file permissions per instructions in named.conf.

Double check everything. Roll Eyes

==Wrapping up==
When and if you are feeling lucky, rename the original directories and then rename the new directories to take their place:

sudo mv /etc/bind /etc/bind.original
sudo mv /etc/bind.new /etc/bind
sudo mv /etc/dhcp3 /etc/dhcp3.original
sudo mv /etc/dhcp3.new /etc/dhcp3
sudo mv /etc/resolve.conf /etc/resolve.conf.original
sudo mv /etc/resolve.conf.new /etc/resolve.conf

Finally restart the bind and dhcpd services:

sudo rndc reload
sudo /etc/init.d/dhcp3-server restart

Check the syslog for any errors:

grep named /var/log/syslog
grep dhcpd /var/log/syslog

==Config Files==

===/etc/bind/named.conf===
<pre>
// This is the primary configuration file for the BIND DNS server named.
//
// This configuration supports an authoritative local zone (wright.local on
// 192.168.80.0/24) and allows DHCP to update the local zone.
// To customize to your setup:
// 1) replace "wright.local" with your internal domain name.
// 2) edit db.wright.local.zone and db.wright.local.rev and replace
// my static names/addresses with your network's static names/addresses.
// Make sure to increment the serial number of any file edited.
// Note, format of serial number is: YYYYMMDDNN where YYYY is year,
// MM is month, DD is day, NN is update number for that day (i.e., 01,
// 02, 03,...)
// 3) rename db.wright.local.zone to match your domain name.
// 4) rename db.wright.local.rev to match your domain name.
// 5) If you changed the internal network IP from the LinuxMCE default of
// 192.168.80.0/24, then replace "192.168.80" with your network
// ip and replace it's reverse "80.168.192" wity your network ip's
// reverse.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
//
// references:
// http://www.arda.homeunix.net/dnssetup.html
// http://www.madboa.com/geek/soho-bind/
//
// notes:
// 1) The following command should be ran about twice a year to keep
// the root servers current:
// dig @a.root-servers.net . ns > /etc/bin/db.root
// Root name servers don’t change very often so updating this file more
// than twice a year is probably overkill. Frequent updates also put undo
// load on the root name servers; they have enough to do as it is.
//
// 2) File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//
// Manually Updating Zone Files
// 1. Use rndc to stop BIND.
// sudo rndc stop
// 2. Remove any .jnl files from the zone file directory.
// sudo rm /etc/bind/*.jnl
// 3. Edit the zone files as necessary. Make sure to increment the serial
// number of any file edited. Note, format of serial number is:
// YYYYMMDDNN where YYYY is year, MM is month, DD is day, NN is update
// number for that day (i.e., 01, 02, 03,...)
// 4. Start BIND using its startup script.
// sudo /etc/init.d/bind9 start

// secret must be the same as in /etc/bind/rndc.conf
include "/etc/bind/rndc.key";

// access control list used to limit queries to local net
acl "internal-net" { 192.168.80/24; 127.0.0.1; };

controls {
inet 127.0.0.1 allow { any; } keys { "rndc-key"; };
};

include "/etc/bind/named.conf.options";

// The single dot (.) is the root of all DNS namespace, so
// this zone tells named where to start looking for any
// name on the Internet
zone "." IN {
type hint;
file "/etc/bind/db.root";
};

// local intranet zones and reverse zones
// intranet is wright.local and 192.168.80.0/24
// the DHCP servers is on linuxmce-dhcp
// an optional second nameserver would be on linuxmce-ns2

zone "wright.local" IN {
type master;
file "/etc/bind/db.wright.local.zone";
// both allow-update and update-policy can enable DHCP updates,
// but update-policy allows more control over what kinds of
// updates DHCP can perform on a zone.
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain wright.local. A TXT; };
// allow-transfer { key "linuxmce-ns2"; };
// notify on zone transfers
notify yes;
};

zone "80.168.192.in-addr.arpa" IN {
type master;
file "/etc/bind/db.wright.local.rev";
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain 80.168.192.in-addr.arpa. PTR TXT; };
// allow-transfer { key "linuxmce-ns2"; };
notify yes;
};

// be authoritative for the localhost forward and reverse zones, and for
// broadcast zones as per RFC 1912 (http://www.ietf.org/rfc/rfc1912.txt)

// Where the localhost hostname is defined
zone "localhost" IN {
// a master type means that this server needn't look
// anywhere else for information; the localhost buck
// stops here.
type master;
file "/etc/bind/db.local";
// don't allow dynamic DNS clients to update info
// about the localhost zone
allow-update { none; };
};

// Where the 127.0.0.0 network is defined
zone "127.in-addr.arpa" IN {
type master;
file "/etc/bind/db.127";
allow-update { none; };
};

zone "0.in-addr.arpa" IN {
type master;
file "/etc/bind/db.0";
allow-update { none; };
};

zone "255.in-addr.arpa" IN {
type master;
file "/etc/bind/db.255";
allow-update { none; };
};

// Include logging config file
include "/etc/bind/logging.conf";

// zone "com" { type delegation-only; };
// zone "net" { type delegation-only; };

// From the release notes:
// Because many of our users are uncomfortable receiving undelegated answers
// from root or top level domains, other than a few for whom that behaviour
// has been trusted and expected for quite some length of time, we have now
// introduced the "root-delegations-only" feature which applies delegation-only
// logic to all top level domains, and to the root domain. An exception list
// should be specified, including "MUSEUM" and "DE", and any other top level
// domains from whom undelegated responses are expected and trusted.
// root-delegation-only exclude { "DE"; "MUSEUM"; };

include "/etc/bind/named.conf.local";
</pre>

===/etc/bind/named.conf.options===
<pre>
options {
// tell named where to find files mentioned below
directory "/var/cache/bind";

// file that contains the process id when bind is running
pid-file "/var/run/bind/run/named.pid";

// enable statistics
statistics-file "/var/named/named.stats";
zone-statistics yes;

dump-file "/var/named/named.dump";

// If there is a firewall between you and nameservers you want
// to talk to, you might need to uncomment the query-source
// directive below. Previous versions of BIND always asked
// questions using port 53, but BIND 8.1 and later use an unprivileged
// port by default.
// query-source address * port 53;

// If your ISP provided one or more IP addresses for stable
// nameservers, you probably want to use them as forwarders.
// Uncomment the following block, and insert the addresses replacing
// the all-0's placeholder.

// The forwarders option tells BIND to not use iterative queries itself
// for information it doesn’t already know about but to forward a
// recursive query to the name servers specified instead.
include "/etc/bind/named.conf.forwarders";

// conform to RFC1035
auth-nxdomain no;

// on a multi-homed host, you might want to tell named
// to listen for queries only on certain interfaces
listen-on-v6 { any; };
listen-on { "internal-net"; };

// to allow only specific hosts to use the DNS server:
allow-query { "internal-net"; };

// sets BIND’s default behaviour to refuse all zone transfers.
// Without setting this option, anyone can transfer any zone.
allow-transfer { none; };

// do not generate notify messages for all zones on a restart.
// override for authorative zones
notify no;
};
</pre>

===/etc/bind/logging.conf===
<pre>
logging {

channel default_file {
file "/var/log/named/default.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel general_file {
file "/var/log/named/general.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel database_file {
file "/var/log/named/database.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel security_file {
file "/var/log/named/security.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel config_file {
file "/var/log/named/config.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel resolver_file {
file "/var/log/named/resolver.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-in_file {
file "/var/log/named/xfer-in.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-out_file {
file "/var/log/named/xfer-out.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel notify_file {
file "/var/log/named/notify.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel client_file {
file "/var/log/named/client.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel unmatched_file {
file "/var/log/named/unmatched.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel queries_file {
file "/var/log/named/queries.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel network_file {
file "/var/log/named/network.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel update_file {
file "/var/log/named/update.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dispatch_file {
file "/var/log/named/dispatch.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dnssec_file {
file "/var/log/named/dnssec.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel lame-servers_file {
file "/var/log/named/lame-servers.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};

category lame-servers {
lame-servers_file;
};
category dnssec {
dnssec_file;
};
category dispatch {
dispatch_file;
};
category update {
update_file;
};
category network {
network_file;
};
category queries {
queries_file;
};
category unmatched {
unmatched_file;
};
category client {
client_file;
};
category notify {
notify_file;
};
category xfer-out {
xfer-out_file;
};
category xfer-in {
xfer-in_file;
};
category resolver {
resolver_file;
};
category config {
config_file;
};
category security {
security_file;
};
category database {
database_file;
};
category general {
general_file;
};
category default {
default_file;
};
};
</pre>

===/etc/bind/rndc.conf===
<pre>
options {
default-server localhost;
default-key "rndc-key";
default-port 953;
};

server localhost {
key "rndc-key";
};

key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/rndc.key===
<pre>
key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-ns2" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/db.wright.local.zone===
<pre>
;
; BIND data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; Address records specify an IP address to assign to a name
;
dcerouter IN A 192.168.80.1
dad-kubuntu IN A 192.168.80.21
royw-gentoo IN A 192.168.80.20
;
; Canonical name records, maps one name to another.
;
linuxmce IN CNAME dcerouter
</pre>

===/etc/bind/db.wright.local.rev===
<pre>

;
; BIND reverse data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$ORIGIN 80.168.192.in-addr.arpa.
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; PTR — PoinTeR record, designed to point to another part of the namespace.
;
1 IN PTR dcerouter.wright.local.
21 IN PTR dad-kubuntu.wright.local.
20 IN PTR royw-gentoo.wright.local.
</pre>

===/etc/dhcp3/dhcpd.conf===
<pre>
option domain-name-servers 192.168.80.1;
authoritative;

option routers 192.168.80.1;
option subnet-mask 255.255.255.0;

# lease IPs for 1 day, maximum 1 week
default-lease-time 86400;
max-lease-time 604800;

# dynamic DNS updates
ddns-updates on;
ddns-update-style interim;
ddns-domainname "wright.local.";
ddns-rev-domainname "in-addr.arpa.";
ddns-ttl 14400;

# don't let clients modify their own A records
ignore client-updates;

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

zone wright.local {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

zone 80.168.192.in-addr.arpa {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

option space pxelinux;
option pxelinux.magic code 208 = string;
option pxelinux.configfile code 209 = text;
option pxelinux.pathprefix code 210 = text;
option pxelinux.reboottime code 211 = unsigned integer 32;

subnet 192.168.80.0 netmask 255.255.255.0 {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

option domain-name "wright.local";
option domain-name-servers 192.168.80.1;
option routers 192.168.80.1;

default-lease-time 86400;
max-lease-time 604800;
pool {
allow unknown-clients;
range 192.168.80.129 192.168.80.254;
}
}

# PXE booting machines
group {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

}

# regular machines
group {
}

# CORE (1) has bad mac address:

</pre>

===/etc/resolv.conf===
<pre>
domain wright.local
nameserver localhost
</pre>

How to setup Local Authoritative DNS

2008-09-05T22:27:35Z

Juanfe: /* After Editing Files */

[[category: Tutorials]]
=How to setup Local Authoritative DNS=

I was wanting an authoritative name server for my local intranet. I also wanted any dynamic IP's to be visible to the name server. The name server included with linuxmce is configured as a recursive name server. Here's the changes I did to configure my core's name server to be authoritative and support dynamic IPs. Note, the machines on my intranet are private, i.e., not known to the outside world.

3 Feb 2008 - Developed and tested on LinuxMCE 0710 Beta 3 amd64.

I named my intranet "wright.local". Using a "local" top level domain (TLD) is recommended for private intranets. Some may prefer to use "lan". You do not want to use any of the standard TLDs like "com", "net", "org",...

I used the core's default intranet addresses, 192.168.80.0/24 with the core at 192.168.80.1.

I've attempted to verbosely document each config file. :)

The directions for adapting the config files are included in the named.conf file.

==Installation==

If you want to try this, I would suggest building the config in new directories then swapping with the originals when you are ready (I had a little mess when my core hung and I had to restart with only half the configs ready) :)

So start with creating two directories:

sudo mkdir /etc/bind.new
sudo mkdir /etc/dhcp3.new

Now copy the contents of the original directories:

sudo cp -arp /etc/bind/* /etc/bind.new
sudo cp -arp /etc/dhcp3/* /etc/dhcp3.new

Also create a new resolve.conf file:

sudo touch /etc/resolv.conf.new

You will be creating or editing the following config files in these new directories, as described below:

/etc/bind.new/named.conf
/etc/bind.new/named.conf.options
/etc/bind.new/logging.conf
/etc/bind.new/rndc.conf
/etc/bind.new/rndc.key
/etc/bind.new/db.yournetworkname.local.zone
/etc/bind.new/db.yournetworkname.local.rev
/etc/dhcp3.new/dhcpd.conf
/etc/resolv.conf

==Notes on Editing Files==

===rndc.key and dhcpd.conf key values===

To create a key for use in rndc.key and dhcpd.conf:

sudo dnssec-keygen -a HMAC-MD5 -b 256 -n user rndc

Now get the key from the private file:

sudo cat Krndc.*.private
Private-key-format: v1.2
Algorithm: 157 (HMAC_MD5)
Key: 3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=
Bits: AAA=

Now cut the key which is to the right of "Key: " and paste where needed (replace "<paste your key here>" with the key in the config files). So an example using the above key would look like:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

becomes:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=";
};

===Check directory ownership===
Make the logging directory:

sudo mkdir /var/log/named
sudo chown bind:bind /var/log/named
sudo chmod 755 /var/log/named

You probably ought to check and change the defaultdomain:

domainname

will probably show

pluto

if so, then set it by:
sudo domainname yourdomain.local

where "yourdomain.local" is your domain. :-)

===File Permissions===
Change all the file permissions per instructions in named.conf.

Double check everything. Roll Eyes

==Wrapping up==
When and if you are feeling lucky, rename the original directories and then rename the new directories to take their place:

sudo mv /etc/bind /etc/bind.original
sudo mv /etc/bind.new /etc/bind
sudo mv /etc/dhcp3 /etc/dhcp3.original
sudo mv /etc/dhcp3.new /etc/dhcp3
sudo mv /etc/resolve.conf /etc/resolve.conf.original
sudo mv /etc/resolve.conf.new /etc/resolve.conf

Finally restart the bind and dhcpd services:

sudo rndc reload
sudo /etc/init.d/dhcp3-server restart

Check the syslog for any errors:

grep named /var/log/syslog
grep dhcpd /var/log/syslog

==Config Files==

===/etc/bind/named.conf===
<pre>
// This is the primary configuration file for the BIND DNS server named.
//
// This configuration supports an authoritative local zone (wright.local on
// 192.168.80.0/24) and allows DHCP to update the local zone.
// To customize to your setup:
// 1) replace "wright.local" with your internal domain name.
// 2) edit db.wright.local.zone and db.wright.local.rev and replace
// my static names/addresses with your network's static names/addresses.
// Make sure to increment the serial number of any file edited.
// Note, format of serial number is: YYYYMMDDNN where YYYY is year,
// MM is month, DD is day, NN is update number for that day (i.e., 01,
// 02, 03,...)
// 3) rename db.wright.local.zone to match your domain name.
// 4) rename db.wright.local.rev to match your domain name.
// 5) If you changed the internal network IP from the LinuxMCE default of
// 192.168.80.0/24, then replace "192.168.80" with your network
// ip and replace it's reverse "80.168.192" wity your network ip's
// reverse.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
//
// references:
// http://www.arda.homeunix.net/dnssetup.html
// http://www.madboa.com/geek/soho-bind/
//
// notes:
// 1) The following command should be ran about twice a year to keep
// the root servers current:
// dig @a.root-servers.net . ns > /etc/bin/db.root
// Root name servers don’t change very often so updating this file more
// than twice a year is probably overkill. Frequent updates also put undo
// load on the root name servers; they have enough to do as it is.
//
// 2) File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//
// Manually Updating Zone Files
// 1. Use rndc to stop BIND.
// sudo rndc stop
// 2. Remove any .jnl files from the zone file directory.
// sudo rm /etc/bind/*.jnl
// 3. Edit the zone files as necessary. Make sure to increment the serial
// number of any file edited. Note, format of serial number is:
// YYYYMMDDNN where YYYY is year, MM is month, DD is day, NN is update
// number for that day (i.e., 01, 02, 03,...)
// 4. Start BIND using its startup script.
// sudo /etc/init.d/bind9 start

// secret must be the same as in /etc/bind/rndc.conf
include "/etc/bind/rndc.key";

// access control list used to limit queries to local net
acl "internal-net" { 192.168.80/24; 127.0.0.1; };

controls {
inet 127.0.0.1 allow { any; } keys { "rndc-key"; };
};

include "/etc/bind/named.conf.options";

// The single dot (.) is the root of all DNS namespace, so
// this zone tells named where to start looking for any
// name on the Internet
zone "." IN {
type hint;
file "/etc/bind/db.root";
};

// local intranet zones and reverse zones
// intranet is wright.local and 192.168.80.0/24
// the DHCP servers is on linuxmce-dhcp
// an optional second nameserver would be on linuxmce-ns2

zone "wright.local" IN {
type master;
file "/etc/bind/db.wright.local.zone";
// both allow-update and update-policy can enable DHCP updates,
// but update-policy allows more control over what kinds of
// updates DHCP can perform on a zone.
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain wright.local. A TXT; };
// allow-transfer { key "linuxmce-ns2"; };
// notify on zone transfers
notify yes;
};

zone "80.168.192.in-addr.arpa" IN {
type master;
file "/etc/bind/db.wright.local.rev";
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain 80.168.192.in-addr.arpa. PTR TXT; };
// allow-transfer { key "linuxmce-ns2"; };
notify yes;
};

// be authoritative for the localhost forward and reverse zones, and for
// broadcast zones as per RFC 1912 (http://www.ietf.org/rfc/rfc1912.txt)

// Where the localhost hostname is defined
zone "localhost" IN {
// a master type means that this server needn't look
// anywhere else for information; the localhost buck
// stops here.
type master;
file "/etc/bind/db.local";
// don't allow dynamic DNS clients to update info
// about the localhost zone
allow-update { none; };
};

// Where the 127.0.0.0 network is defined
zone "127.in-addr.arpa" IN {
type master;
file "/etc/bind/db.127";
allow-update { none; };
};

zone "0.in-addr.arpa" IN {
type master;
file "/etc/bind/db.0";
allow-update { none; };
};

zone "255.in-addr.arpa" IN {
type master;
file "/etc/bind/db.255";
allow-update { none; };
};

// Include logging config file
include "/etc/bind/logging.conf";

// zone "com" { type delegation-only; };
// zone "net" { type delegation-only; };

// From the release notes:
// Because many of our users are uncomfortable receiving undelegated answers
// from root or top level domains, other than a few for whom that behaviour
// has been trusted and expected for quite some length of time, we have now
// introduced the "root-delegations-only" feature which applies delegation-only
// logic to all top level domains, and to the root domain. An exception list
// should be specified, including "MUSEUM" and "DE", and any other top level
// domains from whom undelegated responses are expected and trusted.
// root-delegation-only exclude { "DE"; "MUSEUM"; };

include "/etc/bind/named.conf.local";
</pre>

===/etc/bind/named.conf.options===
<pre>
options {
// tell named where to find files mentioned below
directory "/var/cache/bind";

// file that contains the process id when bind is running
pid-file "/var/run/bind/run/named.pid";

// enable statistics
statistics-file "/var/named/named.stats";
zone-statistics yes;

dump-file "/var/named/named.dump";

// If there is a firewall between you and nameservers you want
// to talk to, you might need to uncomment the query-source
// directive below. Previous versions of BIND always asked
// questions using port 53, but BIND 8.1 and later use an unprivileged
// port by default.
// query-source address * port 53;

// If your ISP provided one or more IP addresses for stable
// nameservers, you probably want to use them as forwarders.
// Uncomment the following block, and insert the addresses replacing
// the all-0's placeholder.

// The forwarders option tells BIND to not use iterative queries itself
// for information it doesn’t already know about but to forward a
// recursive query to the name servers specified instead.
include "/etc/bind/named.conf.forwarders";

// conform to RFC1035
auth-nxdomain no;

// on a multi-homed host, you might want to tell named
// to listen for queries only on certain interfaces
listen-on-v6 { any; };
listen-on { "internal-net"; };

// to allow only specific hosts to use the DNS server:
allow-query { "internal-net"; };

// sets BIND’s default behaviour to refuse all zone transfers.
// Without setting this option, anyone can transfer any zone.
allow-transfer { none; };

// do not generate notify messages for all zones on a restart.
// override for authorative zones
notify no;
};
</pre>

===/etc/bind/logging.conf===
<pre>
logging {

channel default_file {
file "/var/log/named/default.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel general_file {
file "/var/log/named/general.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel database_file {
file "/var/log/named/database.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel security_file {
file "/var/log/named/security.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel config_file {
file "/var/log/named/config.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel resolver_file {
file "/var/log/named/resolver.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-in_file {
file "/var/log/named/xfer-in.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-out_file {
file "/var/log/named/xfer-out.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel notify_file {
file "/var/log/named/notify.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel client_file {
file "/var/log/named/client.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel unmatched_file {
file "/var/log/named/unmatched.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel queries_file {
file "/var/log/named/queries.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel network_file {
file "/var/log/named/network.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel update_file {
file "/var/log/named/update.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dispatch_file {
file "/var/log/named/dispatch.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dnssec_file {
file "/var/log/named/dnssec.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel lame-servers_file {
file "/var/log/named/lame-servers.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};

category lame-servers {
lame-servers_file;
};
category dnssec {
dnssec_file;
};
category dispatch {
dispatch_file;
};
category update {
update_file;
};
category network {
network_file;
};
category queries {
queries_file;
};
category unmatched {
unmatched_file;
};
category client {
client_file;
};
category notify {
notify_file;
};
category xfer-out {
xfer-out_file;
};
category xfer-in {
xfer-in_file;
};
category resolver {
resolver_file;
};
category config {
config_file;
};
category security {
security_file;
};
category database {
database_file;
};
category general {
general_file;
};
category default {
default_file;
};
};
</pre>

===/etc/bind/rndc.conf===
<pre>
options {
default-server localhost;
default-key "rndc-key";
default-port 953;
};

server localhost {
key "rndc-key";
};

key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/rndc.key===
<pre>
key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-ns2" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/db.wright.local.zone===
<pre>
;
; BIND data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; Address records specify an IP address to assign to a name
;
dcerouter IN A 192.168.80.1
dad-kubuntu IN A 192.168.80.21
royw-gentoo IN A 192.168.80.20
;
; Canonical name records, maps one name to another.
;
linuxmce IN CNAME dcerouter
</pre>

===/etc/bind/db.wright.local.rev===
<pre>

;
; BIND reverse data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$ORIGIN 80.168.192.in-addr.arpa.
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; PTR — PoinTeR record, designed to point to another part of the namespace.
;
1 IN PTR dcerouter.wright.local.
21 IN PTR dad-kubuntu.wright.local.
20 IN PTR royw-gentoo.wright.local.
</pre>

===/etc/dhcp3/dhcpd.conf===
<pre>
option domain-name-servers 192.168.80.1;
authoritative;

option routers 192.168.80.1;
option subnet-mask 255.255.255.0;

# lease IPs for 1 day, maximum 1 week
default-lease-time 86400;
max-lease-time 604800;

# dynamic DNS updates
ddns-updates on;
ddns-update-style interim;
ddns-domainname "wright.local.";
ddns-rev-domainname "in-addr.arpa.";
ddns-ttl 14400;

# don't let clients modify their own A records
ignore client-updates;

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

zone wright.local {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

zone 80.168.192.in-addr.arpa {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

option space pxelinux;
option pxelinux.magic code 208 = string;
option pxelinux.configfile code 209 = text;
option pxelinux.pathprefix code 210 = text;
option pxelinux.reboottime code 211 = unsigned integer 32;

subnet 192.168.80.0 netmask 255.255.255.0 {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

option domain-name "wright.local";
option domain-name-servers 192.168.80.1;
option routers 192.168.80.1;

default-lease-time 86400;
max-lease-time 604800;
pool {
allow unknown-clients;
range 192.168.80.129 192.168.80.254;
}
}

# PXE booting machines
group {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

}

# regular machines
group {
}

# CORE (1) has bad mac address:

</pre>

===/etc/resolv.conf===
<pre>
domain wright.local
nameserver localhost
</pre>

How to setup Local Authoritative DNS

2008-09-05T22:24:44Z

Juanfe: /* Installation */

[[category: Tutorials]]
=How to setup Local Authoritative DNS=

I was wanting an authoritative name server for my local intranet. I also wanted any dynamic IP's to be visible to the name server. The name server included with linuxmce is configured as a recursive name server. Here's the changes I did to configure my core's name server to be authoritative and support dynamic IPs. Note, the machines on my intranet are private, i.e., not known to the outside world.

3 Feb 2008 - Developed and tested on LinuxMCE 0710 Beta 3 amd64.

I named my intranet "wright.local". Using a "local" top level domain (TLD) is recommended for private intranets. Some may prefer to use "lan". You do not want to use any of the standard TLDs like "com", "net", "org",...

I used the core's default intranet addresses, 192.168.80.0/24 with the core at 192.168.80.1.

I've attempted to verbosely document each config file. :)

The directions for adapting the config files are included in the named.conf file.

==Installation==

If you want to try this, I would suggest building the config in new directories then swapping with the originals when you are ready (I had a little mess when my core hung and I had to restart with only half the configs ready) :)

So start with creating two directories:

sudo mkdir /etc/bind.new
sudo mkdir /etc/dhcp3.new

Now copy the contents of the original directories:

sudo cp -arp /etc/bind/* /etc/bind.new
sudo cp -arp /etc/dhcp3/* /etc/dhcp3.new

Also create a new resolve.conf file:

sudo touch /etc/resolv.conf.new

You will be creating or editing the following config files in these new directories, as described below:

/etc/bind.new/named.conf
/etc/bind.new/named.conf.options
/etc/bind.new/logging.conf
/etc/bind.new/rndc.conf
/etc/bind.new/rndc.key
/etc/bind.new/db.yournetworkname.local.zone
/etc/bind.new/db.yournetworkname.local.rev
/etc/dhcp3.new/dhcpd.conf
/etc/resolv.conf

==After Editing Files==

Make the logging directory:

sudo mkdir /var/log/named
sudo chown bind:bind /var/log/named
sudo chmod 755 /var/log/named

You probably ought to check and change the defaultdomain:

domainname

will probably show

pluto

if so, then set it by:
sudo domainname yourdomain.local

where "yourdomain.local" is your domain. :-)

Change all the file permissions per instructions in named.conf.

Double check everything. Roll Eyes

Then when you are feeling lucky, rename the original directories and then rename the new directories to take there place:

sudo mv /etc/bind /etc/bind.original
sudo mv /etc/bind.new /etc/bind
sudo mv /etc/dhcp3 /etc/dhcp3.original
sudo mv /etc/dhcp3.new /etc/dhcp3
sudo mv /etc/resolve.conf /etc/resolve.conf.original
sudo mv /etc/resolve.conf.new /etc/resolve.conf

Finally restart the bind and dhcpd services:

sudo rndc reload
sudo /etc/init.d/dhcp3-server restart

Check the syslog for any errors:

grep named /var/log/syslog
grep dhcpd /var/log/syslog

==Config Files==

===/etc/bind/named.conf===
<pre>
// This is the primary configuration file for the BIND DNS server named.
//
// This configuration supports an authoritative local zone (wright.local on
// 192.168.80.0/24) and allows DHCP to update the local zone.
// To customize to your setup:
// 1) replace "wright.local" with your internal domain name.
// 2) edit db.wright.local.zone and db.wright.local.rev and replace
// my static names/addresses with your network's static names/addresses.
// Make sure to increment the serial number of any file edited.
// Note, format of serial number is: YYYYMMDDNN where YYYY is year,
// MM is month, DD is day, NN is update number for that day (i.e., 01,
// 02, 03,...)
// 3) rename db.wright.local.zone to match your domain name.
// 4) rename db.wright.local.rev to match your domain name.
// 5) If you changed the internal network IP from the LinuxMCE default of
// 192.168.80.0/24, then replace "192.168.80" with your network
// ip and replace it's reverse "80.168.192" wity your network ip's
// reverse.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
//
// references:
// http://www.arda.homeunix.net/dnssetup.html
// http://www.madboa.com/geek/soho-bind/
//
// notes:
// 1) The following command should be ran about twice a year to keep
// the root servers current:
// dig @a.root-servers.net . ns > /etc/bin/db.root
// Root name servers don’t change very often so updating this file more
// than twice a year is probably overkill. Frequent updates also put undo
// load on the root name servers; they have enough to do as it is.
//
// 2) File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//
// Manually Updating Zone Files
// 1. Use rndc to stop BIND.
// sudo rndc stop
// 2. Remove any .jnl files from the zone file directory.
// sudo rm /etc/bind/*.jnl
// 3. Edit the zone files as necessary. Make sure to increment the serial
// number of any file edited. Note, format of serial number is:
// YYYYMMDDNN where YYYY is year, MM is month, DD is day, NN is update
// number for that day (i.e., 01, 02, 03,...)
// 4. Start BIND using its startup script.
// sudo /etc/init.d/bind9 start

// secret must be the same as in /etc/bind/rndc.conf
include "/etc/bind/rndc.key";

// access control list used to limit queries to local net
acl "internal-net" { 192.168.80/24; 127.0.0.1; };

controls {
inet 127.0.0.1 allow { any; } keys { "rndc-key"; };
};

include "/etc/bind/named.conf.options";

// The single dot (.) is the root of all DNS namespace, so
// this zone tells named where to start looking for any
// name on the Internet
zone "." IN {
type hint;
file "/etc/bind/db.root";
};

// local intranet zones and reverse zones
// intranet is wright.local and 192.168.80.0/24
// the DHCP servers is on linuxmce-dhcp
// an optional second nameserver would be on linuxmce-ns2

zone "wright.local" IN {
type master;
file "/etc/bind/db.wright.local.zone";
// both allow-update and update-policy can enable DHCP updates,
// but update-policy allows more control over what kinds of
// updates DHCP can perform on a zone.
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain wright.local. A TXT; };
// allow-transfer { key "linuxmce-ns2"; };
// notify on zone transfers
notify yes;
};

zone "80.168.192.in-addr.arpa" IN {
type master;
file "/etc/bind/db.wright.local.rev";
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain 80.168.192.in-addr.arpa. PTR TXT; };
// allow-transfer { key "linuxmce-ns2"; };
notify yes;
};

// be authoritative for the localhost forward and reverse zones, and for
// broadcast zones as per RFC 1912 (http://www.ietf.org/rfc/rfc1912.txt)

// Where the localhost hostname is defined
zone "localhost" IN {
// a master type means that this server needn't look
// anywhere else for information; the localhost buck
// stops here.
type master;
file "/etc/bind/db.local";
// don't allow dynamic DNS clients to update info
// about the localhost zone
allow-update { none; };
};

// Where the 127.0.0.0 network is defined
zone "127.in-addr.arpa" IN {
type master;
file "/etc/bind/db.127";
allow-update { none; };
};

zone "0.in-addr.arpa" IN {
type master;
file "/etc/bind/db.0";
allow-update { none; };
};

zone "255.in-addr.arpa" IN {
type master;
file "/etc/bind/db.255";
allow-update { none; };
};

// Include logging config file
include "/etc/bind/logging.conf";

// zone "com" { type delegation-only; };
// zone "net" { type delegation-only; };

// From the release notes:
// Because many of our users are uncomfortable receiving undelegated answers
// from root or top level domains, other than a few for whom that behaviour
// has been trusted and expected for quite some length of time, we have now
// introduced the "root-delegations-only" feature which applies delegation-only
// logic to all top level domains, and to the root domain. An exception list
// should be specified, including "MUSEUM" and "DE", and any other top level
// domains from whom undelegated responses are expected and trusted.
// root-delegation-only exclude { "DE"; "MUSEUM"; };

include "/etc/bind/named.conf.local";
</pre>

===/etc/bind/named.conf.options===
<pre>
options {
// tell named where to find files mentioned below
directory "/var/cache/bind";

// file that contains the process id when bind is running
pid-file "/var/run/bind/run/named.pid";

// enable statistics
statistics-file "/var/named/named.stats";
zone-statistics yes;

dump-file "/var/named/named.dump";

// If there is a firewall between you and nameservers you want
// to talk to, you might need to uncomment the query-source
// directive below. Previous versions of BIND always asked
// questions using port 53, but BIND 8.1 and later use an unprivileged
// port by default.
// query-source address * port 53;

// If your ISP provided one or more IP addresses for stable
// nameservers, you probably want to use them as forwarders.
// Uncomment the following block, and insert the addresses replacing
// the all-0's placeholder.

// The forwarders option tells BIND to not use iterative queries itself
// for information it doesn’t already know about but to forward a
// recursive query to the name servers specified instead.
include "/etc/bind/named.conf.forwarders";

// conform to RFC1035
auth-nxdomain no;

// on a multi-homed host, you might want to tell named
// to listen for queries only on certain interfaces
listen-on-v6 { any; };
listen-on { "internal-net"; };

// to allow only specific hosts to use the DNS server:
allow-query { "internal-net"; };

// sets BIND’s default behaviour to refuse all zone transfers.
// Without setting this option, anyone can transfer any zone.
allow-transfer { none; };

// do not generate notify messages for all zones on a restart.
// override for authorative zones
notify no;
};
</pre>

===/etc/bind/logging.conf===
<pre>
logging {

channel default_file {
file "/var/log/named/default.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel general_file {
file "/var/log/named/general.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel database_file {
file "/var/log/named/database.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel security_file {
file "/var/log/named/security.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel config_file {
file "/var/log/named/config.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel resolver_file {
file "/var/log/named/resolver.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-in_file {
file "/var/log/named/xfer-in.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-out_file {
file "/var/log/named/xfer-out.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel notify_file {
file "/var/log/named/notify.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel client_file {
file "/var/log/named/client.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel unmatched_file {
file "/var/log/named/unmatched.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel queries_file {
file "/var/log/named/queries.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel network_file {
file "/var/log/named/network.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel update_file {
file "/var/log/named/update.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dispatch_file {
file "/var/log/named/dispatch.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dnssec_file {
file "/var/log/named/dnssec.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel lame-servers_file {
file "/var/log/named/lame-servers.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};

category lame-servers {
lame-servers_file;
};
category dnssec {
dnssec_file;
};
category dispatch {
dispatch_file;
};
category update {
update_file;
};
category network {
network_file;
};
category queries {
queries_file;
};
category unmatched {
unmatched_file;
};
category client {
client_file;
};
category notify {
notify_file;
};
category xfer-out {
xfer-out_file;
};
category xfer-in {
xfer-in_file;
};
category resolver {
resolver_file;
};
category config {
config_file;
};
category security {
security_file;
};
category database {
database_file;
};
category general {
general_file;
};
category default {
default_file;
};
};
</pre>

===/etc/bind/rndc.conf===
<pre>
options {
default-server localhost;
default-key "rndc-key";
default-port 953;
};

server localhost {
key "rndc-key";
};

key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/rndc.key===
<pre>
key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-ns2" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/db.wright.local.zone===
<pre>
;
; BIND data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; Address records specify an IP address to assign to a name
;
dcerouter IN A 192.168.80.1
dad-kubuntu IN A 192.168.80.21
royw-gentoo IN A 192.168.80.20
;
; Canonical name records, maps one name to another.
;
linuxmce IN CNAME dcerouter
</pre>

===/etc/bind/db.wright.local.rev===
<pre>

;
; BIND reverse data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$ORIGIN 80.168.192.in-addr.arpa.
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; PTR — PoinTeR record, designed to point to another part of the namespace.
;
1 IN PTR dcerouter.wright.local.
21 IN PTR dad-kubuntu.wright.local.
20 IN PTR royw-gentoo.wright.local.
</pre>

===/etc/dhcp3/dhcpd.conf===
<pre>
option domain-name-servers 192.168.80.1;
authoritative;

option routers 192.168.80.1;
option subnet-mask 255.255.255.0;

# lease IPs for 1 day, maximum 1 week
default-lease-time 86400;
max-lease-time 604800;

# dynamic DNS updates
ddns-updates on;
ddns-update-style interim;
ddns-domainname "wright.local.";
ddns-rev-domainname "in-addr.arpa.";
ddns-ttl 14400;

# don't let clients modify their own A records
ignore client-updates;

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

zone wright.local {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

zone 80.168.192.in-addr.arpa {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

option space pxelinux;
option pxelinux.magic code 208 = string;
option pxelinux.configfile code 209 = text;
option pxelinux.pathprefix code 210 = text;
option pxelinux.reboottime code 211 = unsigned integer 32;

subnet 192.168.80.0 netmask 255.255.255.0 {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

option domain-name "wright.local";
option domain-name-servers 192.168.80.1;
option routers 192.168.80.1;

default-lease-time 86400;
max-lease-time 604800;
pool {
allow unknown-clients;
range 192.168.80.129 192.168.80.254;
}
}

# PXE booting machines
group {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

}

# regular machines
group {
}

# CORE (1) has bad mac address:

</pre>

===/etc/resolv.conf===
<pre>
domain wright.local
nameserver localhost
</pre>

How to setup Local Authoritative DNS

2008-09-05T22:20:38Z

Juanfe: /* Installation */

[[category: Tutorials]]
=How to setup Local Authoritative DNS=

I was wanting an authoritative name server for my local intranet. I also wanted any dynamic IP's to be visible to the name server. The name server included with linuxmce is configured as a recursive name server. Here's the changes I did to configure my core's name server to be authoritative and support dynamic IPs. Note, the machines on my intranet are private, i.e., not known to the outside world.

3 Feb 2008 - Developed and tested on LinuxMCE 0710 Beta 3 amd64.

I named my intranet "wright.local". Using a "local" top level domain (TLD) is recommended for private intranets. Some may prefer to use "lan". You do not want to use any of the standard TLDs like "com", "net", "org",...

I used the core's default intranet addresses, 192.168.80.0/24 with the core at 192.168.80.1.

I've attempted to verbosely document each config file. :)

The directions for adapting the config files are included in the named.conf file.

==Installation==

If you want to try this, I would suggest building the config in new directories then swapping with the originals when you are ready (I had a little mess when my core hung and I had to restart with only half the configs ready) :)

So start with creating two directories:

sudo mkdir /etc/bind.new
sudo mkdir /etc/dhcp3.new

Now copy the contents of the original directories:

sudo cp -arp /etc/bind/* /etc/bind.new
sudo cp -arp /etc/dhcp3/* /etc/dhcp3.new

Also create a new resolve.conf file:

sudo touch /etc/resolv.conf.new

Then add/change the following config files as described below:

/etc/bind/named.conf

To create a key for use in rndc.key and dhcpd.conf:

sudo dnssec-keygen -a HMAC-MD5 -b 256 -n user rndc

Now get the key from the private file:

sudo cat Krndc.*.private
Private-key-format: v1.2
Algorithm: 157 (HMAC_MD5)
Key: 3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=
Bits: AAA=

Now cut the key which is to the right of "Key: " and paste where needed (replace "<paste your key here>" with the key in the config files). So an example using the above key would look like:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

becomes:

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "3+GnSWV5FKxcUu57k7QFxbpvv/xr4fXj2wBVGtdGifI=";
};

Make the logging directory:

sudo mkdir /var/log/named
sudo chown bind:bind /var/log/named
sudo chmod 755 /var/log/named

You probably ought to check and change the defaultdomain:

domainname

will probably show

pluto

if so, then set it by:
sudo domainname yourdomain.local

where "yourdomain.local" is your domain. :-)

Change all the file permissions per instructions in named.conf.

Double check everything. Roll Eyes

Then when you are feeling lucky, rename the original directories and then rename the new directories to take there place:

sudo mv /etc/bind /etc/bind.original
sudo mv /etc/bind.new /etc/bind
sudo mv /etc/dhcp3 /etc/dhcp3.original
sudo mv /etc/dhcp3.new /etc/dhcp3
sudo mv /etc/resolve.conf /etc/resolve.conf.original
sudo mv /etc/resolve.conf.new /etc/resolve.conf

Finally restart the bind and dhcpd services:

sudo rndc reload
sudo /etc/init.d/dhcp3-server restart

Check the syslog for any errors:

grep named /var/log/syslog
grep dhcpd /var/log/syslog

==Config Files==

===/etc/bind/named.conf===
<pre>
// This is the primary configuration file for the BIND DNS server named.
//
// This configuration supports an authoritative local zone (wright.local on
// 192.168.80.0/24) and allows DHCP to update the local zone.
// To customize to your setup:
// 1) replace "wright.local" with your internal domain name.
// 2) edit db.wright.local.zone and db.wright.local.rev and replace
// my static names/addresses with your network's static names/addresses.
// Make sure to increment the serial number of any file edited.
// Note, format of serial number is: YYYYMMDDNN where YYYY is year,
// MM is month, DD is day, NN is update number for that day (i.e., 01,
// 02, 03,...)
// 3) rename db.wright.local.zone to match your domain name.
// 4) rename db.wright.local.rev to match your domain name.
// 5) If you changed the internal network IP from the LinuxMCE default of
// 192.168.80.0/24, then replace "192.168.80" with your network
// ip and replace it's reverse "80.168.192" wity your network ip's
// reverse.
//
// Please read /usr/share/doc/bind9/README.Debian.gz for information on the
// structure of BIND configuration files in Debian, *BEFORE* you customize
// this configuration file.
//
// If you are just adding zones, please do that in /etc/bind/named.conf.local
//
// references:
// http://www.arda.homeunix.net/dnssetup.html
// http://www.madboa.com/geek/soho-bind/
//
// notes:
// 1) The following command should be ran about twice a year to keep
// the root servers current:
// dig @a.root-servers.net . ns > /etc/bin/db.root
// Root name servers don’t change very often so updating this file more
// than twice a year is probably overkill. Frequent updates also put undo
// load on the root name servers; they have enough to do as it is.
//
// 2) File permissions:
// /etc/bind/named.conf root:root 644
// /etc/bind/rndc.key root:bind 640
// /etc/bind/rndc.conf root:root 600
// /etc/resolv.conf root:root 644
// /etc/bind root:bind 775, chmod g+s => drwxrwsr-x
// /etc/dhcp3 root:root 755
// /etc/dhcp3/dhcpd.conf root:root 644
//
// Manually Updating Zone Files
// 1. Use rndc to stop BIND.
// sudo rndc stop
// 2. Remove any .jnl files from the zone file directory.
// sudo rm /etc/bind/*.jnl
// 3. Edit the zone files as necessary. Make sure to increment the serial
// number of any file edited. Note, format of serial number is:
// YYYYMMDDNN where YYYY is year, MM is month, DD is day, NN is update
// number for that day (i.e., 01, 02, 03,...)
// 4. Start BIND using its startup script.
// sudo /etc/init.d/bind9 start

// secret must be the same as in /etc/bind/rndc.conf
include "/etc/bind/rndc.key";

// access control list used to limit queries to local net
acl "internal-net" { 192.168.80/24; 127.0.0.1; };

controls {
inet 127.0.0.1 allow { any; } keys { "rndc-key"; };
};

include "/etc/bind/named.conf.options";

// The single dot (.) is the root of all DNS namespace, so
// this zone tells named where to start looking for any
// name on the Internet
zone "." IN {
type hint;
file "/etc/bind/db.root";
};

// local intranet zones and reverse zones
// intranet is wright.local and 192.168.80.0/24
// the DHCP servers is on linuxmce-dhcp
// an optional second nameserver would be on linuxmce-ns2

zone "wright.local" IN {
type master;
file "/etc/bind/db.wright.local.zone";
// both allow-update and update-policy can enable DHCP updates,
// but update-policy allows more control over what kinds of
// updates DHCP can perform on a zone.
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain wright.local. A TXT; };
// allow-transfer { key "linuxmce-ns2"; };
// notify on zone transfers
notify yes;
};

zone "80.168.192.in-addr.arpa" IN {
type master;
file "/etc/bind/db.wright.local.rev";
// allow-update { none; };
update-policy { grant linuxmce-dhcp subdomain 80.168.192.in-addr.arpa. PTR TXT; };
// allow-transfer { key "linuxmce-ns2"; };
notify yes;
};

// be authoritative for the localhost forward and reverse zones, and for
// broadcast zones as per RFC 1912 (http://www.ietf.org/rfc/rfc1912.txt)

// Where the localhost hostname is defined
zone "localhost" IN {
// a master type means that this server needn't look
// anywhere else for information; the localhost buck
// stops here.
type master;
file "/etc/bind/db.local";
// don't allow dynamic DNS clients to update info
// about the localhost zone
allow-update { none; };
};

// Where the 127.0.0.0 network is defined
zone "127.in-addr.arpa" IN {
type master;
file "/etc/bind/db.127";
allow-update { none; };
};

zone "0.in-addr.arpa" IN {
type master;
file "/etc/bind/db.0";
allow-update { none; };
};

zone "255.in-addr.arpa" IN {
type master;
file "/etc/bind/db.255";
allow-update { none; };
};

// Include logging config file
include "/etc/bind/logging.conf";

// zone "com" { type delegation-only; };
// zone "net" { type delegation-only; };

// From the release notes:
// Because many of our users are uncomfortable receiving undelegated answers
// from root or top level domains, other than a few for whom that behaviour
// has been trusted and expected for quite some length of time, we have now
// introduced the "root-delegations-only" feature which applies delegation-only
// logic to all top level domains, and to the root domain. An exception list
// should be specified, including "MUSEUM" and "DE", and any other top level
// domains from whom undelegated responses are expected and trusted.
// root-delegation-only exclude { "DE"; "MUSEUM"; };

include "/etc/bind/named.conf.local";
</pre>

===/etc/bind/named.conf.options===
<pre>
options {
// tell named where to find files mentioned below
directory "/var/cache/bind";

// file that contains the process id when bind is running
pid-file "/var/run/bind/run/named.pid";

// enable statistics
statistics-file "/var/named/named.stats";
zone-statistics yes;

dump-file "/var/named/named.dump";

// If there is a firewall between you and nameservers you want
// to talk to, you might need to uncomment the query-source
// directive below. Previous versions of BIND always asked
// questions using port 53, but BIND 8.1 and later use an unprivileged
// port by default.
// query-source address * port 53;

// If your ISP provided one or more IP addresses for stable
// nameservers, you probably want to use them as forwarders.
// Uncomment the following block, and insert the addresses replacing
// the all-0's placeholder.

// The forwarders option tells BIND to not use iterative queries itself
// for information it doesn’t already know about but to forward a
// recursive query to the name servers specified instead.
include "/etc/bind/named.conf.forwarders";

// conform to RFC1035
auth-nxdomain no;

// on a multi-homed host, you might want to tell named
// to listen for queries only on certain interfaces
listen-on-v6 { any; };
listen-on { "internal-net"; };

// to allow only specific hosts to use the DNS server:
allow-query { "internal-net"; };

// sets BIND’s default behaviour to refuse all zone transfers.
// Without setting this option, anyone can transfer any zone.
allow-transfer { none; };

// do not generate notify messages for all zones on a restart.
// override for authorative zones
notify no;
};
</pre>

===/etc/bind/logging.conf===
<pre>
logging {

channel default_file {
file "/var/log/named/default.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel general_file {
file "/var/log/named/general.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel database_file {
file "/var/log/named/database.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel security_file {
file "/var/log/named/security.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel config_file {
file "/var/log/named/config.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel resolver_file {
file "/var/log/named/resolver.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-in_file {
file "/var/log/named/xfer-in.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel xfer-out_file {
file "/var/log/named/xfer-out.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel notify_file {
file "/var/log/named/notify.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel client_file {
file "/var/log/named/client.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel unmatched_file {
file "/var/log/named/unmatched.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel queries_file {
file "/var/log/named/queries.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel network_file {
file "/var/log/named/network.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel update_file {
file "/var/log/named/update.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dispatch_file {
file "/var/log/named/dispatch.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel dnssec_file {
file "/var/log/named/dnssec.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};
channel lame-servers_file {
file "/var/log/named/lame-servers.log" versions 3 size 5m;
severity dynamic;
print-time yes;
};

category lame-servers {
lame-servers_file;
};
category dnssec {
dnssec_file;
};
category dispatch {
dispatch_file;
};
category update {
update_file;
};
category network {
network_file;
};
category queries {
queries_file;
};
category unmatched {
unmatched_file;
};
category client {
client_file;
};
category notify {
notify_file;
};
category xfer-out {
xfer-out_file;
};
category xfer-in {
xfer-in_file;
};
category resolver {
resolver_file;
};
category config {
config_file;
};
category security {
security_file;
};
category database {
database_file;
};
category general {
general_file;
};
category default {
default_file;
};
};
</pre>

===/etc/bind/rndc.conf===
<pre>
options {
default-server localhost;
default-key "rndc-key";
default-port 953;
};

server localhost {
key "rndc-key";
};

key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/rndc.key===
<pre>
key "rndc-key" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

key "linuxmce-ns2" {
algorithm hmac-md5;
secret "<paste your key here>";
};
</pre>

===/etc/bind/db.wright.local.zone===
<pre>
;
; BIND data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; Address records specify an IP address to assign to a name
;
dcerouter IN A 192.168.80.1
dad-kubuntu IN A 192.168.80.21
royw-gentoo IN A 192.168.80.20
;
; Canonical name records, maps one name to another.
;
linuxmce IN CNAME dcerouter
</pre>

===/etc/bind/db.wright.local.rev===
<pre>

;
; BIND reverse data file for wright.local
; ref. http://www.redhat.com/docs/manuals/linux/RHL-9-Manual/ref-guide/s1-bind-zone.html
;
$ORIGIN 80.168.192.in-addr.arpa.
$TTL 86400 ; time to live : 86400s = 1 day
; Start Of Authority record, proclaims important authoritative information
; about a namespace to the nameserver.
@ IN SOA dcerouter.wright.local roy@wright.org (
2008013101 ;serial (YYYYMMDDNN where N = 01,02,03,...)
10800 ;refresh (3 hours)
7200 ;retry (2 hours)
36000000 ;expire (10,000 hours = 416 2/3 days)
86400) ;default minimum ttl
;
; NameServer record, which announces the authoritative nameservers for a particular zone.
;
IN NS dcerouter.wright.local.
;
; PTR — PoinTeR record, designed to point to another part of the namespace.
;
1 IN PTR dcerouter.wright.local.
21 IN PTR dad-kubuntu.wright.local.
20 IN PTR royw-gentoo.wright.local.
</pre>

===/etc/dhcp3/dhcpd.conf===
<pre>
option domain-name-servers 192.168.80.1;
authoritative;

option routers 192.168.80.1;
option subnet-mask 255.255.255.0;

# lease IPs for 1 day, maximum 1 week
default-lease-time 86400;
max-lease-time 604800;

# dynamic DNS updates
ddns-updates on;
ddns-update-style interim;
ddns-domainname "wright.local.";
ddns-rev-domainname "in-addr.arpa.";
ddns-ttl 14400;

# don't let clients modify their own A records
ignore client-updates;

key "linuxmce-dhcp" {
algorithm hmac-md5;
secret "<paste your key here>";
};

zone wright.local {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

zone 80.168.192.in-addr.arpa {
primary 192.168.80.1;
key "linuxmce-dhcp";
}

option space pxelinux;
option pxelinux.magic code 208 = string;
option pxelinux.configfile code 209 = text;
option pxelinux.pathprefix code 210 = text;
option pxelinux.reboottime code 211 = unsigned integer 32;

subnet 192.168.80.0 netmask 255.255.255.0 {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

option domain-name "wright.local";
option domain-name-servers 192.168.80.1;
option routers 192.168.80.1;

default-lease-time 86400;
max-lease-time 604800;
pool {
allow unknown-clients;
range 192.168.80.129 192.168.80.254;
}
}

# PXE booting machines
group {
next-server 192.168.80.1;
filename "/tftpboot/pxelinux.0";
option pxelinux.reboottime = 30;

}

# regular machines
group {
}

# CORE (1) has bad mac address:

</pre>

===/etc/resolv.conf===
<pre>
domain wright.local
nameserver localhost
</pre>

SMB / Samba NAS Configurations

2008-09-05T22:09:24Z

Juanfe: /* Adding fileserver on the external network */

[[Category: Tutorials]]

[[How to setup Samba with two workgroups?]]
[[How to setup Samba to follow symbolic links?]]

Problem: we have shares for each users. if I want to access it from Windows, I have to enter password. if I don't this on first access, windows won't ask my anymore to enter password and just denies access. How can I force windows, to reenter password for share ???

If your samba password doesn't work then run this on core to update your samba password:
sudo smbpasswd pluto_USER
where USER is your username. For instance to change john's password run sudo smbpasswd pluto_john

== Adding fileserver on the external network ==
The external network does not get scanned for Samba servers. You can easily add a new server by going into the web admin
* Click Show Device Tree
* Click CORE
* On the right hand side, click Create Child Device
* Click Pick Device Template
* In the popup select Manufacturer->Generic and Device Category->File Server from the drop down menus; you can also enter device template ID 1837 in the "Do you know the ID of the device template?" field
* Now, it is important to fill out 2 fields
** The IP address
** '''and''' the MAC address
* The username and password are only needed if the file server requires them.
* There is currently a bug in the webadmin which causes this file server to not be scanned for shares.
=== Scanning For Shares ===
The good thing about LinuxMCE is, that LinuxMCE routinely scans the internal network for servers, and if found, scans those servers for shares to be mounted and spidered for media. To initiate the scan for shares manually (because of a manually added server) do the following
* Open a terminal
* Execute
/usr/pluto/bin/Configure_1837.sh -d <device-id> -i '<ip-address>' -m '<mac-address>'

This will execute the scan for new shares. The shares will be presented to you on any orbiter.

LinuxMCE System Update

2008-09-03T21:18:31Z

Juanfe: /* This information seems to be outdated. At least in 0710b3 there are no such files. */

{{NeedsToBeFixed}}
== General Info ==
'''Package:''' pluto-update-system

'''Directory:''' src/PlutoUpdateSystem

== File Details ==

= This information seems to be outdated. At least in 0710b3 there are no such files. =

LinuxMCE live updating system is taking care of by 4 shell scripts:

;DownloadUpdates.sh: This script is runned by cron and downloads all the needed deb packages for doing an dist-upgrade on the Core and all of it's MDs. Also this script calls the NotifyUpdates.sh script to notify the user that the updates are available and he shoule reboot certain machine so they can be installed. This script runs only on the Core.

;ApplyUpdates.sh: This is a startup script and is runned by the /etc/init.d/fastboot/rcS.d system initialization script before any of the LinuxMCE services get started. It checks if DownloadUpdates has downloaded all the needed packages and if so, it trigers a dist-updagrade. If a new kernel is one of the updated packages he also takes care of rebooting the system after all the updates are installed. This script is run by Core and all the Diskless MDs.

;NotifyUpdates.sh: Notifies the user via orbiters that updates are available and that certain machines should do a reboot so they can update. It takes the ''PK_Device'' of the machine that needs to reboot as a parameter.

;ForceUpdates.sh: Force system update. It kill all instances of already run DownloadUpdates.sh and ForceUpdates.sh, display notification message about reboot on all Orbiters and send a command to the Core to reboot it and start process of system update.
[[Category: LinuxMCEBashScripts]]

== How to upgrade manually ==

--[[User:Totallymaxed|Totallymaxed]] 08:14, 2 March 2008 (PST)
I would suggest the following procedure for forcing the download of updates under 0704;

Go to the /usr/pluto/bin directory

run the following script;

sudo ./LMCEUpdate_DownloadXml.sh <return>

This will take some time while the update archives are downloaded... so be patient! Once the updates are downloaded you should be asked whether you want to apply the update in the Orbiter - click "Yes" to apply updates and thats it.

Quoting [http://plutohome.com/wiki/index.php/User:Nite_man nite_man] from forum :

You can do upgrade manually. Go to the /usr/pluto/bin and run one by one two scripts:

./DownloadUpdates.sh

and

./ApplyUpdates.sh

The first one will download all updated packages and the second one will apply changes to the LinuxMCE installation.

Note: you should wain until DownloadUpdates.sh finish. Also, you can ignore some warnings which may be generated by this script (you can see the log /var/log/pluto/DownloadUpdates.log)

Another way to perform system update is use the Orbiter:

More --> Advanced Options --> Force Upgrade Now

It forces reboot your core and starts upgrade.

Java Mobile Orbiter

2008-08-16T21:09:33Z

Juanfe: /* Install the application on the phone */

[[Category: Hardware]]
[[Category: Phones]]
[[Category: Orbiters]]

[[Image:N73-Javamo.jpg|thumb|200px|JavaMO on the Nokia N73]]
[[Image:Javamo p1 ui1.jpg|thumb|200px|UI1 with touchscreen on the P1]]
[[Image:Javamo-e65-ui1.jpg|thumb|200px|UI1 on the Nokia E65]]

= Introduction =
The JavaMO is a lightweight [[Mobile_Orbiter|Mobile Orbiter]] client. It receives rendered pictures from the [[Bluetooth_Dongle|Bluetooth dongle]] [[Orbiter]] and sends keystrokes and pointer events back. The protocol used over Bluetooth is [[BD_-_Bidirectional_command_processor|BD]].

JavaMO is under active development. An alpha version can be found on the charonmedia svn tree or on http://vt100.at/javamo/.
= Changelog =
* 0.0.2 - Touchscreen support, fix unhandled exception on dcerouter reload
* 0.0.1 - Proof of concept, basic functionality

= Installation =
== Phone ==
For most phones you need the jad and the jar file. Copy both to the phone and select the jad from the file or application manager.
== Core/MD ==
You have to exchange the libBDCommon.so with the provided one on all 0710 cores or MD's with a Bluetooth_Dongle. Download the replacement libBDCommon.so from http://vt100.at/javamo/ . In /usr/pluto/lib rename libBDCommon.so to libBDCommon.so.old, then copy the new version you downloaded into this directory and reboot.
== LMCE Plug and Play detection ==
When LMCE asks you for the type of phone select "Symbian S60". The application push will fail. Thats ok. Just answer no to the question if LMCE should resend it.
== Screen Size, UI Variant ==
Go to the Orbiter in the pluto-admin web interface (select Orbiters in the Wizard on the left)
Adapt the PK_UI, PK_Size and resolution values to match your phones display. If you have no touchscreen on the phone stick with symbian for PK_UI, otherwise choose the normal variant.

= See also =
[[Mobile_Orbiter|Mobile Orbiter]]

[[LinuxMCE_Orbiter_Symbian_Programmer%27s_Guide|LinuxMCE Orbiter Symbian Programmer's Guide]]

= Links =
[http://forum.linuxmce.org/index.php?topic=2893 Forum thread re JavaMO]

= JavaMO development guide =
== Preparations ==
=== Checkout ===
Checkout the source from the charonmedia.org svn tree:
<pre>
svn co http://svn.charonmedia.org/svn/home/hari/javamo
cd javamo
</pre>

=== Installing Java ===
First we install the Java SDK. I used version 6 update 6. Download it from the sun download center: http://java.sun.com/javase/downloads/index.jsp
<pre>
chmod +x ./jdk-6u6-linux-i586.bin
./jdk-6u6-linux-i586.bin
</pre>
That gives us the directory "jdk1.6.0_06".

Now install the wireless toolkit version 2.5.2: http://java.sun.com/products/sjwtoolkit/download.html
<pre>
./sun_java_wireless_toolkit-2_5_2-linux.bin
</pre>
Specify the _full_ path to the "jdk1.6.0_06/bin" directory (this example assumes javamo was checked out to "/home/hari/src/javamo"):
<pre>
Enter a path to the Java 2 SDK: /home/hari/src/javamo/jdk1.6.0_06/bin
</pre>
After the installation you should have the following subdirectories in the javamo directory:
* jdk1.6.0_06
* WTK2.5.2

== Building the application ==
just run "make":
<pre>
make
</pre>
You will find the "JavaMO.jad" and "JavaMO.jar" file in the "output" directory if the compile succeeds.
== Install the application on the phone ==
That strongly depends on the type of phone and sometimes your mobile carrier.

===Nokia Symbian devices===
For Nokia Symbian Series with a memory card you can use the "install" target in the "Makefile". Just adapt the Bluetooth address of the phone in the "Makefile" and run:
<pre>
make install
</pre>
Then go to the file browser on the phone, switch to the memory card and select the "JavaMO.jad" file. Make sure you have enabled the installation of unsigned applications in the application manager.

===Developers in the United States===
If you are developing in the United States, the process to install JavaMO on your phone depends heavily on the operator you have for your mobile.

If you have a Sprint or Nextel phone, you can install the MIDlet over the air using [http://developer.sprint.com/site/global/develop/upload_your_content/p_upload_your_content.jsp | Sprint ADP's OTA content uploader].

On a Nextel phone, you can also install it using a cable downloading the [https://developer.motorola.com/docstools/idenjal/| iDEN Java Application Loader]. There are mechanisms for cable-loading an application onto a variety of Sprint CDMA phones, but these vary greatly in their reliability/ease of access.

If you are working with a Verizon phone, you will need to have a BREW developer license and toolkit to load an application onto the device. Chances are you don't have this.

If you are working with an AT&T or T-Mobile GSM phone, you should put the JAD and JAR files in a publicly accessible web server, then point the web browser of your phone to the JAD file -- it should begin the download automatically.

== Building the documentation ==
<pre>
make javadoc
</pre>
Direct your browser to the file "doc/index.html"
== On device debugging with a Nokia N and E series phone and Linux ==
To get the output from the application running on the phone on a computer screen, do the following:
* Register with Nokia and get the Symbian SDK
* Transfer the "EcmtAgent_MIDP.SIS" application on the phone and run it, uses bluetooth per default
* Go to system - application manager on the phone and install the "RedMIDlet.jar" (shows "not installed")
* Go to the application folder and run the "Sdt.out.redir" application
* do a "sdptool browse" on your notebook with a supported bluetooth dongle (hci device must be up) to find out the rfcomm port. You should see something like this:
<pre>
Service Name: EcmtAgent
Service Description: Bluetooth bearer for EcmtAgent
Service RecHandle: 0x10043
Service Class ID List:
"Serial Port" (0x1101)
Protocol Descriptor List:
"L2CAP" (0x0100)
PSM: 3
"RFCOMM" (0x0003)
Channel: 3
Language Base Attr List:
code_ISO639: 0x656e
encoding: 0x6a
base_offset: 0x100
</pre>
* run a command like the following after substitution of the Bluetooth address and the rfcomm channel:
<pre>
while $a; do rfcomm release /dev/rfcomm0 ; rfcomm bind /dev/rfcomm0 00:17:C4:C3:36:24 3 ; cat /dev/rfcomm0 ; done
</pre>
Example output (process list, system info and the javamo console output):
<pre>
0x000004380x10204578CPU 191985135 1 DRIVES C 46539776 23182336;D 5629952 5627904;E 2030960640 30343168;Z 20971520 0; RAM 5627904 46137344 20971520 APPLICATIONS JavaMO 692 -1 -1 -1 2654876;EiksrvBackdrop 97 -1 -1 -1 106830749;Menü 163 -1 -1 -1 5559722;EcmtAgent 601 -1 -1 -1 1263824;Standby-Modus 150 -1 -1 -1 16982482;Sdt.out_redir 648 -1 -1 -1 243194;Telefon 146 -1 -1 -1 11353271;Protokoll 394 -1 -1 -1 1592987;Kontakte 330 -1 -1 -1 1927398;MultimediaList 161 -1 -1 -1 510864;SysAp 122 -1 -1 -1 4535278; 77 -1 -1 -1 9002;Anykey 148 -1 -1 -1 290618;blinkingled 240 -1 -1 -1 266265;Player 266 -1 -1 -1 331695;Autolock 238 -1 -1 -1 103759;Galerie 310 -1 -1 -1 1241149;screensaver 154 -1 -1 -1 16530914;akncapserver 97 -1 -1 -1 106830749;btnotifappserver 108 -1 -1 -1 684661;Securitynotifierappserver 106 -1 -1 -1 311309;VolumePopup 266 -1 -1 -1 331695;MPlayerInfoPopup 266 -1 -1 -1 331695;VolumePopup 150 -1 -1 -1 16982482;CTSecDlgAppServer 110 -1 -1 -1 63354;SyncMLNotifierAppServer 114 -1 -1 -1 59234;cconndlgappserver 116 -1 -1 -1 62744;locnotifierappserver 104 -1 -1 -1 63476;0x000000780x1020456c
ReceiveLong: long result: 102
Got BD_CP_SHOW_IMAGE
</pre>
== Java J2ME simulator with real bluetooth hardware access over bluez ==
* Get the mpowerplayer SDK: http://mpowerplayer.com/?cat=6
* Install it
* Either buy (http://www.avetana-gmbh.de) or compile (http://sourceforge.net/projects/avetanabt/) the avetana bluetooth stack
* put the "AvetanaBluetooth.jar" file in the mpp-sdk top level directory
* adapt the path to the mpp installation in the javamo Makefile
* run "make bluezsim" to run JavaMO in the sim with bluez access over JSR082

= Phone Specifics =
== Nokia E61 ==
The Nokia E61 has a full keyboard. To select the numbers you have to '''hold''' down the blue function key, and press the number together with it.

Java Mobile Orbiter

2008-08-01T15:57:20Z

Juanfe: /* Install the application on the phone */

[[Category: Hardware]]
[[Category: Phones]]
[[Category: Orbiters]]

[[Image:N73-Javamo.jpg|thumb|200px|JavaMO on the Nokia N73]]
[[Image:Javamo p1 ui1.jpg|thumb|200px|UI1 with touchscreen on the P1]]
[[Image:Javamo-e65-ui1.jpg|thumb|200px|UI1 on the Nokia E65]]

= Introduction =
The JavaMO is a lightweight [[Mobile_Orbiter|Mobile Orbiter]] client. It receives rendered pictures from the [[Bluetooth_Dongle|Bluetooth dongle]] [[Orbiter]] and sends keystrokes and pointer events back. The protocol used over Bluetooth is [[BD_-_Bidirectional_command_processor|BD]].

JavaMO is under active development. An alpha version can be found on the charonmedia svn tree or on http://vt100.at/javamo/.
= Changelog =
* 0.0.2 - Touchscreen support, fix unhandled exception on dcerouter reload
* 0.0.1 - Proof of concept, basic functionality

= Installation =
== Phone ==
For most phones you need the jad and the jar file. Copy both to the phone and select the jad from the file or application manager.
== Core/MD ==
You have to exchange the libBDCommon.so with the provided one on all 0710 cores or MD's with a Bluetooth_Dongle. Download the replacement libBDCommon.so from http://vt100.at/javamo/ . In /usr/pluto/lib rename libBDCommon.so to libBDCommon.so.old, then copy the new version you downloaded into this directory and reboot.
== LMCE Plug and Play detection ==
When LMCE asks you for the type of phone select "Symbian S60". The application push will fail. Thats ok. Just answer no to the question if LMCE should resend it.
== Screen Size, UI Variant ==
Go to the Orbiter in the pluto-admin web interface (select Orbiters in the Wizard on the left)
Adapt the PK_UI, PK_Size and resolution values to match your phones display. If you have no touchscreen on the phone stick with symbian for PK_UI, otherwise choose the normal variant.

= See also =
[[Mobile_Orbiter|Mobile Orbiter]]

[[LinuxMCE_Orbiter_Symbian_Programmer%27s_Guide|LinuxMCE Orbiter Symbian Programmer's Guide]]

= Links =
[http://forum.linuxmce.org/index.php?topic=2893 Forum thread re JavaMO]

= JavaMO development guide =
== Preparations ==
=== Checkout ===
Checkout the source from the charonmedia.org svn tree:
<pre>
svn co http://svn.charonmedia.org/svn/home/hari/javamo
cd javamo
</pre>

=== Installing Java ===
First we install the Java SDK. I used version 6 update 6. Download it from the sun download center: http://java.sun.com/javase/downloads/index.jsp
<pre>
chmod +x ./jdk-6u6-linux-i586.bin
./jdk-6u6-linux-i586.bin
</pre>
That gives us the directory "jdk1.6.0_06".

Now install the wireless toolkit version 2.5.2: http://java.sun.com/products/sjwtoolkit/download.html
<pre>
./sun_java_wireless_toolkit-2_5_2-linux.bin
</pre>
Specify the _full_ path to the "jdk1.6.0_06/bin" directory (this example assumes javamo was checked out to "/home/hari/src/javamo"):
<pre>
Enter a path to the Java 2 SDK: /home/hari/src/javamo/jdk1.6.0_06/bin
</pre>
After the installation you should have the following subdirectories in the javamo directory:
* jdk1.6.0_06
* WTK2.5.2

== Building the application ==
just run "make":
<pre>
make
</pre>
You will find the "JavaMO.jad" and "JavaMO.jar" file in the "output" directory if the compile succeeds.
== Install the application on the phone ==
That strongly depends on the type of phone. For Nokia Symbian Series with a memory card you can use the "install" target in the "Makefile". Just adapt the Bluetooth address of the phone in the "Makefile" and run:
<pre>
make install
</pre>
Then go to the file browser on the phone, switch to the memory card and select the "JavaMO.jad" file. Make sure you have enabled the installation of unsigned applications in the application manager.

===Developers in the United States===
This depends strongly on the operator you have on your mobile.

If you are developing in the United States and have a Sprint or Nextel phone, you can install the MIDlet over the air using [http://developer.sprint.com/site/global/develop/upload_your_content/p_upload_your_content.jsp | Sprint ADP's OTA content uploader].

On a Nextel phone, you can also install it using a cable downloading the [https://developer.motorola.com/docstools/idenjal/| iDEN Java Application Loader]. There are mechanisms for cable-loading an application onto a variety of Sprint CDMA phones, but these vary greatly in their reliability/ease of access.

If you are working with a Verizon phone, you will need to have a BREW developer license and toolkit to load an application onto the device. Chances are you don't have this.

If you are working with an AT&T or T-Mobile GSM phone, you should put the JAD and JAR files in a publicly accessible web server, then point the web browser of your phone to the JAD file -- it should begin the download automatically.

== Building the documentation ==
<pre>
make javadoc
</pre>
Direct your browser to the file "doc/index.html"
== On device debugging with a Nokia N and E series phone and Linux ==
To get the output from the application running on the phone on a computer screen, do the following:
* Register with Nokia and get the Symbian SDK
* Transfer the "EcmtAgent_MIDP.SIS" application on the phone and run it, uses bluetooth per default
* Go to system - application manager on the phone and install the "RedMIDlet.jar" (shows "not installed")
* Go to the application folder and run the "Sdt.out.redir" application
* do a "sdptool browse" on your notebook with a supported bluetooth dongle (hci device must be up) to find out the rfcomm port. You should see something like this:
<pre>
Service Name: EcmtAgent
Service Description: Bluetooth bearer for EcmtAgent
Service RecHandle: 0x10043
Service Class ID List:
"Serial Port" (0x1101)
Protocol Descriptor List:
"L2CAP" (0x0100)
PSM: 3
"RFCOMM" (0x0003)
Channel: 3
Language Base Attr List:
code_ISO639: 0x656e
encoding: 0x6a
base_offset: 0x100
</pre>
* run a command like the following after substitution of the Bluetooth address and the rfcomm channel:
<pre>
while $a; do rfcomm release /dev/rfcomm0 ; rfcomm bind /dev/rfcomm0 00:17:C4:C3:36:24 3 ; cat /dev/rfcomm0 ; done
</pre>
Example output (process list, system info and the javamo console output):
<pre>
0x000004380x10204578CPU 191985135 1 DRIVES C 46539776 23182336;D 5629952 5627904;E 2030960640 30343168;Z 20971520 0; RAM 5627904 46137344 20971520 APPLICATIONS JavaMO 692 -1 -1 -1 2654876;EiksrvBackdrop 97 -1 -1 -1 106830749;Menü 163 -1 -1 -1 5559722;EcmtAgent 601 -1 -1 -1 1263824;Standby-Modus 150 -1 -1 -1 16982482;Sdt.out_redir 648 -1 -1 -1 243194;Telefon 146 -1 -1 -1 11353271;Protokoll 394 -1 -1 -1 1592987;Kontakte 330 -1 -1 -1 1927398;MultimediaList 161 -1 -1 -1 510864;SysAp 122 -1 -1 -1 4535278; 77 -1 -1 -1 9002;Anykey 148 -1 -1 -1 290618;blinkingled 240 -1 -1 -1 266265;Player 266 -1 -1 -1 331695;Autolock 238 -1 -1 -1 103759;Galerie 310 -1 -1 -1 1241149;screensaver 154 -1 -1 -1 16530914;akncapserver 97 -1 -1 -1 106830749;btnotifappserver 108 -1 -1 -1 684661;Securitynotifierappserver 106 -1 -1 -1 311309;VolumePopup 266 -1 -1 -1 331695;MPlayerInfoPopup 266 -1 -1 -1 331695;VolumePopup 150 -1 -1 -1 16982482;CTSecDlgAppServer 110 -1 -1 -1 63354;SyncMLNotifierAppServer 114 -1 -1 -1 59234;cconndlgappserver 116 -1 -1 -1 62744;locnotifierappserver 104 -1 -1 -1 63476;0x000000780x1020456c
ReceiveLong: long result: 102
Got BD_CP_SHOW_IMAGE
</pre>
== Java J2ME simulator with real bluetooth hardware access over bluez ==
* Get the mpowerplayer SDK: http://mpowerplayer.com/?cat=6
* Install it
* Either buy (http://www.avetana-gmbh.de) or compile (http://sourceforge.net/projects/avetanabt/) the avetana bluetooth stack
* put the "AvetanaBluetooth.jar" file in the mpp-sdk top level directory
* adapt the path to the mpp installation in the javamo Makefile
* run "make bluezsim" to run JavaMO in the sim with bluez access over JSR082

= Phone Specifics =
== Nokia E61 ==
The Nokia E61 has a full keyboard. To select the numbers you have to '''hold''' down the blue function key, and press the number together with it.

Developers Guide

2008-08-01T15:28:34Z

Juanfe: /* 9.3.1 HADesigner */

[[Category: Programmer's Guide]]

{| align="right"
| __TOC__
|}
LinuxMCE developer’s guide
Document version 1.0

==1. Architecture==

LinuxMCE uses a modular architecture. The heart of LinuxMCE, the 'main application' DCERouter is nothing but a general-purpose message router. It has absolutely no code relating to any of LinuxMCE’s functionality--it just relays messages between "Devices". The functionality of LinuxMCE is entirely in separate programs (aka "Devices") which all run independently and communicate with each other by passing messages through DCERouter over sockets.

[[Image:LMCE_Architecture_mini.jpg|frame|none|LinuxMCE architecture – the devices]]

The plug-in’s are also devices, but instead of running as separate binaries, they run as dynamic libraries in DCERouter’s memory space.
A LinuxMCE system can have one or more Media Directors (MD’s). Also, a Core machine can have also the functionality of a Media Director. We call it a Hybrid:

[[Image:LMCE_Architecture_-_the_machines.jpg|frame|none|Linux MCE architecture – the machines]]

==2. DCE==

DCE (Data, Commands and Events) is a lightweight network protocol allowing any device to access its configuration (ie data) from a central database, send + receive commands, and fire + respond to events.

The DCE protocol can be implemented with any device that supports standard networking. LinuxMCE provides a DCE library written in Ansi C++ that implements the protocol on any socket-compatible operating system, and has been tested on Linux and Windows. Porting to other languages should not be a big task. Because the messaging is socket-based, any device, regardless of operating system or language, can be used with any other device.

In each installation there is also one DCE Router, through which all messages are routed. An "installation" is a group of devices treated as a unit, and normally corresponds to a physical residence.

The DCE Router is itself quite simple. It just opens a port for incoming connections. When a device connects, the device sends its unique ID, or Mac Address. The DCE Router does a lookup in a database, and returns that device's data (configuration). DCERouter also sends back a list of all the other devices in the installation with basic information including the commands they know how to implement. The DCE Device then opens a minimum of 2 socket connections to the router. One is for incoming messages (usually commands) from the router, another for outgoing messages (usually events) to it. The DCE Library, which implements the protocol for DCE Devices and the DCE Router, will also open a 3rd socket connection so that it has 2 outgoing sockets: 1 dedicated for sending events and the other for sending other types of messages, like requests and commands to other devices.

All messages go through the router. The devices do not communicate directly to each other. The message will contain information such as the destination device, the type of message, the message id and any number of optional parameters. The router does nothing with the message but forward it to the destination device or devices if the message is being sent to more than one. The DCE library, from which DCE Devices and the DCE Router are derived, knows how to receive incoming messages of the type command and route them to a message handler in the DCE Device.

Another important library is PlutoUtils. It has cross-platform wrapper classes to handle file, strings, processes, threads synchronization, database utils, etc.

==3. DCERouter==

When a DCE Device connects, DCERouter gives it its configuration data and is responsible for receiving and forwarding any messages to and from the devices that connect to it. The most common types of messages are commands and events. All communication goes through DCE Router. If a doorbell device fires an event that the button was pushed, that event goes to DCERouter, which will forward it whatever plug-in has indicated it wants to handle that type of event. If the plug-in then wants to send a command to the media player, this command goes first to the DCE Router, which will then forward it to the media player. The DCE Devices never communicate with each other directly--everything goes through DCE Router. Devices can create their own types of messages specific to them--not just commands and events. For example, a DVD player may send a message that contains a screen capture, or a TV program may send a stream of messages with streaming video. To DCE Router it makes no difference. Messages just have sources and destinations, and DCE Router does not care what type of message it is.

DCERouter also allows you to Message Interceptors. This means a device or plug-in can say that it wants to pre-process all messages that meet a certain criteria. For example, a security plug-in may want to see all events relating to security.
Plug-in’s are DCE Devices that run within the DCERouter's memory space. They are DCE Devices just like any other and they are created like any other DCE Device. The code is the same, it's just a compilation option whether the device is built as a normal DCE Device, which runs in its own memory space and communicates with DCERouter over a socket, or if it's a plug-in which gets loaded into DCERouter's memory space. Plug-in’s have the ability to get pointers to the in-memory instance of the other plug-ins so they can share memory and call each others methods.

See below a simplified class diagram for DCERouter:
[[Image:DCERouter.jpg|frame|none|Simplified class diagram for the DCE router]]

==4. The binary communication protocol==

===4.1 Introduction===
A device can create a command connection and one or more event connections to the router.
*The command connection is used as an incoming connection and device will use it to receive message from the router (commands).
*An event connection is used by the device as an outgoing connection to notify the router about events or the deliver commands to other devices.
The DCERouter process is listening on 3450 port.

===4.2. How to create an event connection===
Here is how the handshake is made for an event connection:

>> Device sends:
EVENT <my_device_id> '\n'

<< The router will respond with :
OK <my_device_id> IP=<device_ip_address> '\n'

>> To send a message, the device will send :
MESSAGE <size_of_binary_message> '\n'

and then:
<serialized_binary_message>

===4.3 How to serialize data===
DCE uses SerializeClass to serialize/deserialize data.
The sources can be found here : src/SerializeClass/Serialize.h/cpp.
The deserialize the data, the deserializing module must know the way the data was serialized like this:
* 4 bytes, unsigned long
* 1 byte, unsigned char

Primitives:
* 8 bytes, unsigned int64
* 8 bytes, int64
* 4 bytes, unsigned long
* 4 bytes, unsigned short
* 1 byte, unsigned char
* 1 byte, char
* 4 byte, long
* 4 bytes, float
* 8 bytes, double
* 2 bytes, short

Complex types:

#string
#*STR_LENGTH bytes, the array with chars
#*1 byte, '/0' (value 0x00)
#:
#block of data
#*BLOCK_LENGTH bytes, the array with bytes
#:
#vector of strings
#*VECT_LENGTH bytes, the number of strings from vector
#*string 0
#*string 1
#*...
#*string VECT_LENGTH - 1

Other complex types serialized (see SerializeClass.cpp for details) :
* map<int,string>
* map<u_int64_t,string>
* map<int,int>
* map<string,string>
* vector<int>
* vector< pair<int,int> >
* map<string, pair<int,int> >

SerializeClass also allowed you to serialize/deserialize custom objects. Examples:
* PlutoColor
* PlutoPoint
* PlutoSize
* PlutoRectangle
* PlutoDataBlock

===4.4 How to serialize a message===

The class used by DCE is Message class from src/DCE/Message.h/cpp unit.

This is how the raw data looks like into a binary message:

* long, value must be 1234 (magic number)
* long, <device_from_id>
* long, <device_to_id>
* long, <device_group_to_id>
* long, <message_id>
* long, <message_priority>
* long, <message_type>
* long, <device_category_to>
* long, <device_template_to>
* unsigned char, <include_children>
* long, <message_broadcast_level>
* long, <message_retry>
* unsigned char, <relative_to_sender>
* long, <expected_response>
* string, <device_list_to>
* unsigned long, <number_of_string_parameters>
** foreach <string_parameter>
*** long, <string_parameter_id>
*** string, <string_parameter_value>
** end_foreach
* unsigned long, <number_of_data_parameters>
** foreach <data_parameter>
*** long, <data_parameter_id>
*** unsigned long, <data_parameter_length>
*** array of bytes, <data_parameter_value>
** end_foreach
* unsigned long, <number_of_extra_messages>
** foreach <extra_message>
*** unsigned long, <serialized_extra_message_length>
*** array of bytes, <serialized_extra_message_value>
** end_foreach
* unsigned long, must be 6789

'''Enums:'''
* enum eBroadcastLevel { BL_None=0, BL_DirectSiblings=1, BL_SameComputer=2, BL_SameRoom=3, BL_SameHouse=4, BL_AllHouses=5 };
* enum eRetry { MR_None=0, MR_Retry=1, MR_Persist=2 };
* enum eExpectedResponse { ER_None=0, ER_ReplyMessage, ER_ReplyString, ER_DeliveryConfirmation };
* message types: enum { MESSAGETYPE_COMMAND=1, MESSAGETYPE_EVENT=2, MESSAGETYPE_DATAPARM_CHANGE=3, MESSAGETYPE_REPLY=4, MESSAGETYPE_DATAPARM_REQUEST=5, MESSAGETYPE_LOG=6, MESSAGETYPE_SYSCOMMAND=7, MESSAGETYPE_REGISTER_INTERCEPTOR=8, MESSAGETYPE_MESSAGE_INTERCEPTED=9, MESSAGETYPE_EXEC_COMMAND_GROUP=10, MESSAGETYPE_START_PING=11, MESSAGETYPE_STOP_PING=12, MESSAGETYPE_PURGE_INTERCEPTORS=13, MESSAGETYPE_PENDING_TASKS=14 };
* message priority : enum { PRIORITY_LOW=0, PRIORITY_NORMAL=1, PRIORITY_HIGH=2, PRIORITY_URGENT=3 };

'''Important notes:'''
* when sending to device template, set <device_template_to> to desired device template and also <device_to_id> to -2000 (DEVICEID_MASTERDEVICE)
* when sending to device category, set <device_category_to> to desired device category and also <device_to_id> to -2001 (DEVICEID_CATEGORY)
* when sending to a list with devices, set <device_list_to> to comma delimited list with devices and also <device_to_id> to -2002 (DEVICEID_LIST).

'''Example:'''
Here is the pseudocode to send the "on" command to a light switch.
We'll assume that the your device has #id 250 and the light switch has device #id 100

*MyDevice.Connect(router_ip, 3450 /*port*/)
*MyDevice.SendData("EVENT 250\n")
*MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK 250 IP=<device_ip_address> '\n';

'''next: creating a message'''
let's say MyData is an array of bytes
*SerializeLong(MyData, 1234) //magic number
*SerializeLong(MyData, 250) //my id
*SerializeLong(MyData, 100) //the light switch
*SerializeLong(MyData, 0) //not used now
*SerializeLong(MyData, 192) //message id of command 'on'
*SerializeLong(MyData, 1) //normal priority
*SerializeLong(MyData, 1) //message type : command
*SerializeLong(MyData, 0) //not used now
*SerializeLong(MyData, 0) //not used now
*SerializeUnsignedChar(MyData, 0) //not including children
*SerializeLong(MyData, 0) //broadcast level : none
*SerializeLong(MyData, 0) //don't retry
*SerializeUnsignedChar(MyData, 0) //relative to sender false
*SerializeLong(MyData, 3) //delivery confirmation
*SerializeString(MyData, "") //device list to empty
*SerializeUnsignedLong(MyData, 2) //2 parameters
*SerializeLong(MyData, 98) //parameter type #98
*SerializeString(MyData, "") //empty value
*SerializeLong(MyData, 97) //parameter type #97
*SerializeString(MyData, "") //empty value
*SerializeUnsignedLong(MyData, 0) //no binary parameters
*SerializeUnsignedLong(MyData, 0) //no extra messages
*SerializeUnsignedLong(6789) //magic number

*MyDevice.SendData("MESSAGE " + MyData.length() + '\n')
*MyDevice.SendData(MyData)
*MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK" or an error message

*MyDevice.CloseConnection();

===4.5 How to serialize data-grids ===
'''Complex objects:'''
# DataGridCellSerializableData
#* unsigned long, <sizeof(DataGridCellSerializableData)>
#* unsigned long, <graphic_length>
#* unsigned long, <message_length>
#* unsigned long, <text_length>
#* unsigned long, <value_length>
#* unsigned long, <image_path_length>
#* unsigned long, <number_of_attributes_length>
#* unsigned long, <attributes_length>
#* int, <alternate_color>
#* unsigned long, <graphic_format>
#* unsigned char, <selectable>
#* int, <style_detail>
#* int, <col_span>
#* int, <row_span>
#* unsigned char, <dont_fire_grid_event>
#:
#:Enums:
#* enum eGraphicFormat { GR_UNKNOWN=0, GR_JPG=1, GR_GIF=2, GR_TIF=3, GR_PNG=4, GR_MNG=5, GR_BMP=6, GR_OCG=7, GR_PFG=8 };
#:
# DataGridCell
#* DataGridCellSerializableData, <datagrid_cell_serializable_data>
#* array of chars, <text>
#* array of chars, <value>
#* array of bytes, <graphic_data>
#* array of bytes, <message_data>
#* array of chars, <image_path>
#*:
#** foreach <cell_attribute>
#*** array of chars ended with '\0' , <cell_attribute_name>
#*** array of chars ended with '\0', <cell_attribute_value>
#** end_foreach
#:
#DataGridTableSerializableData
#* int, <total_number_of_columns>
#* int, <total_number_of_rows>
#* unsigned char, <keep_row_header>
#* unsigned char, <keep_column_header>
#* int, <column_count>
#* int, <row_count>
#* int, <starting_column>
#* int, <starting_row>
#* int, <cell_count>
#:
#DataGridTableCellIndex
#* unsigned int, <column_row_type>
#* unsigned int, <size>
#:
#DataGridTable
#* unsigned long, <sizeof(DataGridTableSerializableData)>
#* array of DataGridTableCellIndex, <col * row * sizeof(DataGridTableCellIndex)>
#* array of DataGridCell, <col * row * serialized DataGridCell>

----
Additional step: lzo compression/decompression

'''Note:''' can be disabled if compiled with DISABLE_LZO_DATAGRID
----

==5. The devices==

Each device has associated an interface, which we call device template. A device template is a set of commands to be implemented, events which can be fired by the device and device data (persistent information for device).
To create device templates and modify them, go to LinuxMCE Web Admin -> Advanced -> Configuration -> Device Templates.
To generate the C++ code for the device implementing a device template interface, you must use DCEGen tool, specifying the database ip address and the device template number.
Here is the simplified class diagram for one of the devices (App_Server):

[[Image:App_Server.jpg|frame|none|Simplified class diagram for a DCE device]]

The classes App_Server_Event, App_Server_Command and App_Server_Data are generated using DCEGen tool. The base classes for them are implemented in DCE Library.

==6. App_Server device==

App_Server device is present by default on all LinuxMCE machines. It spawns/kills applications, handles volume of sound on that machine, restarts/halts the device.

# Implemented commands:
#*CMD_Spawn_Application - Spawns an application
#*CMD_Kill_Application - Kills an application
#*CMD_Application_Is_Running - Checks if the given application is running.
#*CMD_Halt_Device - Halts or reboots this device
#*CMD_Vol_Up - Increases the volume 1%
#*CMD_Vol_Down - Decreases the volume 1%
#*CMD_Set_Volume - Sets the volume to a specific level between 0-100
#*CMD_Mute - Toggles mute/unmute
#:
#:
#It doesn’t fire any events.
#:
#:
#It has the following device data:
#*Discrete Volume
#*Volume Level

==7. Photo_Screen_Saver device==

The photo screen saver (PSS) displays pictures when there is no video playing, even if you just happen to be listening to music. By default, the photos come from Flickr and are downloaded regularly to local drive.

PSS is a OpenGL application and it slides pictures and fades them between transitions.

1. Implemented commands

The list with pictures is taken by sending a command to Orbiter Plugin : CMD_Get_Screen_Saver_Files which has an output parameter Filename. The filenames are delimited by a ‘\n’ character.

The PSS animations are started/stopped using CMD_On/CMD_Off commands. To force PSS reload the list with pictures from Orbiter Plugin, CMD_Reload is used.

When PSS starts, it should check every 10 minutes if there are any pictures downloaded and ready to be displayed. If there are pictures to display it should display them on CMD_On command and refresh the list with pictures every 24 hours.

2. It doesn’t fire any events

3. Device data:
* ZoomTime - Value in miliseconds that a zoom effect will take
* FadeTime - value in miliseconds that a fade effect will take
* Name - The window name to activate

==8. Media Player device==

Currently there are two Media Players in LinuxMCE, the primary Xine_Player and
secondary MPlayer_Player.
First one is based one the Xine engine (http://xinehq.de) and supports the
following formats:

*'''File formats (System layer / media types)supported:'''
**direct DVD playback (of unlocked/unencrypted DVDs, see below)
** Video CD
** Audio CD
** mpeg program streams (.mpg, .mpeg)
** mpeg transport streams (.ts)
** ogg (.ogg, .ogm)
** avi (.avi)
** asf (.asf, .wmv, .wma)
** quicktime (.mov, .mp4)
** mpeg-video (.mpv, .m2v)
** mpeg-audio (.mp2, .mp3)
** Sega Saturn FILM (.cpk)
** Id Software RoQ (.roq)
** wav (.wav)
** Autodesk FLIC (.fli)
** real (.rm, .ra, .ram)
** raw dv (.dv)
** network graphics format (.png, .mng)
** Creative Voice (.voc)
** Sun/NeXT SND/AU (.snd, .au)
** Wing Commander III (.mve)
** Westwood Studios files (.vqa, .aud)
** Electronic Arts WVE (.wve)
** AIFF (.aif, .aiff)
** YUV4MPEG2 (.y4m)
** SMJPEG (.mjpg)
** raw AC3 (.ac3)
** Dialogic VOX (.vox)
** TechnoTrend PVA (.pva)
** Playstation STR (.str)
** Nullsoft Video (.nsv)
** 4X Technologies (.4xm)

*'''Video codecs supported:'''
** mpeg 1/2
** mpeg 4 (aka OpenDivX)
** ms mpeg 4
** divx 3/4/5
** windows media video 7 & 8
** motion jpeg
** Cinepak
** DV
** ms video 1 (msvc)
** ms rle
** Sorenson SVQ1/SVQ3 (often used in Quicktime trailers)
** creative yuv (cyuv)
** roq video
** QT RLE, SMC, RPZA
** theora
** via external binary/win32 codecs (not included in xine):
** Indeo 3.1-5.0
** Window Media Video 8,9
** On2 VP3.1
** I263
** Real Media 2.0, 3.0, 4.0
* currently unsupported/untested Formats:
** 3ivx
** h263 (aka Real Video 1.0)

*'''Audio codecs'''
** mpeg audio (layer 1,2,3)
** a/52 (aka ac3, dolby digital)
** aac (used in .mp4 files)
** dts (via external decoder)
** vorbis
** pcm
** adpcm (MS/IMA/DVI/Dialogic)
** mu-law and A-law
** roq dpcm
** Real Media dnet audio
** Real Media 28.8 audio
** DivX audio (WMA)
** GSM 6.10
** FLAC
** NSF (NES sound format)
** Speex

The MPlayer_Player is used as the fallback player for the formats Xine doesn't
support/supports not well and currently is used for playing HD-DVD/Bluray
video files and disks.

A media player device plays all kind of media: audio and video, stored media or from cd/dvd/hd/bluray drivers, etc.

1. Implemented commands

*'''Keyboard input:'''
** CMD_EnterGo - Select the currently highlighted menu item
** CMD_Move_Up, CMD_Move_Down, CMD_Move_Left, CMD_Move_Right - Move the highlighter

*'''Media Player Commands'''
** CMD_Pause - Pause the media
** CMD_Play - Play the media
** CMD_Skip_Back_ChannelTrack_Lower - Lower the channel, track, station, etc. by 1. Same as Jump to Pos in Playlist with value -1 for a smart media player
** CMD_Skip_Fwd_ChannelTrack_Greater - Raise the channel, track, station, etc. by 1. Same as Jump to Pos in Playlist with value +1 for a smart media player
** CMD_Stop - Stop the media

*'''Menu Navigation'''
** CMD_EnterGo - Select the currently highlighted menu item
** CMD_Move_Up, CMD_Move_Down, CMD_Move_Left, CMD_Move_Right - Move the highlighter
** CMD_Get_Video_Frame - Gets the current video frame from the media player.
** CMD_Goto_Media_Menu - Goto to the current media Root Menu.
** CMD_Navigate_Next - Nagivate to the next possible navigable area. (The actual outcome depends on the specifc device)
** CMD_Navigate_Prev - Nagivate the previous possible navigable area. (The actual outcome depends on the specific device).
** CMD_Simulate_Mouse_Click - Simlate a mouse click at a certain position on the screen

*'''Smart DVD commands'''
** CMD_Angle – Go to an angle
** CMD_Audio_Track – Go to an audio track
** Subtitle – Go to a subtitle

* '''Smart Media Player'''
** CMD_Change_Playback_Speed – Will make the playback to FF with a configurable amount of speed.
** CMD_Guide - Show guide information. For a dvd this may be the menu, just like the menu command
** CMD_Jump_Position_In_Playlist - Jump to a specific position in the playlist, or a track, or a chapter. Smart media players should also understand the skip fwd/skip back (which non-DCE media players use) to be the same thing as a jump +1 or -1
** CMD_Jump_To_Position_In_Stream - Jump to a position in the stream, specified in seconds.
** CMD_Menu - Show a menu associated with this media
** CMD_Pause_Media - This will stop a media that is currently played. This method should be paired with the "Restart Media" and used when the playback will be stopped and restarted on the same display device.
** CMD_Play_Media - This command will instruct a Media Player to play a media stream identified by a media descriptor created by the "Create Media" command.
** CMD_Report_Playback_Position - This will report the playback position of the current stream.
** CMD_Restart_Media - This will restart a media was paused with the above command
** CMD_Set_Aspect_Ratio - Force aspect ratio
** CMD_Set_Media_ID - Set Media ID - information about media stream
** CMD_Set_Media_Position - Jump to a certain media position
** CMD_SetZoom - Sets zoom level, relative, absolute or 'auto'
** CMD_Simulate_Keypress - Send a key to the device's OSD, or simulate keypresses on the device's panel
** CMD_Start_Streaming - Like play media, but it means the destination device is not the same as the source
** CMD_Stop_Media - This will instruct the media player to stop the playback of a media started with the "Play Media" Command
** CMD_Update_Object_Image - Display an image on the media player

2. '''It fires the following events'''
* EVENT_Menu_Onscreen - A DVD Menu appeared on screen
* EVENT_Playblack_Completed - Fired when the playback of a stream has completed.
* EVENT_Playback_Info_Changed – Playback info changed
* EVENT_Playback_Started – Media has start playing

3. '''Device data:'''
* Name - The name of the window for this app
* Hardware acceleration - driver used
* Deinterlacing Mode - Movie deinterlacing filter status
* Port – Time code notification every second
* Zoom Level – default zoom level

'''NOTE:''' A deviation from design, the media player must bind on a port specified in the device data and report the time code every one second. Any device like an Orbiter could connect to that port and read the time code. Here is the format used for time code:
Speed,CurrentTime,TotalTime,StreamID,Title,Chapter,MediaType,MediaID,Filename (comma delimited).

==9. Orbiter==

===9.1 Introduction===

The Orbiter is really a device just like any other. The main class, Orbiter, is a normal DCE command implementation. However, the Orbiter class was written so that it has no platform-specific functions, such as graphics and sound. It handles the basic logic, and calls pure virtual functions that derived classes must implement to handle the platform-specific commands. Most of the code and virtually all of the logic is contained in the base classes. Therefore, it is a fairly easy task to make a new version of Orbiter for a platform other than SDL, perhaps one that uses Windows SDK calls, or another image library.

Right now there are implementations of Orbiter using SDL. PocketFrog and OpenGL engines. Orbiter runs on different operation systems like Linux, Windows, Windows CE, Window Mobile, Symbian60. There also implementation for web orbiter (running into a browser) or for a Cisco hard phones (using XML services).

===9.2 Architecture===

[[Image:architecture.jpg|frame|none|Orbiter application architecture]]

The present diagram shows how the Orbiter application architecture looks like. Depending on the Graphic Engine and the platform, the only modules dependent on them are “Renderers – engine specific” and “Orbiter - platform specific”.

====9.2.1. The renderers====

There are two kinds of renders:
* orbiter renderers
* object renderers

The orbiter renderers (derived from OrbiterRenderer class) handle the graphic primitives, having pure virtual methods for operations like this:
* RenderText
* SolidRectangle
* HollowRectangle
* DrawLine
* FloodFill
* RenderGraphic
* ReplaceColorInRectangle
* etc.

and applications flow :
* event loop
* configure
* destroy
* on quit
* on reload

However, OrbiterRenderer is not an interface. It also has implemented the logic needed for:
* render screen action
* show a progress bar
* highlighting / un-highlighting objects
* render shortcuts
* show / hide popup’s
* redraw objects
* refresh screen
* render object asynchronously
* object on screen / off screen actions
* background image loading
* drawing an arrow

Here is the class diagram for derived OrbiterRenderer‘s:

[[Image:orbiterrenderer.jpg|frame|none|OrbiterRenderer class diagram]]

Also, there are renderer classes of complex objects like button, data grid, edit box, etc. The base classes for them are : ObjectRenderer, DataGridRenderer. Each renderer is attached to an object like DesignObj_Orbiter, DesignObj_DataGrid.

Here is the class diagram for OpenGL implementation:

[[Image:openGLimplementation.jpg|frame|none|OpenGL implementation]]

The screens are actually trees of objects. The characteristics of the objects are set using the Designer application and stored in the database, then serialized by OrbiterGen and then deserialized by Orbiter.
OrbiterGen scales and pre-renders the screens. Also, OrbiterGen embeds in the serialized data info about the actions to be executed when an object is loaded, activated, unloaded, etc.

====9.2.2. Orbiter – platform specific====

Orbiter also has to take care of the input events like mouse click, keyboard events, etc. For example, Orbiter_Win32 is derived from Orbiter class and takes care of enabling the auto-update mechanism.
Platform specific are the external dialogs with progress bar and prompt user, or the way the composite or masks are used (see OrbiterRenderer_Linux, OrbiterLinux, OrbiterRenderer_SDL_Win32

The Linux version uses XRecord extension to intercept events. The Windows versions use PocketFrog engine’s event loop or SDL event loop.

====9.2.3. Cache image manager====

This module is mainly used by remote orbiters, non-OSD orbiters. Because these orbiters don’t have access to core’s file system, all the graphic files are obtained by network connection and it might be slow. So instead of requesting same image over and over, the image is cached on the local drivers. The collection of images cached are associated with a timestamp (the generation date for the screens). If the user decides to regenerate the screens, the timestamp is changed and the cache is purged and the images are requested, on demand, again from the server.

====9.2.4. Self update module====

The “Self update” module is also used for non-OSD orbiters. Once a new version of the Orbiter XP/CE is available, a new binary data is stored on core’s filesystem. When an non-OSD orbiter starts, compares the md5sum of the current binary with the one from the server. If it’s different, the UpdateBinary is spawned, Orbiter exits and UpdateBinary requests the new binary from server, it downloads it, replaces the old binary and restart Orbiter.

====9.2.5. Simulator====

The simulator is responsible for generating mouse and keyboard events used for stress testing. It also stores some configuration settings.

====9.2.6. Graphic objects====

They are all derived from PlutoGraphic class and store info about the filename, width, height, the block of data and its length, graphic format and graphic management. The operations required are related to loading graphics from a file or a block of data, clearing the data stored, initializations, etc.
In the derived classes like PocketFrogGraphic, SDLGraphic, OpenGLGraphic, specific info are stored like the Surface for PocketFrong, SDL_Surface for SDL and the texture for OpenGL.

====9.2.7. Orbiter logic module====

Just like any other device, Orbiter is derived from a {Device_name}_Command class, the wrapper class generated by DCEGen to allow the device communicate with the router. However, Orbiter is also derived from OrbiterData and IRReceiverBase.

[[Image:orbiterlogicclassdiagram.jpg|frame|none|Orbiter logic – class diagram]]

OrbiterData helps Orbiter deserialize the data needed for its graphic objects, data serialized by OrbiterGen. IRReceiverBase is the base class for all IR receiver devices and it translates IR codes into actions, base on the current screen type and remote layout.

====9.2.7. Mouse handlers====

The goal of handlers is the interpret mouse movements and perform specific actions depending on current screen type. This is one of the main features add in UI2 version.

See below the class diagram:

[[Image:mousehandlers.jpg|frame|none|Mouse handlers – class diagram]]

Note that the mouse handlers are not available for UI1 version of Orbiter.

MouseIterator and MouseGovernor limit the mouse movements the only one move per x ms to prevent extreme numbers of messages burdening the system.
MouseBehaviour handles special mouse behavior, such as locking axis’s, ramping and acceleration.

====9.2.7. HID interface====

This module gets events from the Gyration remote. See below the class diagram:

[[Image:HIDinterface.jpg|frame|none|HID interface – class diagram]]

===9.3 Skinning and User Interface===

====9.3.1 HADesigner====
The graphics, layout and display for the screens rendered in different Orbiter interfaces for the different UI versions are generated and manipulated using a Windows UI management tool called [[HADesigner_User's_manual|HADesigner]].

The following series of screencasts describes the use of the HADesigner tool and the process of generating a brand new UI for a specific plugin for all different variations of the Orbiter UI versions.

Before proceeding, follow the [[Installing_HADesigner | installation instructions for HADesigner]].

# [http://www.localeconcept.com/HADesigner-Screencasts/01-basic_hadesigner_fundamentals.html Basic Designer Fundamentals]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/02_designobj_basics_1.ogg Design Object Basics]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/03_ui2_popup_part_1.ogg UI2 Popup Part I]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/04_ui2_popup_part_2.ogg UI2 Popup Part II]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/05_UI1_Orbiter.ogg UI1 Orbiter]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/06_UI1_Full_Screen_OSD.ogg UI1 Full Screen OSD]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/07_UI1_Full_Screen_OSD_2.ogg UI1 Full Screen OSD Part II]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/08_UI1_PDA.ogg UI1 PDA]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/09_Mobile_Remote.ogg Mobile Remote]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/10_cisco_7970_orbiter.ogg Cisco 7970 Orbiter]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/11_Monitor_mode.ogg Monitor Mode]

The Basic skin, included with LinuxMCE, should really not be modified, since it is used extensively by LinuxMCE and Pluto and is known to work.

====9.3.2 UI Design and process====
The following series of screencasts walks through the design considerations involved in creating a brand new skin for LinuxMCE.

# [http://www.localeconcept.com/Skin-Screencasts/01_introduction_and_aesthetic.ogg Introduction and Aesthetic considerations]
# [http://www.localeconcept.com/Skin-Screencasts/02_main_menu_first_pass.ogg First Pass at the Main Menu]
# [http://www.localeconcept.com/Skin-Screencasts/03_main_menu_notes_and_corrections.ogg Main Menu Notes and Corrections]
# [http://www.localeconcept.com/Skin-Screencasts/04_the_floorplan_buttons.ogg The Floorplan Buttons]

Designer User's manual

2008-08-01T15:25:38Z

Juanfe: Designer User's manual moved to HADesigner User's manual: More descriptive of the function

#REDIRECT [[HADesigner User's manual]]

HADesigner User's manual

2008-08-01T15:25:38Z

Juanfe: Designer User's manual moved to HADesigner User's manual: More descriptive of the function

Here is a link to the Orbiter Design Program (HADesigner) documentation.

* [http://www.localeconcept.com/pub/HADesigner/HADesigner_user_manual.pdf HADesigner Manual]

[[Category: Programmer's Guide]]

Developers Guide

2008-07-31T15:52:57Z

Juanfe: /* 9.3.1 HADesigner */

[[Category: Programmer's Guide]]

{| align="right"
| __TOC__
|}
LinuxMCE developer’s guide
Document version 1.0

==1. Architecture==

LinuxMCE uses a modular architecture. The heart of LinuxMCE, the 'main application' DCERouter is nothing but a general-purpose message router. It has absolutely no code relating to any of LinuxMCE’s functionality--it just relays messages between "Devices". The functionality of LinuxMCE is entirely in separate programs (aka "Devices") which all run independently and communicate with each other by passing messages through DCERouter over sockets.

[[Image:LMCE_Architecture_mini.jpg|frame|none|LinuxMCE architecture – the devices]]

The plug-in’s are also devices, but instead of running as separate binaries, they run as dynamic libraries in DCERouter’s memory space.
A LinuxMCE system can have one or more Media Directors (MD’s). Also, a Core machine can have also the functionality of a Media Director. We call it a Hybrid:

[[Image:LMCE_Architecture_-_the_machines.jpg|frame|none|Linux MCE architecture – the machines]]

==2. DCE==

DCE (Data, Commands and Events) is a lightweight network protocol allowing any device to access its configuration (ie data) from a central database, send + receive commands, and fire + respond to events.

The DCE protocol can be implemented with any device that supports standard networking. LinuxMCE provides a DCE library written in Ansi C++ that implements the protocol on any socket-compatible operating system, and has been tested on Linux and Windows. Porting to other languages should not be a big task. Because the messaging is socket-based, any device, regardless of operating system or language, can be used with any other device.

In each installation there is also one DCE Router, through which all messages are routed. An "installation" is a group of devices treated as a unit, and normally corresponds to a physical residence.

The DCE Router is itself quite simple. It just opens a port for incoming connections. When a device connects, the device sends its unique ID, or Mac Address. The DCE Router does a lookup in a database, and returns that device's data (configuration). DCERouter also sends back a list of all the other devices in the installation with basic information including the commands they know how to implement. The DCE Device then opens a minimum of 2 socket connections to the router. One is for incoming messages (usually commands) from the router, another for outgoing messages (usually events) to it. The DCE Library, which implements the protocol for DCE Devices and the DCE Router, will also open a 3rd socket connection so that it has 2 outgoing sockets: 1 dedicated for sending events and the other for sending other types of messages, like requests and commands to other devices.

All messages go through the router. The devices do not communicate directly to each other. The message will contain information such as the destination device, the type of message, the message id and any number of optional parameters. The router does nothing with the message but forward it to the destination device or devices if the message is being sent to more than one. The DCE library, from which DCE Devices and the DCE Router are derived, knows how to receive incoming messages of the type command and route them to a message handler in the DCE Device.

Another important library is PlutoUtils. It has cross-platform wrapper classes to handle file, strings, processes, threads synchronization, database utils, etc.

==3. DCERouter==

When a DCE Device connects, DCERouter gives it its configuration data and is responsible for receiving and forwarding any messages to and from the devices that connect to it. The most common types of messages are commands and events. All communication goes through DCE Router. If a doorbell device fires an event that the button was pushed, that event goes to DCERouter, which will forward it whatever plug-in has indicated it wants to handle that type of event. If the plug-in then wants to send a command to the media player, this command goes first to the DCE Router, which will then forward it to the media player. The DCE Devices never communicate with each other directly--everything goes through DCE Router. Devices can create their own types of messages specific to them--not just commands and events. For example, a DVD player may send a message that contains a screen capture, or a TV program may send a stream of messages with streaming video. To DCE Router it makes no difference. Messages just have sources and destinations, and DCE Router does not care what type of message it is.

DCERouter also allows you to Message Interceptors. This means a device or plug-in can say that it wants to pre-process all messages that meet a certain criteria. For example, a security plug-in may want to see all events relating to security.
Plug-in’s are DCE Devices that run within the DCERouter's memory space. They are DCE Devices just like any other and they are created like any other DCE Device. The code is the same, it's just a compilation option whether the device is built as a normal DCE Device, which runs in its own memory space and communicates with DCERouter over a socket, or if it's a plug-in which gets loaded into DCERouter's memory space. Plug-in’s have the ability to get pointers to the in-memory instance of the other plug-ins so they can share memory and call each others methods.

See below a simplified class diagram for DCERouter:
[[Image:DCERouter.jpg|frame|none|Simplified class diagram for the DCE router]]

==4. The binary communication protocol==

===4.1 Introduction===
A device can create a command connection and one or more event connections to the router.
*The command connection is used as an incoming connection and device will use it to receive message from the router (commands).
*An event connection is used by the device as an outgoing connection to notify the router about events or the deliver commands to other devices.
The DCERouter process is listening on 3450 port.

===4.2. How to create an event connection===
Here is how the handshake is made for an event connection:

>> Device sends:
EVENT <my_device_id> '\n'

<< The router will respond with :
OK <my_device_id> IP=<device_ip_address> '\n'

>> To send a message, the device will send :
MESSAGE <size_of_binary_message> '\n'

and then:
<serialized_binary_message>

===4.3 How to serialize data===
DCE uses SerializeClass to serialize/deserialize data.
The sources can be found here : src/SerializeClass/Serialize.h/cpp.
The deserialize the data, the deserializing module must know the way the data was serialized like this:
* 4 bytes, unsigned long
* 1 byte, unsigned char

Primitives:
* 8 bytes, unsigned int64
* 8 bytes, int64
* 4 bytes, unsigned long
* 4 bytes, unsigned short
* 1 byte, unsigned char
* 1 byte, char
* 4 byte, long
* 4 bytes, float
* 8 bytes, double
* 2 bytes, short

Complex types:

#string
#*STR_LENGTH bytes, the array with chars
#*1 byte, '/0' (value 0x00)
#:
#block of data
#*BLOCK_LENGTH bytes, the array with bytes
#:
#vector of strings
#*VECT_LENGTH bytes, the number of strings from vector
#*string 0
#*string 1
#*...
#*string VECT_LENGTH - 1

Other complex types serialized (see SerializeClass.cpp for details) :
* map<int,string>
* map<u_int64_t,string>
* map<int,int>
* map<string,string>
* vector<int>
* vector< pair<int,int> >
* map<string, pair<int,int> >

SerializeClass also allowed you to serialize/deserialize custom objects. Examples:
* PlutoColor
* PlutoPoint
* PlutoSize
* PlutoRectangle
* PlutoDataBlock

===4.4 How to serialize a message===

The class used by DCE is Message class from src/DCE/Message.h/cpp unit.

This is how the raw data looks like into a binary message:

* long, value must be 1234 (magic number)
* long, <device_from_id>
* long, <device_to_id>
* long, <device_group_to_id>
* long, <message_id>
* long, <message_priority>
* long, <message_type>
* long, <device_category_to>
* long, <device_template_to>
* unsigned char, <include_children>
* long, <message_broadcast_level>
* long, <message_retry>
* unsigned char, <relative_to_sender>
* long, <expected_response>
* string, <device_list_to>
* unsigned long, <number_of_string_parameters>
** foreach <string_parameter>
*** long, <string_parameter_id>
*** string, <string_parameter_value>
** end_foreach
* unsigned long, <number_of_data_parameters>
** foreach <data_parameter>
*** long, <data_parameter_id>
*** unsigned long, <data_parameter_length>
*** array of bytes, <data_parameter_value>
** end_foreach
* unsigned long, <number_of_extra_messages>
** foreach <extra_message>
*** unsigned long, <serialized_extra_message_length>
*** array of bytes, <serialized_extra_message_value>
** end_foreach
* unsigned long, must be 6789

'''Enums:'''
* enum eBroadcastLevel { BL_None=0, BL_DirectSiblings=1, BL_SameComputer=2, BL_SameRoom=3, BL_SameHouse=4, BL_AllHouses=5 };
* enum eRetry { MR_None=0, MR_Retry=1, MR_Persist=2 };
* enum eExpectedResponse { ER_None=0, ER_ReplyMessage, ER_ReplyString, ER_DeliveryConfirmation };
* message types: enum { MESSAGETYPE_COMMAND=1, MESSAGETYPE_EVENT=2, MESSAGETYPE_DATAPARM_CHANGE=3, MESSAGETYPE_REPLY=4, MESSAGETYPE_DATAPARM_REQUEST=5, MESSAGETYPE_LOG=6, MESSAGETYPE_SYSCOMMAND=7, MESSAGETYPE_REGISTER_INTERCEPTOR=8, MESSAGETYPE_MESSAGE_INTERCEPTED=9, MESSAGETYPE_EXEC_COMMAND_GROUP=10, MESSAGETYPE_START_PING=11, MESSAGETYPE_STOP_PING=12, MESSAGETYPE_PURGE_INTERCEPTORS=13, MESSAGETYPE_PENDING_TASKS=14 };
* message priority : enum { PRIORITY_LOW=0, PRIORITY_NORMAL=1, PRIORITY_HIGH=2, PRIORITY_URGENT=3 };

'''Important notes:'''
* when sending to device template, set <device_template_to> to desired device template and also <device_to_id> to -2000 (DEVICEID_MASTERDEVICE)
* when sending to device category, set <device_category_to> to desired device category and also <device_to_id> to -2001 (DEVICEID_CATEGORY)
* when sending to a list with devices, set <device_list_to> to comma delimited list with devices and also <device_to_id> to -2002 (DEVICEID_LIST).

'''Example:'''
Here is the pseudocode to send the "on" command to a light switch.
We'll assume that the your device has #id 250 and the light switch has device #id 100

*MyDevice.Connect(router_ip, 3450 /*port*/)
*MyDevice.SendData("EVENT 250\n")
*MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK 250 IP=<device_ip_address> '\n';

'''next: creating a message'''
let's say MyData is an array of bytes
*SerializeLong(MyData, 1234) //magic number
*SerializeLong(MyData, 250) //my id
*SerializeLong(MyData, 100) //the light switch
*SerializeLong(MyData, 0) //not used now
*SerializeLong(MyData, 192) //message id of command 'on'
*SerializeLong(MyData, 1) //normal priority
*SerializeLong(MyData, 1) //message type : command
*SerializeLong(MyData, 0) //not used now
*SerializeLong(MyData, 0) //not used now
*SerializeUnsignedChar(MyData, 0) //not including children
*SerializeLong(MyData, 0) //broadcast level : none
*SerializeLong(MyData, 0) //don't retry
*SerializeUnsignedChar(MyData, 0) //relative to sender false
*SerializeLong(MyData, 3) //delivery confirmation
*SerializeString(MyData, "") //device list to empty
*SerializeUnsignedLong(MyData, 2) //2 parameters
*SerializeLong(MyData, 98) //parameter type #98
*SerializeString(MyData, "") //empty value
*SerializeLong(MyData, 97) //parameter type #97
*SerializeString(MyData, "") //empty value
*SerializeUnsignedLong(MyData, 0) //no binary parameters
*SerializeUnsignedLong(MyData, 0) //no extra messages
*SerializeUnsignedLong(6789) //magic number

*MyDevice.SendData("MESSAGE " + MyData.length() + '\n')
*MyDevice.SendData(MyData)
*MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK" or an error message

*MyDevice.CloseConnection();

===4.5 How to serialize data-grids ===
'''Complex objects:'''
# DataGridCellSerializableData
#* unsigned long, <sizeof(DataGridCellSerializableData)>
#* unsigned long, <graphic_length>
#* unsigned long, <message_length>
#* unsigned long, <text_length>
#* unsigned long, <value_length>
#* unsigned long, <image_path_length>
#* unsigned long, <number_of_attributes_length>
#* unsigned long, <attributes_length>
#* int, <alternate_color>
#* unsigned long, <graphic_format>
#* unsigned char, <selectable>
#* int, <style_detail>
#* int, <col_span>
#* int, <row_span>
#* unsigned char, <dont_fire_grid_event>
#:
#:Enums:
#* enum eGraphicFormat { GR_UNKNOWN=0, GR_JPG=1, GR_GIF=2, GR_TIF=3, GR_PNG=4, GR_MNG=5, GR_BMP=6, GR_OCG=7, GR_PFG=8 };
#:
# DataGridCell
#* DataGridCellSerializableData, <datagrid_cell_serializable_data>
#* array of chars, <text>
#* array of chars, <value>
#* array of bytes, <graphic_data>
#* array of bytes, <message_data>
#* array of chars, <image_path>
#*:
#** foreach <cell_attribute>
#*** array of chars ended with '\0' , <cell_attribute_name>
#*** array of chars ended with '\0', <cell_attribute_value>
#** end_foreach
#:
#DataGridTableSerializableData
#* int, <total_number_of_columns>
#* int, <total_number_of_rows>
#* unsigned char, <keep_row_header>
#* unsigned char, <keep_column_header>
#* int, <column_count>
#* int, <row_count>
#* int, <starting_column>
#* int, <starting_row>
#* int, <cell_count>
#:
#DataGridTableCellIndex
#* unsigned int, <column_row_type>
#* unsigned int, <size>
#:
#DataGridTable
#* unsigned long, <sizeof(DataGridTableSerializableData)>
#* array of DataGridTableCellIndex, <col * row * sizeof(DataGridTableCellIndex)>
#* array of DataGridCell, <col * row * serialized DataGridCell>

----
Additional step: lzo compression/decompression

'''Note:''' can be disabled if compiled with DISABLE_LZO_DATAGRID
----

==5. The devices==

Each device has associated an interface, which we call device template. A device template is a set of commands to be implemented, events which can be fired by the device and device data (persistent information for device).
To create device templates and modify them, go to LinuxMCE Web Admin -> Advanced -> Configuration -> Device Templates.
To generate the C++ code for the device implementing a device template interface, you must use DCEGen tool, specifying the database ip address and the device template number.
Here is the simplified class diagram for one of the devices (App_Server):

[[Image:App_Server.jpg|frame|none|Simplified class diagram for a DCE device]]

The classes App_Server_Event, App_Server_Command and App_Server_Data are generated using DCEGen tool. The base classes for them are implemented in DCE Library.

==6. App_Server device==

App_Server device is present by default on all LinuxMCE machines. It spawns/kills applications, handles volume of sound on that machine, restarts/halts the device.

# Implemented commands:
#*CMD_Spawn_Application - Spawns an application
#*CMD_Kill_Application - Kills an application
#*CMD_Application_Is_Running - Checks if the given application is running.
#*CMD_Halt_Device - Halts or reboots this device
#*CMD_Vol_Up - Increases the volume 1%
#*CMD_Vol_Down - Decreases the volume 1%
#*CMD_Set_Volume - Sets the volume to a specific level between 0-100
#*CMD_Mute - Toggles mute/unmute
#:
#:
#It doesn’t fire any events.
#:
#:
#It has the following device data:
#*Discrete Volume
#*Volume Level

==7. Photo_Screen_Saver device==

The photo screen saver (PSS) displays pictures when there is no video playing, even if you just happen to be listening to music. By default, the photos come from Flickr and are downloaded regularly to local drive.

PSS is a OpenGL application and it slides pictures and fades them between transitions.

1. Implemented commands

The list with pictures is taken by sending a command to Orbiter Plugin : CMD_Get_Screen_Saver_Files which has an output parameter Filename. The filenames are delimited by a ‘\n’ character.

The PSS animations are started/stopped using CMD_On/CMD_Off commands. To force PSS reload the list with pictures from Orbiter Plugin, CMD_Reload is used.

When PSS starts, it should check every 10 minutes if there are any pictures downloaded and ready to be displayed. If there are pictures to display it should display them on CMD_On command and refresh the list with pictures every 24 hours.

2. It doesn’t fire any events

3. Device data:
* ZoomTime - Value in miliseconds that a zoom effect will take
* FadeTime - value in miliseconds that a fade effect will take
* Name - The window name to activate

==8. Media Player device==

Currently there are two Media Players in LinuxMCE, the primary Xine_Player and
secondary MPlayer_Player.
First one is based one the Xine engine (http://xinehq.de) and supports the
following formats:

*'''File formats (System layer / media types)supported:'''
**direct DVD playback (of unlocked/unencrypted DVDs, see below)
** Video CD
** Audio CD
** mpeg program streams (.mpg, .mpeg)
** mpeg transport streams (.ts)
** ogg (.ogg, .ogm)
** avi (.avi)
** asf (.asf, .wmv, .wma)
** quicktime (.mov, .mp4)
** mpeg-video (.mpv, .m2v)
** mpeg-audio (.mp2, .mp3)
** Sega Saturn FILM (.cpk)
** Id Software RoQ (.roq)
** wav (.wav)
** Autodesk FLIC (.fli)
** real (.rm, .ra, .ram)
** raw dv (.dv)
** network graphics format (.png, .mng)
** Creative Voice (.voc)
** Sun/NeXT SND/AU (.snd, .au)
** Wing Commander III (.mve)
** Westwood Studios files (.vqa, .aud)
** Electronic Arts WVE (.wve)
** AIFF (.aif, .aiff)
** YUV4MPEG2 (.y4m)
** SMJPEG (.mjpg)
** raw AC3 (.ac3)
** Dialogic VOX (.vox)
** TechnoTrend PVA (.pva)
** Playstation STR (.str)
** Nullsoft Video (.nsv)
** 4X Technologies (.4xm)

*'''Video codecs supported:'''
** mpeg 1/2
** mpeg 4 (aka OpenDivX)
** ms mpeg 4
** divx 3/4/5
** windows media video 7 & 8
** motion jpeg
** Cinepak
** DV
** ms video 1 (msvc)
** ms rle
** Sorenson SVQ1/SVQ3 (often used in Quicktime trailers)
** creative yuv (cyuv)
** roq video
** QT RLE, SMC, RPZA
** theora
** via external binary/win32 codecs (not included in xine):
** Indeo 3.1-5.0
** Window Media Video 8,9
** On2 VP3.1
** I263
** Real Media 2.0, 3.0, 4.0
* currently unsupported/untested Formats:
** 3ivx
** h263 (aka Real Video 1.0)

*'''Audio codecs'''
** mpeg audio (layer 1,2,3)
** a/52 (aka ac3, dolby digital)
** aac (used in .mp4 files)
** dts (via external decoder)
** vorbis
** pcm
** adpcm (MS/IMA/DVI/Dialogic)
** mu-law and A-law
** roq dpcm
** Real Media dnet audio
** Real Media 28.8 audio
** DivX audio (WMA)
** GSM 6.10
** FLAC
** NSF (NES sound format)
** Speex

The MPlayer_Player is used as the fallback player for the formats Xine doesn't
support/supports not well and currently is used for playing HD-DVD/Bluray
video files and disks.

A media player device plays all kind of media: audio and video, stored media or from cd/dvd/hd/bluray drivers, etc.

1. Implemented commands

*'''Keyboard input:'''
** CMD_EnterGo - Select the currently highlighted menu item
** CMD_Move_Up, CMD_Move_Down, CMD_Move_Left, CMD_Move_Right - Move the highlighter

*'''Media Player Commands'''
** CMD_Pause - Pause the media
** CMD_Play - Play the media
** CMD_Skip_Back_ChannelTrack_Lower - Lower the channel, track, station, etc. by 1. Same as Jump to Pos in Playlist with value -1 for a smart media player
** CMD_Skip_Fwd_ChannelTrack_Greater - Raise the channel, track, station, etc. by 1. Same as Jump to Pos in Playlist with value +1 for a smart media player
** CMD_Stop - Stop the media

*'''Menu Navigation'''
** CMD_EnterGo - Select the currently highlighted menu item
** CMD_Move_Up, CMD_Move_Down, CMD_Move_Left, CMD_Move_Right - Move the highlighter
** CMD_Get_Video_Frame - Gets the current video frame from the media player.
** CMD_Goto_Media_Menu - Goto to the current media Root Menu.
** CMD_Navigate_Next - Nagivate to the next possible navigable area. (The actual outcome depends on the specifc device)
** CMD_Navigate_Prev - Nagivate the previous possible navigable area. (The actual outcome depends on the specific device).
** CMD_Simulate_Mouse_Click - Simlate a mouse click at a certain position on the screen

*'''Smart DVD commands'''
** CMD_Angle – Go to an angle
** CMD_Audio_Track – Go to an audio track
** Subtitle – Go to a subtitle

* '''Smart Media Player'''
** CMD_Change_Playback_Speed – Will make the playback to FF with a configurable amount of speed.
** CMD_Guide - Show guide information. For a dvd this may be the menu, just like the menu command
** CMD_Jump_Position_In_Playlist - Jump to a specific position in the playlist, or a track, or a chapter. Smart media players should also understand the skip fwd/skip back (which non-DCE media players use) to be the same thing as a jump +1 or -1
** CMD_Jump_To_Position_In_Stream - Jump to a position in the stream, specified in seconds.
** CMD_Menu - Show a menu associated with this media
** CMD_Pause_Media - This will stop a media that is currently played. This method should be paired with the "Restart Media" and used when the playback will be stopped and restarted on the same display device.
** CMD_Play_Media - This command will instruct a Media Player to play a media stream identified by a media descriptor created by the "Create Media" command.
** CMD_Report_Playback_Position - This will report the playback position of the current stream.
** CMD_Restart_Media - This will restart a media was paused with the above command
** CMD_Set_Aspect_Ratio - Force aspect ratio
** CMD_Set_Media_ID - Set Media ID - information about media stream
** CMD_Set_Media_Position - Jump to a certain media position
** CMD_SetZoom - Sets zoom level, relative, absolute or 'auto'
** CMD_Simulate_Keypress - Send a key to the device's OSD, or simulate keypresses on the device's panel
** CMD_Start_Streaming - Like play media, but it means the destination device is not the same as the source
** CMD_Stop_Media - This will instruct the media player to stop the playback of a media started with the "Play Media" Command
** CMD_Update_Object_Image - Display an image on the media player

2. '''It fires the following events'''
* EVENT_Menu_Onscreen - A DVD Menu appeared on screen
* EVENT_Playblack_Completed - Fired when the playback of a stream has completed.
* EVENT_Playback_Info_Changed – Playback info changed
* EVENT_Playback_Started – Media has start playing

3. '''Device data:'''
* Name - The name of the window for this app
* Hardware acceleration - driver used
* Deinterlacing Mode - Movie deinterlacing filter status
* Port – Time code notification every second
* Zoom Level – default zoom level

'''NOTE:''' A deviation from design, the media player must bind on a port specified in the device data and report the time code every one second. Any device like an Orbiter could connect to that port and read the time code. Here is the format used for time code:
Speed,CurrentTime,TotalTime,StreamID,Title,Chapter,MediaType,MediaID,Filename (comma delimited).

==9. Orbiter==

===9.1 Introduction===

The Orbiter is really a device just like any other. The main class, Orbiter, is a normal DCE command implementation. However, the Orbiter class was written so that it has no platform-specific functions, such as graphics and sound. It handles the basic logic, and calls pure virtual functions that derived classes must implement to handle the platform-specific commands. Most of the code and virtually all of the logic is contained in the base classes. Therefore, it is a fairly easy task to make a new version of Orbiter for a platform other than SDL, perhaps one that uses Windows SDK calls, or another image library.

Right now there are implementations of Orbiter using SDL. PocketFrog and OpenGL engines. Orbiter runs on different operation systems like Linux, Windows, Windows CE, Window Mobile, Symbian60. There also implementation for web orbiter (running into a browser) or for a Cisco hard phones (using XML services).

===9.2 Architecture===

[[Image:architecture.jpg|frame|none|Orbiter application architecture]]

The present diagram shows how the Orbiter application architecture looks like. Depending on the Graphic Engine and the platform, the only modules dependent on them are “Renderers – engine specific” and “Orbiter - platform specific”.

====9.2.1. The renderers====

There are two kinds of renders:
* orbiter renderers
* object renderers

The orbiter renderers (derived from OrbiterRenderer class) handle the graphic primitives, having pure virtual methods for operations like this:
* RenderText
* SolidRectangle
* HollowRectangle
* DrawLine
* FloodFill
* RenderGraphic
* ReplaceColorInRectangle
* etc.

and applications flow :
* event loop
* configure
* destroy
* on quit
* on reload

However, OrbiterRenderer is not an interface. It also has implemented the logic needed for:
* render screen action
* show a progress bar
* highlighting / un-highlighting objects
* render shortcuts
* show / hide popup’s
* redraw objects
* refresh screen
* render object asynchronously
* object on screen / off screen actions
* background image loading
* drawing an arrow

Here is the class diagram for derived OrbiterRenderer‘s:

[[Image:orbiterrenderer.jpg|frame|none|OrbiterRenderer class diagram]]

Also, there are renderer classes of complex objects like button, data grid, edit box, etc. The base classes for them are : ObjectRenderer, DataGridRenderer. Each renderer is attached to an object like DesignObj_Orbiter, DesignObj_DataGrid.

Here is the class diagram for OpenGL implementation:

[[Image:openGLimplementation.jpg|frame|none|OpenGL implementation]]

The screens are actually trees of objects. The characteristics of the objects are set using the Designer application and stored in the database, then serialized by OrbiterGen and then deserialized by Orbiter.
OrbiterGen scales and pre-renders the screens. Also, OrbiterGen embeds in the serialized data info about the actions to be executed when an object is loaded, activated, unloaded, etc.

====9.2.2. Orbiter – platform specific====

Orbiter also has to take care of the input events like mouse click, keyboard events, etc. For example, Orbiter_Win32 is derived from Orbiter class and takes care of enabling the auto-update mechanism.
Platform specific are the external dialogs with progress bar and prompt user, or the way the composite or masks are used (see OrbiterRenderer_Linux, OrbiterLinux, OrbiterRenderer_SDL_Win32

The Linux version uses XRecord extension to intercept events. The Windows versions use PocketFrog engine’s event loop or SDL event loop.

====9.2.3. Cache image manager====

This module is mainly used by remote orbiters, non-OSD orbiters. Because these orbiters don’t have access to core’s file system, all the graphic files are obtained by network connection and it might be slow. So instead of requesting same image over and over, the image is cached on the local drivers. The collection of images cached are associated with a timestamp (the generation date for the screens). If the user decides to regenerate the screens, the timestamp is changed and the cache is purged and the images are requested, on demand, again from the server.

====9.2.4. Self update module====

The “Self update” module is also used for non-OSD orbiters. Once a new version of the Orbiter XP/CE is available, a new binary data is stored on core’s filesystem. When an non-OSD orbiter starts, compares the md5sum of the current binary with the one from the server. If it’s different, the UpdateBinary is spawned, Orbiter exits and UpdateBinary requests the new binary from server, it downloads it, replaces the old binary and restart Orbiter.

====9.2.5. Simulator====

The simulator is responsible for generating mouse and keyboard events used for stress testing. It also stores some configuration settings.

====9.2.6. Graphic objects====

They are all derived from PlutoGraphic class and store info about the filename, width, height, the block of data and its length, graphic format and graphic management. The operations required are related to loading graphics from a file or a block of data, clearing the data stored, initializations, etc.
In the derived classes like PocketFrogGraphic, SDLGraphic, OpenGLGraphic, specific info are stored like the Surface for PocketFrong, SDL_Surface for SDL and the texture for OpenGL.

====9.2.7. Orbiter logic module====

Just like any other device, Orbiter is derived from a {Device_name}_Command class, the wrapper class generated by DCEGen to allow the device communicate with the router. However, Orbiter is also derived from OrbiterData and IRReceiverBase.

[[Image:orbiterlogicclassdiagram.jpg|frame|none|Orbiter logic – class diagram]]

OrbiterData helps Orbiter deserialize the data needed for its graphic objects, data serialized by OrbiterGen. IRReceiverBase is the base class for all IR receiver devices and it translates IR codes into actions, base on the current screen type and remote layout.

====9.2.7. Mouse handlers====

The goal of handlers is the interpret mouse movements and perform specific actions depending on current screen type. This is one of the main features add in UI2 version.

See below the class diagram:

[[Image:mousehandlers.jpg|frame|none|Mouse handlers – class diagram]]

Note that the mouse handlers are not available for UI1 version of Orbiter.

MouseIterator and MouseGovernor limit the mouse movements the only one move per x ms to prevent extreme numbers of messages burdening the system.
MouseBehaviour handles special mouse behavior, such as locking axis’s, ramping and acceleration.

====9.2.7. HID interface====

This module gets events from the Gyration remote. See below the class diagram:

[[Image:HIDinterface.jpg|frame|none|HID interface – class diagram]]

===9.3 Skinning and User Interface===

====9.3.1 HADesigner====
The graphics, layout and display for the screens rendered in different Orbiter interfaces for the different UI versions are generated and manipulated using a Windows UI management tool called [http://wiki.linuxmce.org/index.php/Installing_HADesigner HADesigner].

The following series of screencasts describes the use of the HADesigner tool and the process of generating a brand new UI for a specific plugin for all different variations of the Orbiter UI versions.

# [http://www.localeconcept.com/HADesigner-Screencasts/01-basic_hadesigner_fundamentals.html Basic Designer Fundamentals]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/02_designobj_basics_1.ogg Design Object Basics]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/03_ui2_popup_part_1.ogg UI2 Popup Part I]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/04_ui2_popup_part_2.ogg UI2 Popup Part II]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/05_UI1_Orbiter.ogg UI1 Orbiter]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/06_UI1_Full_Screen_OSD.ogg UI1 Full Screen OSD]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/07_UI1_Full_Screen_OSD_2.ogg UI1 Full Screen OSD Part II]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/08_UI1_PDA.ogg UI1 PDA]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/09_Mobile_Remote.ogg Mobile Remote]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/10_cisco_7970_orbiter.ogg Cisco 7970 Orbiter]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/11_Monitor_mode.ogg Monitor Mode]

The Basic skin, included with LinuxMCE, should really not be modified, since it is used extensively by LinuxMCE and Pluto and is known to work.

====9.3.2 UI Design and process====
The following series of screencasts walks through the design considerations involved in creating a brand new skin for LinuxMCE.

# [http://www.localeconcept.com/Skin-Screencasts/01_introduction_and_aesthetic.ogg Introduction and Aesthetic considerations]
# [http://www.localeconcept.com/Skin-Screencasts/02_main_menu_first_pass.ogg First Pass at the Main Menu]
# [http://www.localeconcept.com/Skin-Screencasts/03_main_menu_notes_and_corrections.ogg Main Menu Notes and Corrections]
# [http://www.localeconcept.com/Skin-Screencasts/04_the_floorplan_buttons.ogg The Floorplan Buttons]

Developers Guide

2008-07-31T15:51:25Z

Juanfe: /* 9.3 Skinning and User Interface */

[[Category: Programmer's Guide]]

{| align="right"
| __TOC__
|}
LinuxMCE developer’s guide
Document version 1.0

==1. Architecture==

LinuxMCE uses a modular architecture. The heart of LinuxMCE, the 'main application' DCERouter is nothing but a general-purpose message router. It has absolutely no code relating to any of LinuxMCE’s functionality--it just relays messages between "Devices". The functionality of LinuxMCE is entirely in separate programs (aka "Devices") which all run independently and communicate with each other by passing messages through DCERouter over sockets.

[[Image:LMCE_Architecture_mini.jpg|frame|none|LinuxMCE architecture – the devices]]

The plug-in’s are also devices, but instead of running as separate binaries, they run as dynamic libraries in DCERouter’s memory space.
A LinuxMCE system can have one or more Media Directors (MD’s). Also, a Core machine can have also the functionality of a Media Director. We call it a Hybrid:

[[Image:LMCE_Architecture_-_the_machines.jpg|frame|none|Linux MCE architecture – the machines]]

==2. DCE==

DCE (Data, Commands and Events) is a lightweight network protocol allowing any device to access its configuration (ie data) from a central database, send + receive commands, and fire + respond to events.

The DCE protocol can be implemented with any device that supports standard networking. LinuxMCE provides a DCE library written in Ansi C++ that implements the protocol on any socket-compatible operating system, and has been tested on Linux and Windows. Porting to other languages should not be a big task. Because the messaging is socket-based, any device, regardless of operating system or language, can be used with any other device.

In each installation there is also one DCE Router, through which all messages are routed. An "installation" is a group of devices treated as a unit, and normally corresponds to a physical residence.

The DCE Router is itself quite simple. It just opens a port for incoming connections. When a device connects, the device sends its unique ID, or Mac Address. The DCE Router does a lookup in a database, and returns that device's data (configuration). DCERouter also sends back a list of all the other devices in the installation with basic information including the commands they know how to implement. The DCE Device then opens a minimum of 2 socket connections to the router. One is for incoming messages (usually commands) from the router, another for outgoing messages (usually events) to it. The DCE Library, which implements the protocol for DCE Devices and the DCE Router, will also open a 3rd socket connection so that it has 2 outgoing sockets: 1 dedicated for sending events and the other for sending other types of messages, like requests and commands to other devices.

All messages go through the router. The devices do not communicate directly to each other. The message will contain information such as the destination device, the type of message, the message id and any number of optional parameters. The router does nothing with the message but forward it to the destination device or devices if the message is being sent to more than one. The DCE library, from which DCE Devices and the DCE Router are derived, knows how to receive incoming messages of the type command and route them to a message handler in the DCE Device.

Another important library is PlutoUtils. It has cross-platform wrapper classes to handle file, strings, processes, threads synchronization, database utils, etc.

==3. DCERouter==

When a DCE Device connects, DCERouter gives it its configuration data and is responsible for receiving and forwarding any messages to and from the devices that connect to it. The most common types of messages are commands and events. All communication goes through DCE Router. If a doorbell device fires an event that the button was pushed, that event goes to DCERouter, which will forward it whatever plug-in has indicated it wants to handle that type of event. If the plug-in then wants to send a command to the media player, this command goes first to the DCE Router, which will then forward it to the media player. The DCE Devices never communicate with each other directly--everything goes through DCE Router. Devices can create their own types of messages specific to them--not just commands and events. For example, a DVD player may send a message that contains a screen capture, or a TV program may send a stream of messages with streaming video. To DCE Router it makes no difference. Messages just have sources and destinations, and DCE Router does not care what type of message it is.

DCERouter also allows you to Message Interceptors. This means a device or plug-in can say that it wants to pre-process all messages that meet a certain criteria. For example, a security plug-in may want to see all events relating to security.
Plug-in’s are DCE Devices that run within the DCERouter's memory space. They are DCE Devices just like any other and they are created like any other DCE Device. The code is the same, it's just a compilation option whether the device is built as a normal DCE Device, which runs in its own memory space and communicates with DCERouter over a socket, or if it's a plug-in which gets loaded into DCERouter's memory space. Plug-in’s have the ability to get pointers to the in-memory instance of the other plug-ins so they can share memory and call each others methods.

See below a simplified class diagram for DCERouter:
[[Image:DCERouter.jpg|frame|none|Simplified class diagram for the DCE router]]

==4. The binary communication protocol==

===4.1 Introduction===
A device can create a command connection and one or more event connections to the router.
*The command connection is used as an incoming connection and device will use it to receive message from the router (commands).
*An event connection is used by the device as an outgoing connection to notify the router about events or the deliver commands to other devices.
The DCERouter process is listening on 3450 port.

===4.2. How to create an event connection===
Here is how the handshake is made for an event connection:

>> Device sends:
EVENT <my_device_id> '\n'

<< The router will respond with :
OK <my_device_id> IP=<device_ip_address> '\n'

>> To send a message, the device will send :
MESSAGE <size_of_binary_message> '\n'

and then:
<serialized_binary_message>

===4.3 How to serialize data===
DCE uses SerializeClass to serialize/deserialize data.
The sources can be found here : src/SerializeClass/Serialize.h/cpp.
The deserialize the data, the deserializing module must know the way the data was serialized like this:
* 4 bytes, unsigned long
* 1 byte, unsigned char

Primitives:
* 8 bytes, unsigned int64
* 8 bytes, int64
* 4 bytes, unsigned long
* 4 bytes, unsigned short
* 1 byte, unsigned char
* 1 byte, char
* 4 byte, long
* 4 bytes, float
* 8 bytes, double
* 2 bytes, short

Complex types:

#string
#*STR_LENGTH bytes, the array with chars
#*1 byte, '/0' (value 0x00)
#:
#block of data
#*BLOCK_LENGTH bytes, the array with bytes
#:
#vector of strings
#*VECT_LENGTH bytes, the number of strings from vector
#*string 0
#*string 1
#*...
#*string VECT_LENGTH - 1

Other complex types serialized (see SerializeClass.cpp for details) :
* map<int,string>
* map<u_int64_t,string>
* map<int,int>
* map<string,string>
* vector<int>
* vector< pair<int,int> >
* map<string, pair<int,int> >

SerializeClass also allowed you to serialize/deserialize custom objects. Examples:
* PlutoColor
* PlutoPoint
* PlutoSize
* PlutoRectangle
* PlutoDataBlock

===4.4 How to serialize a message===

The class used by DCE is Message class from src/DCE/Message.h/cpp unit.

This is how the raw data looks like into a binary message:

* long, value must be 1234 (magic number)
* long, <device_from_id>
* long, <device_to_id>
* long, <device_group_to_id>
* long, <message_id>
* long, <message_priority>
* long, <message_type>
* long, <device_category_to>
* long, <device_template_to>
* unsigned char, <include_children>
* long, <message_broadcast_level>
* long, <message_retry>
* unsigned char, <relative_to_sender>
* long, <expected_response>
* string, <device_list_to>
* unsigned long, <number_of_string_parameters>
** foreach <string_parameter>
*** long, <string_parameter_id>
*** string, <string_parameter_value>
** end_foreach
* unsigned long, <number_of_data_parameters>
** foreach <data_parameter>
*** long, <data_parameter_id>
*** unsigned long, <data_parameter_length>
*** array of bytes, <data_parameter_value>
** end_foreach
* unsigned long, <number_of_extra_messages>
** foreach <extra_message>
*** unsigned long, <serialized_extra_message_length>
*** array of bytes, <serialized_extra_message_value>
** end_foreach
* unsigned long, must be 6789

'''Enums:'''
* enum eBroadcastLevel { BL_None=0, BL_DirectSiblings=1, BL_SameComputer=2, BL_SameRoom=3, BL_SameHouse=4, BL_AllHouses=5 };
* enum eRetry { MR_None=0, MR_Retry=1, MR_Persist=2 };
* enum eExpectedResponse { ER_None=0, ER_ReplyMessage, ER_ReplyString, ER_DeliveryConfirmation };
* message types: enum { MESSAGETYPE_COMMAND=1, MESSAGETYPE_EVENT=2, MESSAGETYPE_DATAPARM_CHANGE=3, MESSAGETYPE_REPLY=4, MESSAGETYPE_DATAPARM_REQUEST=5, MESSAGETYPE_LOG=6, MESSAGETYPE_SYSCOMMAND=7, MESSAGETYPE_REGISTER_INTERCEPTOR=8, MESSAGETYPE_MESSAGE_INTERCEPTED=9, MESSAGETYPE_EXEC_COMMAND_GROUP=10, MESSAGETYPE_START_PING=11, MESSAGETYPE_STOP_PING=12, MESSAGETYPE_PURGE_INTERCEPTORS=13, MESSAGETYPE_PENDING_TASKS=14 };
* message priority : enum { PRIORITY_LOW=0, PRIORITY_NORMAL=1, PRIORITY_HIGH=2, PRIORITY_URGENT=3 };

'''Important notes:'''
* when sending to device template, set <device_template_to> to desired device template and also <device_to_id> to -2000 (DEVICEID_MASTERDEVICE)
* when sending to device category, set <device_category_to> to desired device category and also <device_to_id> to -2001 (DEVICEID_CATEGORY)
* when sending to a list with devices, set <device_list_to> to comma delimited list with devices and also <device_to_id> to -2002 (DEVICEID_LIST).

'''Example:'''
Here is the pseudocode to send the "on" command to a light switch.
We'll assume that the your device has #id 250 and the light switch has device #id 100

*MyDevice.Connect(router_ip, 3450 /*port*/)
*MyDevice.SendData("EVENT 250\n")
*MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK 250 IP=<device_ip_address> '\n';

'''next: creating a message'''
let's say MyData is an array of bytes
*SerializeLong(MyData, 1234) //magic number
*SerializeLong(MyData, 250) //my id
*SerializeLong(MyData, 100) //the light switch
*SerializeLong(MyData, 0) //not used now
*SerializeLong(MyData, 192) //message id of command 'on'
*SerializeLong(MyData, 1) //normal priority
*SerializeLong(MyData, 1) //message type : command
*SerializeLong(MyData, 0) //not used now
*SerializeLong(MyData, 0) //not used now
*SerializeUnsignedChar(MyData, 0) //not including children
*SerializeLong(MyData, 0) //broadcast level : none
*SerializeLong(MyData, 0) //don't retry
*SerializeUnsignedChar(MyData, 0) //relative to sender false
*SerializeLong(MyData, 3) //delivery confirmation
*SerializeString(MyData, "") //device list to empty
*SerializeUnsignedLong(MyData, 2) //2 parameters
*SerializeLong(MyData, 98) //parameter type #98
*SerializeString(MyData, "") //empty value
*SerializeLong(MyData, 97) //parameter type #97
*SerializeString(MyData, "") //empty value
*SerializeUnsignedLong(MyData, 0) //no binary parameters
*SerializeUnsignedLong(MyData, 0) //no extra messages
*SerializeUnsignedLong(6789) //magic number

*MyDevice.SendData("MESSAGE " + MyData.length() + '\n')
*MyDevice.SendData(MyData)
*MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK" or an error message

*MyDevice.CloseConnection();

===4.5 How to serialize data-grids ===
'''Complex objects:'''
# DataGridCellSerializableData
#* unsigned long, <sizeof(DataGridCellSerializableData)>
#* unsigned long, <graphic_length>
#* unsigned long, <message_length>
#* unsigned long, <text_length>
#* unsigned long, <value_length>
#* unsigned long, <image_path_length>
#* unsigned long, <number_of_attributes_length>
#* unsigned long, <attributes_length>
#* int, <alternate_color>
#* unsigned long, <graphic_format>
#* unsigned char, <selectable>
#* int, <style_detail>
#* int, <col_span>
#* int, <row_span>
#* unsigned char, <dont_fire_grid_event>
#:
#:Enums:
#* enum eGraphicFormat { GR_UNKNOWN=0, GR_JPG=1, GR_GIF=2, GR_TIF=3, GR_PNG=4, GR_MNG=5, GR_BMP=6, GR_OCG=7, GR_PFG=8 };
#:
# DataGridCell
#* DataGridCellSerializableData, <datagrid_cell_serializable_data>
#* array of chars, <text>
#* array of chars, <value>
#* array of bytes, <graphic_data>
#* array of bytes, <message_data>
#* array of chars, <image_path>
#*:
#** foreach <cell_attribute>
#*** array of chars ended with '\0' , <cell_attribute_name>
#*** array of chars ended with '\0', <cell_attribute_value>
#** end_foreach
#:
#DataGridTableSerializableData
#* int, <total_number_of_columns>
#* int, <total_number_of_rows>
#* unsigned char, <keep_row_header>
#* unsigned char, <keep_column_header>
#* int, <column_count>
#* int, <row_count>
#* int, <starting_column>
#* int, <starting_row>
#* int, <cell_count>
#:
#DataGridTableCellIndex
#* unsigned int, <column_row_type>
#* unsigned int, <size>
#:
#DataGridTable
#* unsigned long, <sizeof(DataGridTableSerializableData)>
#* array of DataGridTableCellIndex, <col * row * sizeof(DataGridTableCellIndex)>
#* array of DataGridCell, <col * row * serialized DataGridCell>

----
Additional step: lzo compression/decompression

'''Note:''' can be disabled if compiled with DISABLE_LZO_DATAGRID
----

==5. The devices==

Each device has associated an interface, which we call device template. A device template is a set of commands to be implemented, events which can be fired by the device and device data (persistent information for device).
To create device templates and modify them, go to LinuxMCE Web Admin -> Advanced -> Configuration -> Device Templates.
To generate the C++ code for the device implementing a device template interface, you must use DCEGen tool, specifying the database ip address and the device template number.
Here is the simplified class diagram for one of the devices (App_Server):

[[Image:App_Server.jpg|frame|none|Simplified class diagram for a DCE device]]

The classes App_Server_Event, App_Server_Command and App_Server_Data are generated using DCEGen tool. The base classes for them are implemented in DCE Library.

==6. App_Server device==

App_Server device is present by default on all LinuxMCE machines. It spawns/kills applications, handles volume of sound on that machine, restarts/halts the device.

# Implemented commands:
#*CMD_Spawn_Application - Spawns an application
#*CMD_Kill_Application - Kills an application
#*CMD_Application_Is_Running - Checks if the given application is running.
#*CMD_Halt_Device - Halts or reboots this device
#*CMD_Vol_Up - Increases the volume 1%
#*CMD_Vol_Down - Decreases the volume 1%
#*CMD_Set_Volume - Sets the volume to a specific level between 0-100
#*CMD_Mute - Toggles mute/unmute
#:
#:
#It doesn’t fire any events.
#:
#:
#It has the following device data:
#*Discrete Volume
#*Volume Level

==7. Photo_Screen_Saver device==

The photo screen saver (PSS) displays pictures when there is no video playing, even if you just happen to be listening to music. By default, the photos come from Flickr and are downloaded regularly to local drive.

PSS is a OpenGL application and it slides pictures and fades them between transitions.

1. Implemented commands

The list with pictures is taken by sending a command to Orbiter Plugin : CMD_Get_Screen_Saver_Files which has an output parameter Filename. The filenames are delimited by a ‘\n’ character.

The PSS animations are started/stopped using CMD_On/CMD_Off commands. To force PSS reload the list with pictures from Orbiter Plugin, CMD_Reload is used.

When PSS starts, it should check every 10 minutes if there are any pictures downloaded and ready to be displayed. If there are pictures to display it should display them on CMD_On command and refresh the list with pictures every 24 hours.

2. It doesn’t fire any events

3. Device data:
* ZoomTime - Value in miliseconds that a zoom effect will take
* FadeTime - value in miliseconds that a fade effect will take
* Name - The window name to activate

==8. Media Player device==

Currently there are two Media Players in LinuxMCE, the primary Xine_Player and
secondary MPlayer_Player.
First one is based one the Xine engine (http://xinehq.de) and supports the
following formats:

*'''File formats (System layer / media types)supported:'''
**direct DVD playback (of unlocked/unencrypted DVDs, see below)
** Video CD
** Audio CD
** mpeg program streams (.mpg, .mpeg)
** mpeg transport streams (.ts)
** ogg (.ogg, .ogm)
** avi (.avi)
** asf (.asf, .wmv, .wma)
** quicktime (.mov, .mp4)
** mpeg-video (.mpv, .m2v)
** mpeg-audio (.mp2, .mp3)
** Sega Saturn FILM (.cpk)
** Id Software RoQ (.roq)
** wav (.wav)
** Autodesk FLIC (.fli)
** real (.rm, .ra, .ram)
** raw dv (.dv)
** network graphics format (.png, .mng)
** Creative Voice (.voc)
** Sun/NeXT SND/AU (.snd, .au)
** Wing Commander III (.mve)
** Westwood Studios files (.vqa, .aud)
** Electronic Arts WVE (.wve)
** AIFF (.aif, .aiff)
** YUV4MPEG2 (.y4m)
** SMJPEG (.mjpg)
** raw AC3 (.ac3)
** Dialogic VOX (.vox)
** TechnoTrend PVA (.pva)
** Playstation STR (.str)
** Nullsoft Video (.nsv)
** 4X Technologies (.4xm)

*'''Video codecs supported:'''
** mpeg 1/2
** mpeg 4 (aka OpenDivX)
** ms mpeg 4
** divx 3/4/5
** windows media video 7 & 8
** motion jpeg
** Cinepak
** DV
** ms video 1 (msvc)
** ms rle
** Sorenson SVQ1/SVQ3 (often used in Quicktime trailers)
** creative yuv (cyuv)
** roq video
** QT RLE, SMC, RPZA
** theora
** via external binary/win32 codecs (not included in xine):
** Indeo 3.1-5.0
** Window Media Video 8,9
** On2 VP3.1
** I263
** Real Media 2.0, 3.0, 4.0
* currently unsupported/untested Formats:
** 3ivx
** h263 (aka Real Video 1.0)

*'''Audio codecs'''
** mpeg audio (layer 1,2,3)
** a/52 (aka ac3, dolby digital)
** aac (used in .mp4 files)
** dts (via external decoder)
** vorbis
** pcm
** adpcm (MS/IMA/DVI/Dialogic)
** mu-law and A-law
** roq dpcm
** Real Media dnet audio
** Real Media 28.8 audio
** DivX audio (WMA)
** GSM 6.10
** FLAC
** NSF (NES sound format)
** Speex

The MPlayer_Player is used as the fallback player for the formats Xine doesn't
support/supports not well and currently is used for playing HD-DVD/Bluray
video files and disks.

A media player device plays all kind of media: audio and video, stored media or from cd/dvd/hd/bluray drivers, etc.

1. Implemented commands

*'''Keyboard input:'''
** CMD_EnterGo - Select the currently highlighted menu item
** CMD_Move_Up, CMD_Move_Down, CMD_Move_Left, CMD_Move_Right - Move the highlighter

*'''Media Player Commands'''
** CMD_Pause - Pause the media
** CMD_Play - Play the media
** CMD_Skip_Back_ChannelTrack_Lower - Lower the channel, track, station, etc. by 1. Same as Jump to Pos in Playlist with value -1 for a smart media player
** CMD_Skip_Fwd_ChannelTrack_Greater - Raise the channel, track, station, etc. by 1. Same as Jump to Pos in Playlist with value +1 for a smart media player
** CMD_Stop - Stop the media

*'''Menu Navigation'''
** CMD_EnterGo - Select the currently highlighted menu item
** CMD_Move_Up, CMD_Move_Down, CMD_Move_Left, CMD_Move_Right - Move the highlighter
** CMD_Get_Video_Frame - Gets the current video frame from the media player.
** CMD_Goto_Media_Menu - Goto to the current media Root Menu.
** CMD_Navigate_Next - Nagivate to the next possible navigable area. (The actual outcome depends on the specifc device)
** CMD_Navigate_Prev - Nagivate the previous possible navigable area. (The actual outcome depends on the specific device).
** CMD_Simulate_Mouse_Click - Simlate a mouse click at a certain position on the screen

*'''Smart DVD commands'''
** CMD_Angle – Go to an angle
** CMD_Audio_Track – Go to an audio track
** Subtitle – Go to a subtitle

* '''Smart Media Player'''
** CMD_Change_Playback_Speed – Will make the playback to FF with a configurable amount of speed.
** CMD_Guide - Show guide information. For a dvd this may be the menu, just like the menu command
** CMD_Jump_Position_In_Playlist - Jump to a specific position in the playlist, or a track, or a chapter. Smart media players should also understand the skip fwd/skip back (which non-DCE media players use) to be the same thing as a jump +1 or -1
** CMD_Jump_To_Position_In_Stream - Jump to a position in the stream, specified in seconds.
** CMD_Menu - Show a menu associated with this media
** CMD_Pause_Media - This will stop a media that is currently played. This method should be paired with the "Restart Media" and used when the playback will be stopped and restarted on the same display device.
** CMD_Play_Media - This command will instruct a Media Player to play a media stream identified by a media descriptor created by the "Create Media" command.
** CMD_Report_Playback_Position - This will report the playback position of the current stream.
** CMD_Restart_Media - This will restart a media was paused with the above command
** CMD_Set_Aspect_Ratio - Force aspect ratio
** CMD_Set_Media_ID - Set Media ID - information about media stream
** CMD_Set_Media_Position - Jump to a certain media position
** CMD_SetZoom - Sets zoom level, relative, absolute or 'auto'
** CMD_Simulate_Keypress - Send a key to the device's OSD, or simulate keypresses on the device's panel
** CMD_Start_Streaming - Like play media, but it means the destination device is not the same as the source
** CMD_Stop_Media - This will instruct the media player to stop the playback of a media started with the "Play Media" Command
** CMD_Update_Object_Image - Display an image on the media player

2. '''It fires the following events'''
* EVENT_Menu_Onscreen - A DVD Menu appeared on screen
* EVENT_Playblack_Completed - Fired when the playback of a stream has completed.
* EVENT_Playback_Info_Changed – Playback info changed
* EVENT_Playback_Started – Media has start playing

3. '''Device data:'''
* Name - The name of the window for this app
* Hardware acceleration - driver used
* Deinterlacing Mode - Movie deinterlacing filter status
* Port – Time code notification every second
* Zoom Level – default zoom level

'''NOTE:''' A deviation from design, the media player must bind on a port specified in the device data and report the time code every one second. Any device like an Orbiter could connect to that port and read the time code. Here is the format used for time code:
Speed,CurrentTime,TotalTime,StreamID,Title,Chapter,MediaType,MediaID,Filename (comma delimited).

==9. Orbiter==

===9.1 Introduction===

The Orbiter is really a device just like any other. The main class, Orbiter, is a normal DCE command implementation. However, the Orbiter class was written so that it has no platform-specific functions, such as graphics and sound. It handles the basic logic, and calls pure virtual functions that derived classes must implement to handle the platform-specific commands. Most of the code and virtually all of the logic is contained in the base classes. Therefore, it is a fairly easy task to make a new version of Orbiter for a platform other than SDL, perhaps one that uses Windows SDK calls, or another image library.

Right now there are implementations of Orbiter using SDL. PocketFrog and OpenGL engines. Orbiter runs on different operation systems like Linux, Windows, Windows CE, Window Mobile, Symbian60. There also implementation for web orbiter (running into a browser) or for a Cisco hard phones (using XML services).

===9.2 Architecture===

[[Image:architecture.jpg|frame|none|Orbiter application architecture]]

The present diagram shows how the Orbiter application architecture looks like. Depending on the Graphic Engine and the platform, the only modules dependent on them are “Renderers – engine specific” and “Orbiter - platform specific”.

====9.2.1. The renderers====

There are two kinds of renders:
* orbiter renderers
* object renderers

The orbiter renderers (derived from OrbiterRenderer class) handle the graphic primitives, having pure virtual methods for operations like this:
* RenderText
* SolidRectangle
* HollowRectangle
* DrawLine
* FloodFill
* RenderGraphic
* ReplaceColorInRectangle
* etc.

and applications flow :
* event loop
* configure
* destroy
* on quit
* on reload

However, OrbiterRenderer is not an interface. It also has implemented the logic needed for:
* render screen action
* show a progress bar
* highlighting / un-highlighting objects
* render shortcuts
* show / hide popup’s
* redraw objects
* refresh screen
* render object asynchronously
* object on screen / off screen actions
* background image loading
* drawing an arrow

Here is the class diagram for derived OrbiterRenderer‘s:

[[Image:orbiterrenderer.jpg|frame|none|OrbiterRenderer class diagram]]

Also, there are renderer classes of complex objects like button, data grid, edit box, etc. The base classes for them are : ObjectRenderer, DataGridRenderer. Each renderer is attached to an object like DesignObj_Orbiter, DesignObj_DataGrid.

Here is the class diagram for OpenGL implementation:

[[Image:openGLimplementation.jpg|frame|none|OpenGL implementation]]

The screens are actually trees of objects. The characteristics of the objects are set using the Designer application and stored in the database, then serialized by OrbiterGen and then deserialized by Orbiter.
OrbiterGen scales and pre-renders the screens. Also, OrbiterGen embeds in the serialized data info about the actions to be executed when an object is loaded, activated, unloaded, etc.

====9.2.2. Orbiter – platform specific====

Orbiter also has to take care of the input events like mouse click, keyboard events, etc. For example, Orbiter_Win32 is derived from Orbiter class and takes care of enabling the auto-update mechanism.
Platform specific are the external dialogs with progress bar and prompt user, or the way the composite or masks are used (see OrbiterRenderer_Linux, OrbiterLinux, OrbiterRenderer_SDL_Win32

The Linux version uses XRecord extension to intercept events. The Windows versions use PocketFrog engine’s event loop or SDL event loop.

====9.2.3. Cache image manager====

This module is mainly used by remote orbiters, non-OSD orbiters. Because these orbiters don’t have access to core’s file system, all the graphic files are obtained by network connection and it might be slow. So instead of requesting same image over and over, the image is cached on the local drivers. The collection of images cached are associated with a timestamp (the generation date for the screens). If the user decides to regenerate the screens, the timestamp is changed and the cache is purged and the images are requested, on demand, again from the server.

====9.2.4. Self update module====

The “Self update” module is also used for non-OSD orbiters. Once a new version of the Orbiter XP/CE is available, a new binary data is stored on core’s filesystem. When an non-OSD orbiter starts, compares the md5sum of the current binary with the one from the server. If it’s different, the UpdateBinary is spawned, Orbiter exits and UpdateBinary requests the new binary from server, it downloads it, replaces the old binary and restart Orbiter.

====9.2.5. Simulator====

The simulator is responsible for generating mouse and keyboard events used for stress testing. It also stores some configuration settings.

====9.2.6. Graphic objects====

They are all derived from PlutoGraphic class and store info about the filename, width, height, the block of data and its length, graphic format and graphic management. The operations required are related to loading graphics from a file or a block of data, clearing the data stored, initializations, etc.
In the derived classes like PocketFrogGraphic, SDLGraphic, OpenGLGraphic, specific info are stored like the Surface for PocketFrong, SDL_Surface for SDL and the texture for OpenGL.

====9.2.7. Orbiter logic module====

Just like any other device, Orbiter is derived from a {Device_name}_Command class, the wrapper class generated by DCEGen to allow the device communicate with the router. However, Orbiter is also derived from OrbiterData and IRReceiverBase.

[[Image:orbiterlogicclassdiagram.jpg|frame|none|Orbiter logic – class diagram]]

OrbiterData helps Orbiter deserialize the data needed for its graphic objects, data serialized by OrbiterGen. IRReceiverBase is the base class for all IR receiver devices and it translates IR codes into actions, base on the current screen type and remote layout.

====9.2.7. Mouse handlers====

The goal of handlers is the interpret mouse movements and perform specific actions depending on current screen type. This is one of the main features add in UI2 version.

See below the class diagram:

[[Image:mousehandlers.jpg|frame|none|Mouse handlers – class diagram]]

Note that the mouse handlers are not available for UI1 version of Orbiter.

MouseIterator and MouseGovernor limit the mouse movements the only one move per x ms to prevent extreme numbers of messages burdening the system.
MouseBehaviour handles special mouse behavior, such as locking axis’s, ramping and acceleration.

====9.2.7. HID interface====

This module gets events from the Gyration remote. See below the class diagram:

[[Image:HIDinterface.jpg|frame|none|HID interface – class diagram]]

===9.3 Skinning and User Interface===

====9.3.1 HADesigner====
The graphics, layout and display for the screens rendered in different Orbiter interfaces for the different UI versions are generated and manipulated using a Windows UI management tool called HADesigner.

The following series of screencasts describes the use of the HADesigner tool and the process of generating a brand new UI for a specific plugin for all different variations of the Orbiter UI versions.

# [http://www.localeconcept.com/HADesigner-Screencasts/01-basic_hadesigner_fundamentals.html Basic Designer Fundamentals]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/02_designobj_basics_1.ogg Design Object Basics]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/03_ui2_popup_part_1.ogg UI2 Popup Part I]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/04_ui2_popup_part_2.ogg UI2 Popup Part II]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/05_UI1_Orbiter.ogg UI1 Orbiter]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/06_UI1_Full_Screen_OSD.ogg UI1 Full Screen OSD]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/07_UI1_Full_Screen_OSD_2.ogg UI1 Full Screen OSD Part II]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/08_UI1_PDA.ogg UI1 PDA]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/09_Mobile_Remote.ogg Mobile Remote]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/10_cisco_7970_orbiter.ogg Cisco 7970 Orbiter]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/11_Monitor_mode.ogg Monitor Mode]

The Basic skin, included with LinuxMCE, should really not be modified, since it is used extensively by LinuxMCE and Pluto and is known to work.

====9.3.2 UI Design and process====
The following series of screencasts walks through the design considerations involved in creating a brand new skin for LinuxMCE.

# [http://www.localeconcept.com/Skin-Screencasts/01_introduction_and_aesthetic.ogg Introduction and Aesthetic considerations]
# [http://www.localeconcept.com/Skin-Screencasts/02_main_menu_first_pass.ogg First Pass at the Main Menu]
# [http://www.localeconcept.com/Skin-Screencasts/03_main_menu_notes_and_corrections.ogg Main Menu Notes and Corrections]
# [http://www.localeconcept.com/Skin-Screencasts/04_the_floorplan_buttons.ogg The Floorplan Buttons]

Developers Guide

2008-07-31T15:43:34Z

Juanfe: /* 9. Orbiter */

[[Category: Programmer's Guide]]

{| align="right"
| __TOC__
|}
LinuxMCE developer’s guide
Document version 1.0

==1. Architecture==

LinuxMCE uses a modular architecture. The heart of LinuxMCE, the 'main application' DCERouter is nothing but a general-purpose message router. It has absolutely no code relating to any of LinuxMCE’s functionality--it just relays messages between "Devices". The functionality of LinuxMCE is entirely in separate programs (aka "Devices") which all run independently and communicate with each other by passing messages through DCERouter over sockets.

[[Image:LMCE_Architecture_mini.jpg|frame|none|LinuxMCE architecture – the devices]]

The plug-in’s are also devices, but instead of running as separate binaries, they run as dynamic libraries in DCERouter’s memory space.
A LinuxMCE system can have one or more Media Directors (MD’s). Also, a Core machine can have also the functionality of a Media Director. We call it a Hybrid:

[[Image:LMCE_Architecture_-_the_machines.jpg|frame|none|Linux MCE architecture – the machines]]

==2. DCE==

DCE (Data, Commands and Events) is a lightweight network protocol allowing any device to access its configuration (ie data) from a central database, send + receive commands, and fire + respond to events.

The DCE protocol can be implemented with any device that supports standard networking. LinuxMCE provides a DCE library written in Ansi C++ that implements the protocol on any socket-compatible operating system, and has been tested on Linux and Windows. Porting to other languages should not be a big task. Because the messaging is socket-based, any device, regardless of operating system or language, can be used with any other device.

In each installation there is also one DCE Router, through which all messages are routed. An "installation" is a group of devices treated as a unit, and normally corresponds to a physical residence.

The DCE Router is itself quite simple. It just opens a port for incoming connections. When a device connects, the device sends its unique ID, or Mac Address. The DCE Router does a lookup in a database, and returns that device's data (configuration). DCERouter also sends back a list of all the other devices in the installation with basic information including the commands they know how to implement. The DCE Device then opens a minimum of 2 socket connections to the router. One is for incoming messages (usually commands) from the router, another for outgoing messages (usually events) to it. The DCE Library, which implements the protocol for DCE Devices and the DCE Router, will also open a 3rd socket connection so that it has 2 outgoing sockets: 1 dedicated for sending events and the other for sending other types of messages, like requests and commands to other devices.

All messages go through the router. The devices do not communicate directly to each other. The message will contain information such as the destination device, the type of message, the message id and any number of optional parameters. The router does nothing with the message but forward it to the destination device or devices if the message is being sent to more than one. The DCE library, from which DCE Devices and the DCE Router are derived, knows how to receive incoming messages of the type command and route them to a message handler in the DCE Device.

Another important library is PlutoUtils. It has cross-platform wrapper classes to handle file, strings, processes, threads synchronization, database utils, etc.

==3. DCERouter==

When a DCE Device connects, DCERouter gives it its configuration data and is responsible for receiving and forwarding any messages to and from the devices that connect to it. The most common types of messages are commands and events. All communication goes through DCE Router. If a doorbell device fires an event that the button was pushed, that event goes to DCERouter, which will forward it whatever plug-in has indicated it wants to handle that type of event. If the plug-in then wants to send a command to the media player, this command goes first to the DCE Router, which will then forward it to the media player. The DCE Devices never communicate with each other directly--everything goes through DCE Router. Devices can create their own types of messages specific to them--not just commands and events. For example, a DVD player may send a message that contains a screen capture, or a TV program may send a stream of messages with streaming video. To DCE Router it makes no difference. Messages just have sources and destinations, and DCE Router does not care what type of message it is.

DCERouter also allows you to Message Interceptors. This means a device or plug-in can say that it wants to pre-process all messages that meet a certain criteria. For example, a security plug-in may want to see all events relating to security.
Plug-in’s are DCE Devices that run within the DCERouter's memory space. They are DCE Devices just like any other and they are created like any other DCE Device. The code is the same, it's just a compilation option whether the device is built as a normal DCE Device, which runs in its own memory space and communicates with DCERouter over a socket, or if it's a plug-in which gets loaded into DCERouter's memory space. Plug-in’s have the ability to get pointers to the in-memory instance of the other plug-ins so they can share memory and call each others methods.

See below a simplified class diagram for DCERouter:
[[Image:DCERouter.jpg|frame|none|Simplified class diagram for the DCE router]]

==4. The binary communication protocol==

===4.1 Introduction===
A device can create a command connection and one or more event connections to the router.
*The command connection is used as an incoming connection and device will use it to receive message from the router (commands).
*An event connection is used by the device as an outgoing connection to notify the router about events or the deliver commands to other devices.
The DCERouter process is listening on 3450 port.

===4.2. How to create an event connection===
Here is how the handshake is made for an event connection:

>> Device sends:
EVENT <my_device_id> '\n'

<< The router will respond with :
OK <my_device_id> IP=<device_ip_address> '\n'

>> To send a message, the device will send :
MESSAGE <size_of_binary_message> '\n'

and then:
<serialized_binary_message>

===4.3 How to serialize data===
DCE uses SerializeClass to serialize/deserialize data.
The sources can be found here : src/SerializeClass/Serialize.h/cpp.
The deserialize the data, the deserializing module must know the way the data was serialized like this:
* 4 bytes, unsigned long
* 1 byte, unsigned char

Primitives:
* 8 bytes, unsigned int64
* 8 bytes, int64
* 4 bytes, unsigned long
* 4 bytes, unsigned short
* 1 byte, unsigned char
* 1 byte, char
* 4 byte, long
* 4 bytes, float
* 8 bytes, double
* 2 bytes, short

Complex types:

#string
#*STR_LENGTH bytes, the array with chars
#*1 byte, '/0' (value 0x00)
#:
#block of data
#*BLOCK_LENGTH bytes, the array with bytes
#:
#vector of strings
#*VECT_LENGTH bytes, the number of strings from vector
#*string 0
#*string 1
#*...
#*string VECT_LENGTH - 1

Other complex types serialized (see SerializeClass.cpp for details) :
* map<int,string>
* map<u_int64_t,string>
* map<int,int>
* map<string,string>
* vector<int>
* vector< pair<int,int> >
* map<string, pair<int,int> >

SerializeClass also allowed you to serialize/deserialize custom objects. Examples:
* PlutoColor
* PlutoPoint
* PlutoSize
* PlutoRectangle
* PlutoDataBlock

===4.4 How to serialize a message===

The class used by DCE is Message class from src/DCE/Message.h/cpp unit.

This is how the raw data looks like into a binary message:

* long, value must be 1234 (magic number)
* long, <device_from_id>
* long, <device_to_id>
* long, <device_group_to_id>
* long, <message_id>
* long, <message_priority>
* long, <message_type>
* long, <device_category_to>
* long, <device_template_to>
* unsigned char, <include_children>
* long, <message_broadcast_level>
* long, <message_retry>
* unsigned char, <relative_to_sender>
* long, <expected_response>
* string, <device_list_to>
* unsigned long, <number_of_string_parameters>
** foreach <string_parameter>
*** long, <string_parameter_id>
*** string, <string_parameter_value>
** end_foreach
* unsigned long, <number_of_data_parameters>
** foreach <data_parameter>
*** long, <data_parameter_id>
*** unsigned long, <data_parameter_length>
*** array of bytes, <data_parameter_value>
** end_foreach
* unsigned long, <number_of_extra_messages>
** foreach <extra_message>
*** unsigned long, <serialized_extra_message_length>
*** array of bytes, <serialized_extra_message_value>
** end_foreach
* unsigned long, must be 6789

'''Enums:'''
* enum eBroadcastLevel { BL_None=0, BL_DirectSiblings=1, BL_SameComputer=2, BL_SameRoom=3, BL_SameHouse=4, BL_AllHouses=5 };
* enum eRetry { MR_None=0, MR_Retry=1, MR_Persist=2 };
* enum eExpectedResponse { ER_None=0, ER_ReplyMessage, ER_ReplyString, ER_DeliveryConfirmation };
* message types: enum { MESSAGETYPE_COMMAND=1, MESSAGETYPE_EVENT=2, MESSAGETYPE_DATAPARM_CHANGE=3, MESSAGETYPE_REPLY=4, MESSAGETYPE_DATAPARM_REQUEST=5, MESSAGETYPE_LOG=6, MESSAGETYPE_SYSCOMMAND=7, MESSAGETYPE_REGISTER_INTERCEPTOR=8, MESSAGETYPE_MESSAGE_INTERCEPTED=9, MESSAGETYPE_EXEC_COMMAND_GROUP=10, MESSAGETYPE_START_PING=11, MESSAGETYPE_STOP_PING=12, MESSAGETYPE_PURGE_INTERCEPTORS=13, MESSAGETYPE_PENDING_TASKS=14 };
* message priority : enum { PRIORITY_LOW=0, PRIORITY_NORMAL=1, PRIORITY_HIGH=2, PRIORITY_URGENT=3 };

'''Important notes:'''
* when sending to device template, set <device_template_to> to desired device template and also <device_to_id> to -2000 (DEVICEID_MASTERDEVICE)
* when sending to device category, set <device_category_to> to desired device category and also <device_to_id> to -2001 (DEVICEID_CATEGORY)
* when sending to a list with devices, set <device_list_to> to comma delimited list with devices and also <device_to_id> to -2002 (DEVICEID_LIST).

'''Example:'''
Here is the pseudocode to send the "on" command to a light switch.
We'll assume that the your device has #id 250 and the light switch has device #id 100

*MyDevice.Connect(router_ip, 3450 /*port*/)
*MyDevice.SendData("EVENT 250\n")
*MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK 250 IP=<device_ip_address> '\n';

'''next: creating a message'''
let's say MyData is an array of bytes
*SerializeLong(MyData, 1234) //magic number
*SerializeLong(MyData, 250) //my id
*SerializeLong(MyData, 100) //the light switch
*SerializeLong(MyData, 0) //not used now
*SerializeLong(MyData, 192) //message id of command 'on'
*SerializeLong(MyData, 1) //normal priority
*SerializeLong(MyData, 1) //message type : command
*SerializeLong(MyData, 0) //not used now
*SerializeLong(MyData, 0) //not used now
*SerializeUnsignedChar(MyData, 0) //not including children
*SerializeLong(MyData, 0) //broadcast level : none
*SerializeLong(MyData, 0) //don't retry
*SerializeUnsignedChar(MyData, 0) //relative to sender false
*SerializeLong(MyData, 3) //delivery confirmation
*SerializeString(MyData, "") //device list to empty
*SerializeUnsignedLong(MyData, 2) //2 parameters
*SerializeLong(MyData, 98) //parameter type #98
*SerializeString(MyData, "") //empty value
*SerializeLong(MyData, 97) //parameter type #97
*SerializeString(MyData, "") //empty value
*SerializeUnsignedLong(MyData, 0) //no binary parameters
*SerializeUnsignedLong(MyData, 0) //no extra messages
*SerializeUnsignedLong(6789) //magic number

*MyDevice.SendData("MESSAGE " + MyData.length() + '\n')
*MyDevice.SendData(MyData)
*MyDevice.ReceiveData() //until you'll get a '\n' ; you should receive: "OK" or an error message

*MyDevice.CloseConnection();

===4.5 How to serialize data-grids ===
'''Complex objects:'''
# DataGridCellSerializableData
#* unsigned long, <sizeof(DataGridCellSerializableData)>
#* unsigned long, <graphic_length>
#* unsigned long, <message_length>
#* unsigned long, <text_length>
#* unsigned long, <value_length>
#* unsigned long, <image_path_length>
#* unsigned long, <number_of_attributes_length>
#* unsigned long, <attributes_length>
#* int, <alternate_color>
#* unsigned long, <graphic_format>
#* unsigned char, <selectable>
#* int, <style_detail>
#* int, <col_span>
#* int, <row_span>
#* unsigned char, <dont_fire_grid_event>
#:
#:Enums:
#* enum eGraphicFormat { GR_UNKNOWN=0, GR_JPG=1, GR_GIF=2, GR_TIF=3, GR_PNG=4, GR_MNG=5, GR_BMP=6, GR_OCG=7, GR_PFG=8 };
#:
# DataGridCell
#* DataGridCellSerializableData, <datagrid_cell_serializable_data>
#* array of chars, <text>
#* array of chars, <value>
#* array of bytes, <graphic_data>
#* array of bytes, <message_data>
#* array of chars, <image_path>
#*:
#** foreach <cell_attribute>
#*** array of chars ended with '\0' , <cell_attribute_name>
#*** array of chars ended with '\0', <cell_attribute_value>
#** end_foreach
#:
#DataGridTableSerializableData
#* int, <total_number_of_columns>
#* int, <total_number_of_rows>
#* unsigned char, <keep_row_header>
#* unsigned char, <keep_column_header>
#* int, <column_count>
#* int, <row_count>
#* int, <starting_column>
#* int, <starting_row>
#* int, <cell_count>
#:
#DataGridTableCellIndex
#* unsigned int, <column_row_type>
#* unsigned int, <size>
#:
#DataGridTable
#* unsigned long, <sizeof(DataGridTableSerializableData)>
#* array of DataGridTableCellIndex, <col * row * sizeof(DataGridTableCellIndex)>
#* array of DataGridCell, <col * row * serialized DataGridCell>

----
Additional step: lzo compression/decompression

'''Note:''' can be disabled if compiled with DISABLE_LZO_DATAGRID
----

==5. The devices==

Each device has associated an interface, which we call device template. A device template is a set of commands to be implemented, events which can be fired by the device and device data (persistent information for device).
To create device templates and modify them, go to LinuxMCE Web Admin -> Advanced -> Configuration -> Device Templates.
To generate the C++ code for the device implementing a device template interface, you must use DCEGen tool, specifying the database ip address and the device template number.
Here is the simplified class diagram for one of the devices (App_Server):

[[Image:App_Server.jpg|frame|none|Simplified class diagram for a DCE device]]

The classes App_Server_Event, App_Server_Command and App_Server_Data are generated using DCEGen tool. The base classes for them are implemented in DCE Library.

==6. App_Server device==

App_Server device is present by default on all LinuxMCE machines. It spawns/kills applications, handles volume of sound on that machine, restarts/halts the device.

# Implemented commands:
#*CMD_Spawn_Application - Spawns an application
#*CMD_Kill_Application - Kills an application
#*CMD_Application_Is_Running - Checks if the given application is running.
#*CMD_Halt_Device - Halts or reboots this device
#*CMD_Vol_Up - Increases the volume 1%
#*CMD_Vol_Down - Decreases the volume 1%
#*CMD_Set_Volume - Sets the volume to a specific level between 0-100
#*CMD_Mute - Toggles mute/unmute
#:
#:
#It doesn’t fire any events.
#:
#:
#It has the following device data:
#*Discrete Volume
#*Volume Level

==7. Photo_Screen_Saver device==

The photo screen saver (PSS) displays pictures when there is no video playing, even if you just happen to be listening to music. By default, the photos come from Flickr and are downloaded regularly to local drive.

PSS is a OpenGL application and it slides pictures and fades them between transitions.

1. Implemented commands

The list with pictures is taken by sending a command to Orbiter Plugin : CMD_Get_Screen_Saver_Files which has an output parameter Filename. The filenames are delimited by a ‘\n’ character.

The PSS animations are started/stopped using CMD_On/CMD_Off commands. To force PSS reload the list with pictures from Orbiter Plugin, CMD_Reload is used.

When PSS starts, it should check every 10 minutes if there are any pictures downloaded and ready to be displayed. If there are pictures to display it should display them on CMD_On command and refresh the list with pictures every 24 hours.

2. It doesn’t fire any events

3. Device data:
* ZoomTime - Value in miliseconds that a zoom effect will take
* FadeTime - value in miliseconds that a fade effect will take
* Name - The window name to activate

==8. Media Player device==

Currently there are two Media Players in LinuxMCE, the primary Xine_Player and
secondary MPlayer_Player.
First one is based one the Xine engine (http://xinehq.de) and supports the
following formats:

*'''File formats (System layer / media types)supported:'''
**direct DVD playback (of unlocked/unencrypted DVDs, see below)
** Video CD
** Audio CD
** mpeg program streams (.mpg, .mpeg)
** mpeg transport streams (.ts)
** ogg (.ogg, .ogm)
** avi (.avi)
** asf (.asf, .wmv, .wma)
** quicktime (.mov, .mp4)
** mpeg-video (.mpv, .m2v)
** mpeg-audio (.mp2, .mp3)
** Sega Saturn FILM (.cpk)
** Id Software RoQ (.roq)
** wav (.wav)
** Autodesk FLIC (.fli)
** real (.rm, .ra, .ram)
** raw dv (.dv)
** network graphics format (.png, .mng)
** Creative Voice (.voc)
** Sun/NeXT SND/AU (.snd, .au)
** Wing Commander III (.mve)
** Westwood Studios files (.vqa, .aud)
** Electronic Arts WVE (.wve)
** AIFF (.aif, .aiff)
** YUV4MPEG2 (.y4m)
** SMJPEG (.mjpg)
** raw AC3 (.ac3)
** Dialogic VOX (.vox)
** TechnoTrend PVA (.pva)
** Playstation STR (.str)
** Nullsoft Video (.nsv)
** 4X Technologies (.4xm)

*'''Video codecs supported:'''
** mpeg 1/2
** mpeg 4 (aka OpenDivX)
** ms mpeg 4
** divx 3/4/5
** windows media video 7 & 8
** motion jpeg
** Cinepak
** DV
** ms video 1 (msvc)
** ms rle
** Sorenson SVQ1/SVQ3 (often used in Quicktime trailers)
** creative yuv (cyuv)
** roq video
** QT RLE, SMC, RPZA
** theora
** via external binary/win32 codecs (not included in xine):
** Indeo 3.1-5.0
** Window Media Video 8,9
** On2 VP3.1
** I263
** Real Media 2.0, 3.0, 4.0
* currently unsupported/untested Formats:
** 3ivx
** h263 (aka Real Video 1.0)

*'''Audio codecs'''
** mpeg audio (layer 1,2,3)
** a/52 (aka ac3, dolby digital)
** aac (used in .mp4 files)
** dts (via external decoder)
** vorbis
** pcm
** adpcm (MS/IMA/DVI/Dialogic)
** mu-law and A-law
** roq dpcm
** Real Media dnet audio
** Real Media 28.8 audio
** DivX audio (WMA)
** GSM 6.10
** FLAC
** NSF (NES sound format)
** Speex

The MPlayer_Player is used as the fallback player for the formats Xine doesn't
support/supports not well and currently is used for playing HD-DVD/Bluray
video files and disks.

A media player device plays all kind of media: audio and video, stored media or from cd/dvd/hd/bluray drivers, etc.

1. Implemented commands

*'''Keyboard input:'''
** CMD_EnterGo - Select the currently highlighted menu item
** CMD_Move_Up, CMD_Move_Down, CMD_Move_Left, CMD_Move_Right - Move the highlighter

*'''Media Player Commands'''
** CMD_Pause - Pause the media
** CMD_Play - Play the media
** CMD_Skip_Back_ChannelTrack_Lower - Lower the channel, track, station, etc. by 1. Same as Jump to Pos in Playlist with value -1 for a smart media player
** CMD_Skip_Fwd_ChannelTrack_Greater - Raise the channel, track, station, etc. by 1. Same as Jump to Pos in Playlist with value +1 for a smart media player
** CMD_Stop - Stop the media

*'''Menu Navigation'''
** CMD_EnterGo - Select the currently highlighted menu item
** CMD_Move_Up, CMD_Move_Down, CMD_Move_Left, CMD_Move_Right - Move the highlighter
** CMD_Get_Video_Frame - Gets the current video frame from the media player.
** CMD_Goto_Media_Menu - Goto to the current media Root Menu.
** CMD_Navigate_Next - Nagivate to the next possible navigable area. (The actual outcome depends on the specifc device)
** CMD_Navigate_Prev - Nagivate the previous possible navigable area. (The actual outcome depends on the specific device).
** CMD_Simulate_Mouse_Click - Simlate a mouse click at a certain position on the screen

*'''Smart DVD commands'''
** CMD_Angle – Go to an angle
** CMD_Audio_Track – Go to an audio track
** Subtitle – Go to a subtitle

* '''Smart Media Player'''
** CMD_Change_Playback_Speed – Will make the playback to FF with a configurable amount of speed.
** CMD_Guide - Show guide information. For a dvd this may be the menu, just like the menu command
** CMD_Jump_Position_In_Playlist - Jump to a specific position in the playlist, or a track, or a chapter. Smart media players should also understand the skip fwd/skip back (which non-DCE media players use) to be the same thing as a jump +1 or -1
** CMD_Jump_To_Position_In_Stream - Jump to a position in the stream, specified in seconds.
** CMD_Menu - Show a menu associated with this media
** CMD_Pause_Media - This will stop a media that is currently played. This method should be paired with the "Restart Media" and used when the playback will be stopped and restarted on the same display device.
** CMD_Play_Media - This command will instruct a Media Player to play a media stream identified by a media descriptor created by the "Create Media" command.
** CMD_Report_Playback_Position - This will report the playback position of the current stream.
** CMD_Restart_Media - This will restart a media was paused with the above command
** CMD_Set_Aspect_Ratio - Force aspect ratio
** CMD_Set_Media_ID - Set Media ID - information about media stream
** CMD_Set_Media_Position - Jump to a certain media position
** CMD_SetZoom - Sets zoom level, relative, absolute or 'auto'
** CMD_Simulate_Keypress - Send a key to the device's OSD, or simulate keypresses on the device's panel
** CMD_Start_Streaming - Like play media, but it means the destination device is not the same as the source
** CMD_Stop_Media - This will instruct the media player to stop the playback of a media started with the "Play Media" Command
** CMD_Update_Object_Image - Display an image on the media player

2. '''It fires the following events'''
* EVENT_Menu_Onscreen - A DVD Menu appeared on screen
* EVENT_Playblack_Completed - Fired when the playback of a stream has completed.
* EVENT_Playback_Info_Changed – Playback info changed
* EVENT_Playback_Started – Media has start playing

3. '''Device data:'''
* Name - The name of the window for this app
* Hardware acceleration - driver used
* Deinterlacing Mode - Movie deinterlacing filter status
* Port – Time code notification every second
* Zoom Level – default zoom level

'''NOTE:''' A deviation from design, the media player must bind on a port specified in the device data and report the time code every one second. Any device like an Orbiter could connect to that port and read the time code. Here is the format used for time code:
Speed,CurrentTime,TotalTime,StreamID,Title,Chapter,MediaType,MediaID,Filename (comma delimited).

==9. Orbiter==

===9.1 Introduction===

The Orbiter is really a device just like any other. The main class, Orbiter, is a normal DCE command implementation. However, the Orbiter class was written so that it has no platform-specific functions, such as graphics and sound. It handles the basic logic, and calls pure virtual functions that derived classes must implement to handle the platform-specific commands. Most of the code and virtually all of the logic is contained in the base classes. Therefore, it is a fairly easy task to make a new version of Orbiter for a platform other than SDL, perhaps one that uses Windows SDK calls, or another image library.

Right now there are implementations of Orbiter using SDL. PocketFrog and OpenGL engines. Orbiter runs on different operation systems like Linux, Windows, Windows CE, Window Mobile, Symbian60. There also implementation for web orbiter (running into a browser) or for a Cisco hard phones (using XML services).

===9.2 Architecture===

[[Image:architecture.jpg|frame|none|Orbiter application architecture]]

The present diagram shows how the Orbiter application architecture looks like. Depending on the Graphic Engine and the platform, the only modules dependent on them are “Renderers – engine specific” and “Orbiter - platform specific”.

====9.2.1. The renderers====

There are two kinds of renders:
* orbiter renderers
* object renderers

The orbiter renderers (derived from OrbiterRenderer class) handle the graphic primitives, having pure virtual methods for operations like this:
* RenderText
* SolidRectangle
* HollowRectangle
* DrawLine
* FloodFill
* RenderGraphic
* ReplaceColorInRectangle
* etc.

and applications flow :
* event loop
* configure
* destroy
* on quit
* on reload

However, OrbiterRenderer is not an interface. It also has implemented the logic needed for:
* render screen action
* show a progress bar
* highlighting / un-highlighting objects
* render shortcuts
* show / hide popup’s
* redraw objects
* refresh screen
* render object asynchronously
* object on screen / off screen actions
* background image loading
* drawing an arrow

Here is the class diagram for derived OrbiterRenderer‘s:

[[Image:orbiterrenderer.jpg|frame|none|OrbiterRenderer class diagram]]

Also, there are renderer classes of complex objects like button, data grid, edit box, etc. The base classes for them are : ObjectRenderer, DataGridRenderer. Each renderer is attached to an object like DesignObj_Orbiter, DesignObj_DataGrid.

Here is the class diagram for OpenGL implementation:

[[Image:openGLimplementation.jpg|frame|none|OpenGL implementation]]

The screens are actually trees of objects. The characteristics of the objects are set using the Designer application and stored in the database, then serialized by OrbiterGen and then deserialized by Orbiter.
OrbiterGen scales and pre-renders the screens. Also, OrbiterGen embeds in the serialized data info about the actions to be executed when an object is loaded, activated, unloaded, etc.

====9.2.2. Orbiter – platform specific====

Orbiter also has to take care of the input events like mouse click, keyboard events, etc. For example, Orbiter_Win32 is derived from Orbiter class and takes care of enabling the auto-update mechanism.
Platform specific are the external dialogs with progress bar and prompt user, or the way the composite or masks are used (see OrbiterRenderer_Linux, OrbiterLinux, OrbiterRenderer_SDL_Win32

The Linux version uses XRecord extension to intercept events. The Windows versions use PocketFrog engine’s event loop or SDL event loop.

====9.2.3. Cache image manager====

This module is mainly used by remote orbiters, non-OSD orbiters. Because these orbiters don’t have access to core’s file system, all the graphic files are obtained by network connection and it might be slow. So instead of requesting same image over and over, the image is cached on the local drivers. The collection of images cached are associated with a timestamp (the generation date for the screens). If the user decides to regenerate the screens, the timestamp is changed and the cache is purged and the images are requested, on demand, again from the server.

====9.2.4. Self update module====

The “Self update” module is also used for non-OSD orbiters. Once a new version of the Orbiter XP/CE is available, a new binary data is stored on core’s filesystem. When an non-OSD orbiter starts, compares the md5sum of the current binary with the one from the server. If it’s different, the UpdateBinary is spawned, Orbiter exits and UpdateBinary requests the new binary from server, it downloads it, replaces the old binary and restart Orbiter.

====9.2.5. Simulator====

The simulator is responsible for generating mouse and keyboard events used for stress testing. It also stores some configuration settings.

====9.2.6. Graphic objects====

They are all derived from PlutoGraphic class and store info about the filename, width, height, the block of data and its length, graphic format and graphic management. The operations required are related to loading graphics from a file or a block of data, clearing the data stored, initializations, etc.
In the derived classes like PocketFrogGraphic, SDLGraphic, OpenGLGraphic, specific info are stored like the Surface for PocketFrong, SDL_Surface for SDL and the texture for OpenGL.

====9.2.7. Orbiter logic module====

Just like any other device, Orbiter is derived from a {Device_name}_Command class, the wrapper class generated by DCEGen to allow the device communicate with the router. However, Orbiter is also derived from OrbiterData and IRReceiverBase.

[[Image:orbiterlogicclassdiagram.jpg|frame|none|Orbiter logic – class diagram]]

OrbiterData helps Orbiter deserialize the data needed for its graphic objects, data serialized by OrbiterGen. IRReceiverBase is the base class for all IR receiver devices and it translates IR codes into actions, base on the current screen type and remote layout.

====9.2.7. Mouse handlers====

The goal of handlers is the interpret mouse movements and perform specific actions depending on current screen type. This is one of the main features add in UI2 version.

See below the class diagram:

[[Image:mousehandlers.jpg|frame|none|Mouse handlers – class diagram]]

Note that the mouse handlers are not available for UI1 version of Orbiter.

MouseIterator and MouseGovernor limit the mouse movements the only one move per x ms to prevent extreme numbers of messages burdening the system.
MouseBehaviour handles special mouse behavior, such as locking axis’s, ramping and acceleration.

====9.2.7. HID interface====

This module gets events from the Gyration remote. See below the class diagram:

[[Image:HIDinterface.jpg|frame|none|HID interface – class diagram]]

===9.3 Skinning and User Interface===

The graphics, layout and display for the screens rendered in different Orbiter interfaces for the different UI versions are generated and manipulated using a Windows UI management tool called HADesigner.

The following series of screencasts describes the HADesigner tool and generates a brand new UI for a specific plugin for all different variations of the Orbiter UI versions.

# [http://www.localeconcept.com/HADesigner-Screencasts/01-basic_hadesigner_fundamentals.html Basic Designer Fundamentals]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/02_designobj_basics_1.ogg Design Object Basics]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/03_ui2_popup_part_1.ogg UI2 Popup Part I]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/04_ui2_popup_part_2.ogg UI2 Popup Part II]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/05_UI1_Orbiter.ogg UI1 Orbiter]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/06_UI1_Full_Screen_OSD.ogg UI1 Full Screen OSD]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/07_UI1_Full_Screen_OSD_2.ogg UI1 Full Screen OSD Part II]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/08_UI1_PDA.ogg UI1 PDA]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/09_Mobile_Remote.ogg Mobile Remote]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/10_cisco_7970_orbiter.ogg Cisco 7970 Orbiter]
# [http://www.localeconcept.com/HADesigner-Screencasts/ogg/11_Monitor_mode.ogg Monitor Mode]

Usage Intro

2008-07-12T22:38:50Z

Juanfe:

{| align="right"
| __TOC__
|}
LinuxMCE's main concepts are [[Devices]], Commands (aka [[Scenarios]] and Activities), and [[Events]]. An [[Orbiter]] is the device that displays the User Interface. It can be a [[Media Director|Media Station]], web pad, mobile phone, or other remote control device. The Orbiter User Interface is standardized for all Orbiters.

== Devices ==

A device is generally a piece of hardware or software, like the Xine Media Player, a light switch, or a mobile phone. Devices have three functions, abbreviated "DCE" (Data, Commands, Events):

# Retrieve configuration '''data'''
# Perform a '''command''' (turn on, turn off, fast forward, etc.)
# Report certain triggered '''events''' (e.g. 'motion detected', 'playback started', etc.)

== Scenarios ==

"[[Scenarios]]", "Activities", and "Command Groups" are interchangeable terms -- they mean the same thing. A scenario is a group of commands that can be sent to a device (or series of devices). In LinuxMCE, the default Orbiter main menu consists of several scenario categories, grouped by room. These categories are

* Lighting
* Media
* Climate
* Telecom
* Security

(These default categories are arbitrary and are set up at installation.) To perform an action in LinuxMCE, a scenario is chosen from one of these categories (located on the main menu of an Orbiter).

For example, in rooms which have both a TV and lights, LinuxMCE automatically creates a scenario called 'Showtime.' This scenario dims the lights to 10% whenever the TV starts playing. In rooms with a PVR or other TV-enabled device, another scenario is created called 'TV' (in the 'Media' category) to start the TV. Another scenario in the 'Media' category called 'Video' sends a command to the Orbiter to list your video content. Telecom scenarios are created to make phone calls. Security scenarios are created to view cameras and to arm an alarm.

Some [[What_scenarios_are_created_automatically%3F|default scenarios]] are created for you at installation. A fully-functional system can run using only the default scenarios, if you choose. You can also change or remove the default scenarios or add new ones. This is done though the '''[[LinuxMCE Admin Website]]-->Wizard-->[[Scenarios]]''' menu. When creating a scenario, the [[LinuxMCE Admin Website]] will show you the most appropriate wizard, based on the category you pick. If you're adding an activity in the lighting category, for example, the wizard will display a list of the lights in the room and let you pick which ones to turn off. If you're creating a scenario in the security category, it will list the installed cameras and will allow you to select which ones to display.

A scenario can send a command to any device in the system. By default, scenarios in the lighting category show you the room lights, allowing you to select which ones to which to send commands. However, from the '''Wizard-->[[Scenarios]]''' menu for the specific scenario, you can also specify a command to any device in your home. You could make a phone call, for example, even from a scenario in the lighting category.

Certain scenarios are assigned to certain rooms by default. This can be customized, however. When you manually select a room from the Orbiter main menu, the default scenarios for that room are displayed. In general they control devices in that room, but this can also be changed. If your kitchen is near the garage and you want a scenario to 'turn off the garage light', you can assign a scenario to the room 'kitchen' that will do just that. It doesn't matter that the light is in the garage.

For a Media Director, the on-screen Orbiter User Interface appears on the TV screen. It is manipulated by the mouse/keyboard or remote control connected to your Media Director. By default it is set to display the scenarios for the room in which the Media Director is located.

In contrast, a mobile Orbiter (such as a webpad) can be carried throughout the house. It must be able to select the scenarios for multiple rooms. Fortunately, the option to manually select which room you are currently in is available on every Orbiter's main menu.

This can occasionally cause some confusion. Perhaps both the Living Room and the Bedroom have a scenario called 'TV'. You may have a web pad that is in the Bedroom, but you then carry it to the Living Room. You may forget to tell the web pad that it's now in the Living Room (at the bottom of the Orbiter screen it will still say 'Bedroom'). You hit the 'TV' button expecting the Living Room TV to come on, but in fact you're still controlling the Bedroom and the TV comes on there instead. Finally you may realize that you must change your room location to Living Room, and you can then finally control the TV there.

Once you get used to this concept, though, you'll find it very useful. Conveniently, any Orbiter can be set to control any room and choose from the scenarios assigned to that room. No matter which Orbiter you use, the same set of scenarios will be displayed for each specific room. For example, the kitchen scenarios will always be the same, no matter which Orbiter you are using. (The scenarios are assigned by room -- not by Orbiter.) No matter whether you pick up your mobile phone, your web pad, or your remote control, you will always be shown the same list of scenario options for the Living Room.

You have the option of preventing some family members from using certain scenarios. From the [[LinuxMCE Admin Website]], certain scenarios and rooms can be [[Users#Restrict_Access|restricted to certain users]]. Maybe little Suzy's mobile phone Orbiter should be restricted so that she is only able to control her room and the living room, for example. She would only be able to execute the scenarios in those rooms, but not the Master Bedroom. Other possible options include [[Users#Restrict_Access|requiring a pin code]] to access the scenarios for a particular room.

== Events ==

Devices report events, such as 'Playback started' and 'Motion Sensor tripped'. If you want something to happen automatically in LinuxMCE, you create Event Handlers that react to these events. For example, you can create an event handler that listens for the 'Motion Sensor tripped' event from a motion detector and turns on the lights in response. An event handler might listen for the 'Sunrise' event, which could then prompt the sprinklers to come on.

LinuxMCE creates several default event handlers. In rooms in which you have a TV and lights, an event handler is created that listens for the 'Watching Media' event sent by a media player. When the event is detected, the Showtime scenario (which dims the lights) is executed in response. When you start a movie, therefore, the Showtime activity will be executed and the lights will be dimmed. There are other default event handlers that monitor for events like 'Security Breach' and 'Fire Alarm' (from a home security system).

== Controlling an Orbiter ==

To control the system, you use an [[Orbiter]], which is the LinuxMCE term for a remote control. All [[Orbiters]] have the same basic function: to display the scenarios in the room you're in and let you select one. The different Orbiters may [[Selecting_the_Right_UI|display the User Interface slightly differently]], depending on their screen size, but the function and the list of scenarios is always the same. For example, the [[Selecting_the_Right_UI|"UI1" interface]] (which is used on webpads and PDAs) displays the scenarios in horizontal rows. (If there are more than will fit on a row, there will be a "more" button.) A home button is always displayed that takes you to the main menu. On smaller displays, as on mobile phones or desktop phones, there's not enough room to show the scenarios themselves. The top level menu shows only the categories: Lights, Media, Climate, Security and Telecom. Selecting a category displays the scenarios in that category.

[[Selecting_the_Right_UI|"UI2"]] is the [[Selecting_the_Right_UI|preferred User Interface]] for Media Stations. Using a traditional I/R remote is not much different from using any other Media Center PC remote. The menu button brings up the main menu, and you use the ''left/right/up/down/enter'' buttons to navigate it. The ''fast forward/rewind/skip +/skip -'' keys are used for media playback.

If you have a pointing device like a mouse or gyro air mouse, the UI2 interface also supports a unique control architecture that lets you do everything with 3 (programmable) buttons (plus ok and cancel). The 3 buttons are "MEDIA", "MENU", "AMBIANCE".

On a mouse with 3 programmable buttons (such as the [[Using_the_Gyration_Remote_GYR3101US_%28Non-Fiire_Chief%29|gyration]]), these functions correspond to the buttons from left to right. If you are using a traditional 3 button mouse, you can use the F6, F7 and F8 keys on the keyboard for the three programmable functions instead. In both cases, the left mouse button is "ok", and the right mouse button is "cancel/go back".

Mouse button behavior is "absolute" when you press and hold the media/menu/ambiance button and "relative" when you tap and release.

The "absolute" behavior is generally more efficient. For example, in the case of the middle button (F7), "absolute" behavior means the action is executed without having to additionally click "ok". If you press and hold the middle button (F7) while moving your mouse pointer to the option, then let go, that option is executed. If you instead tap and release the menu button ("relative" behavior), you will only highlight the menu option. You must then press ok (the left mouse button) to execute the option.

Categories appear along the bottom of the screen, and the scenarios in each category popup vertically (like a pull-down menu in a PC, except upside down). If the main menu isn't already visible, bring it up by pressing the "start" button on a Windows I/R remote, or the "menu" button on a 3-button mouse. To exit a menu, use the back button on the I/R remote, the cancel button (right mouse button on a 3-button mouse), or the ESC key on a keyboard.

In UI2 the media is always full screen. If you're not playing your own media, the background media (i.e. screensaver images) is gallery art from the Internet (using flickr) or [[Use_my_own_pictures_in_the_Screen_Saver|pictures you select]]. If only the screensaver images are displayed on the Media Station, press the menu/middle/F7 button to bring up the menu. Right click/ESC to get rid of it. (This works even if your own media is playing.)

If you're using UI2's 3-button navigation model, the normal media control options on a traditional remote are replaced with a single button: "media" (left soft button or F6). Press this and move the pointer up and down for your skip functions (''ch+, ch-, skip fwd, skip back''). Move the pointer left and right for speed control (''rewind, fast forward''). The further you move, the faster the media playback changes. If you hold the button down (the left soft button or F6), your movement will be "absolute". Instead of the traditional "jog shuttle-type" control, movement to the right skips to the end of your media, and movement to the left skips to the beginning. Once you get used to it, you will find that navigating media is orders of magnitude faster and easier with this model than with a traditional remote. You can find a spot in a 2 hour movie in only a couple seconds with a click of a single button (compared to a slew of button clicks required using a traditional remote).

Also, in UI2 you can press the "ambiance" button (right soft button or F8). Move up/down to adjust the lights, and left/right to adjust the volume. As with the media playback, if you hold the F8/right soft button down while you move left and right, your volume control is in "absolute" mode (not "relative"). Moving hard right turns up the volume full blast; hard left is mute. This requires you have a TV or receiver that is serial-controlled, however. LinuxMCE can then directly and instantly set the volume position in sync with your hand movements. (Few TVs and receivers have this feature, unfortunately.)

There are other media control functions besides the most commonly used ''fast fwd/rewind/skip up/skip down''. You can, for example, choose 'subtitles' while watching a DVD, 'guide' while watching TV, and 'random' while listening to an audio CD. In the UI2 3 button model, these functions appear on the main menu (on the left-most pad, entitled 'now playing') and changes according to the type of media you're playing. Press the menu button (middle button/F7) to select these options.

This 3 button model is a new concept and very different from traditional navigation. Most people find it much faster once they become accustomed to it.

==Reload Router & Regen Orbiters==

While using LinuxMCE you'll see sometimes a message asking if you want to [[Quick reload router|reload the router]], or if you want to [[Orbiter Generator|regenerate the Orbiter UIs]] (User Interfaces). In general, these options refresh the LinuxMCE databases so that changes to the system can be recognized.

===Reload Router===
All devices in LinuxMCE obtain their configuration information from the [[DCERouter]], which is the central piece of software on the Core. All devices request a list of the other devices in the home from the router, so they can respond to them appropriately. (For example, an IP camera device might turn on the lights in the room whenever you're viewing the camera. To do so, the IP camera needs to know what lights are in the room.) Typically a device requests this information only when it's starting up. When you connect additional plug and play devices to the system, these new devices generally will work immediately, but their functionality may not be fully enabled within the LinuxMCE system until the DCE router is reloaded. When the router reloads, it signals all devices on the system to simultaneously reload and re-request the system data. Each existing device can then work with each new device. This process is known as a 'reload'. It generally takes about 10 seconds. Every time you add or remove devices, or change a device's configuration, you may be asked to do a reload. If you're going to add more devices or make more device changes, you can do the reload once you're done. If you're in the middle of watching a movie or TV, you can postpone the reload, since media players generally stop playing during reloads. Phone calls aren't affected, though, and TV shows being recorded by MythTV in the background are also unaffected.

===Regen the Orbiter===
LinuxMCE's [[Selecting_the_Right_UI|Orbiter User Interfaces]] are all "pre-rendered" in order to be more efficient. The User Interface source images are all very high resolution, but need to be resized to accommodate the resolution of each Orbiter screen. The Core server has a list of the Orbiters used by your system, and will generate the appropriate User Interface screen for each Orbiter. It will do this each time you request a "regen". If you have five different types of Orbiters (each with a different type of screen), then five different images will be generated during each regen.

These User Interface screen images are stored in the Core. The appropriate UI image is sent to an Orbiter whenever it is activated. For many low-power devices (like mobile phones or desktop phones) there just isn't the processing power to do scaling and rendering of a User Interface screen on the fly. They need to be pre-rendered (with text pre-embedded in the images) to be efficient.

Adding new scenarios may result in the creation of new buttons for the User Interface, or changes to the text on existing buttons. Perhaps an entirely new screen will be created.

Until the User Interface images are regenerated, though, you won't be able to see these new buttons (or screens) on your Orbiter. During the regen, new User Interface images for each type of Orbiter is generated by the Core. This can take about 2-5 minutes, depending on how many Orbiter types you have in your system.

You needn't do a regen every time you add a scenario. You can wait until you have finished adding all the scenarios. Furthermore, you can also regen only the Orbiter you are currently using by doing a "Quick regen". This allows you to see the new User Interface (following the addition of new scenarios) without having to do a full regen for all the Orbiters. Once you have finished adding scenarios, then you can do a full regen.

This regen process can be a bit annoying, but is necessary. In future editions of LinuxMCE, it is planned to allow Media Directors, which have a lot more processing power, to render their on-screen Orbiter User Interfaces on the fly (so you don't have to do a regen each time you add or remove a scenario).

You can do a [[Orbiter Generator#Running OrbiterGen (performing a "regen")|full Orbiter regen or a Quick regen]] at any time by using buttons on the Core's LinuxMCE [[Launch Manager]].

==Managing your media==
LinuxMCE is always scanning for network shares, on Network-Attached Storage (NAS) devices and other Hard Disk Drives (HDDs) of PCs connected to the system (including Windows PCs). Universal Serial Bus (USB) drives are also detected. Every time a LinuxMCE finds a network share, you will be asked if you would like to use it. Whenever you reply "Yes", the file share can be used by any Media Director on the system. The file share is scanned for media, such as audio, video and photos, and any that are found are then cataloged in the Core's central database. For example, when you plug in a USB drive on a Media Station in the living room and tell LinuxMCE to use it, the media on the drive will be available to Media Directors in other rooms.

At the moment there is no way to restrict your media for 'local use only'; all Media Stations in the LinuxMCE system share the media catalog stored on the Core. (This is a limitation that will be addressed in the near future. Sometimes it is desirable to attach a USB drive in the master bedroom and not allow it to be shared, for example. ''Note: However, see [[folder lock|this article that describes a method to address this problem]].'')

Storage devices (NAS, USB drives, extra HDDs on the Core or Media Directors) are referred to as "Extra Drives". When an extra drive is added, it is listed in the device tree in '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]'''. Under 'Core' you'll see a device listed for each HDD in the Core, as well as for each NAS device. Under each Media Station will be listed the HDDs in that Media Station. By clicking on the device you can change the device's properties, such as the mount username/password. Each NAS device, and each file share on another PC, will show as a device listed under the Core; each is considered a child of the Core.

===Access control for shared media===
LinuxMCE creates a top level folder for 'public' media. This folder can be used by every user in the system. A 'private' media folder is also created for each user. Within each of those folders are sub-folders, labeled 'audio', 'video', 'pictures', 'data' and 'other'. Within each of those will also be sub-folders for the extra storage devices (NAS, USB, extra internal drives, etc). When you attach an extra storage device, you can specify whether the default directory structure should be used for it. Alternatively, you can specify 'just make it public' or 'make it private'.

Here's an example. Let's say you have 2 users: john and mary. You connect 3 storage devices:
# a NAS, for which you specify 'use default directory structure'. It is named 'Generic Network Storage [50]'
# a USB drive for which you specify 'make it all public'. It is named 'USB Drive [51]'
# a SATA drive for which you choose 'make it private for john'. It is named 'General Internal HDD [52]

Now let's say you're running Windows. Go to Network Neighborhood and find the LinuxMCE Core server. The directory tree ought to look like this:
<pre>
public
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
USB Drive [51]
john
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
General Internal HDD [52]
mary
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
</pre>
Whether you put your media under video, audio, pictures, data or other is unimportant. It will be scanned by LinuxMCE anyway. The contents of "General Internal HDD [52]" will be displayed in the folder john/other/General Internal HDD [52]. The contents of USB Drive [51] will be displayed in the folder public/other/USB Drive [51]. When John browses the contents in Network Neighborhood, he will be asked for his username and password. He can then access the content in both the public folder as well as the "john" folders (including General Internal HDD [52]). When Mary browses the contents with her username and password, she will see both the public and "mary" folders. She will not be able to see anything on General Internal HDD [52], however, since that drive was specified to be private for John.

In the case of John's private media, it won't be displayed in the LinuxMCE media browser unless you click 'Sources'-->'John'. However you ''can'' see the contents of General Internal HDD [52] (unless you deselect 'Sources'-->'Public' from the media browser). Generic Network Storage [50] would be different, however, since you specified to use the default directory structure for it. LinuxMCE will have created public directories on Generic Network Storage [50] for public video and public audio, as well as for john's video and mary's audio. The media file browser will show only the media that is in the public directories. (The same is true with the Windows Network Neighborhood browser.)

If Generic Network Storage [50] has existing media in the top (root) folder, you won't see it listed anywhere.

It is generally recommended, therefore, that when you add a new (blank) "extra" storage device, you choose to use the default directory structure on it. When you rip media to that device, the media can then be made either public or private, and LinuxMCE will automatically put it in the correct folder (audio, video, etc.).

If you connect an extra storage device that already has media on it, however, and that media isn't already organized in LinuxMCE's default directory structure, it's easiest if you simply 'make it all public' or 'make it all private'. If you were to 'use the default directory structure', you would need to manually move the files from the existing folders into one of the directory folders that LinuxMCE would then create for you.

When you rip files, you have the option of copying them to the Core. If you rip a CD and make it public, it will be stored in public/audio. If you go into Network Neighborhood and add a folder under public/audio, you would essentially be adding a folder on the Core. If you add a folder under public/audio/Generic Network Storage [50], you would be adding it to Generic Network Storage [50].

===Drive and network drive management===
This concept behind drive/network drive management is not the same as the method to which Linux and Windows users are accustomed. In Windows, for example, each network device shows up separately; they are never grouped together. There is an advantage to the way LinuxMCE manages drives. It's much simpler to add devices when you're a novice and don't understand networking. Further, if you're using an infrared remote control, you can manage drives with a single 'yes' or 'no,' click, which is very convenient. Lastly, all your media content is cataloged and presented in the same structure throughout the system, no matter which Media Director you're using or what room you're in.

In Windows, by comparison, if you connect a USB drive to a Windows PC in the bedroom, you won't see that content in the living room unless you 1) open file explorer, 2) create a new network share for it, 3) go into the living room, and 4) create a new mapped network drive there. (That isn't so easy to do with an infrared remote and without some knowledge of networking.) Further, you wouldn't be able to see the media in any other room in the house unless you were to also create mapped network shares in those rooms as well.

With LinuxMCE, when you connect a USB drive, for example, you can 'make it all public'; the media will be available everywhere. No other typing is required. With LinuxMCE, instead of managing multiple network shares and mapped drives, you can choose the Core's public folders in the Network Neighborhood browser from anywhere in the home, without having to know which storage devices the media is actually on. When you remove a USB drive from a Media Station, that media instantly disappears from the catalog displayed in every room. If you reattach it, it will re-appear.

You can also backup the media securely on the Core. LinuxMCE has built-in [http://en.wikipedia.org/wiki/RAID RAID] 5 (see '''[[LinuxMCE Admin Website]]-->Advanced-->[[RAID]]'''), so its HDD has similar backup capabilities to a [[NAS]] device.

To change the name of an extra device, go to the '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]''' and under the Core you will see listed the HDDs in the core and any connected NAS devices. Under each Media Station you will see the HDDs in that Media Station. All are given default names. You can change the description, which will also change the folder name. In the above example, changing "USB Drive [51]" to "Tokyo" means the directory public/other/USB Drive [51] would change to public/other/Tokyo.

You can see a list of the files in the system by folder In the '''[[LinuxMCE Admin Website]]-->Files & Media-->[[Media Files Sync]]''' menu. If a file is shown with a check box, the file exists both on the local disk as well as in LinuxMCE's master catalog. If it has a different icon, then LinuxMCE hasn't finished cataloging the media; just be patient. It should appear with a check mark soon (depending on how much new media was added).

Use this interface to manage change cover art and attributes. Under Files & Media there is also a cover art scan utility that will find cover art, as well as other attributes (actor, genre, etc.) obtained from Amazon.

===Linux operational details of network and disk mounts===
[[UpdateMedia]] is a daemon that constantly scans for media files in the /home/public and the /home/user_xxx folder created for each user. Any added media is cataloged in the pluto_media database File table, and attributes and cover art go into the Attribute and Picture tables. Under /home/public and /home/users_xxx is a data subfolder which contains the actual video, audio, pictures folders. (The /home/user_xxx directories themselves contain the system files for each user (like email boxes) as well as the main login for that user (in a "data" subfolder).

Extra devices are mounted as /mnt/device/xxx (where xxx is the device number). The mount point is the same whether it's a local drive or not. For example, USB drive [50] in a Media Station may be mounted as a local device named /mnt/device/50, but is also mounted as a Samba mount on other Media Stations as /mnt/device/50. The Core and the Media Stations all use the same mount names (/mnt/device/).

Within the /home/public/data and /home/user_xxx/data are symlinks to the physical directories specified by /mnt/device/xxx. Since the Core and all Media Stations mount the same /home directory (and all have the same /mnt/device mounts), they will all show the same files. Therefore, if the [[UpdateMedia]] daemon locates the file /home/public/data/audio/Generic Internal Drive [50]/The Beatles/Let it be.mp3, that file will be listed on every Media Station, too.

[[Category: Tutorials]]

Usage Intro

2008-07-12T22:38:13Z

Juanfe: /* Media Management */

{| align="right"
| __TOC__
|}
LinuxMCE's main concepts are [[Devices]], Commands (aka [[Scenarios]] and Activities), and [[Events]]. An [[Orbiter]] is the device that displays the User Interface. It can be a [[Media Director|Media Station]], web pad, mobile phone, or other remote control device. The Orbiter User Interface is standardized for all Orbiters.

== Devices ==

A device is generally a piece of hardware or software, like the Xine Media Player, a light switch, or a mobile phone. Devices have three functions, abbreviated "DCE" (Data, Commands, Events):

# Retrieve configuration '''data'''
# Perform a '''command''' (turn on, turn off, fast forward, etc.)
# Report certain triggered '''events''' (e.g. 'motion detected', 'playback started', etc.)

== Scenarios ==

"[[Scenarios]]", "Activities", and "Command Groups" are interchangeable terms -- they mean the same thing. A scenario is a group of commands that can be sent to a device (or series of devices). In LinuxMCE, the default Orbiter main menu consists of several scenario categories, grouped by room. These categories are

* Lighting
* Media
* Climate
* Telecom
* Security

(These default categories are arbitrary and are set up at installation.) To perform an action in LinuxMCE, a scenario is chosen from one of these categories (located on the main menu of an Orbiter).

For example, in rooms which have both a TV and lights, LinuxMCE automatically creates a scenario called 'Showtime.' This scenario dims the lights to 10% whenever the TV starts playing. In rooms with a PVR or other TV-enabled device, another scenario is created called 'TV' (in the 'Media' category) to start the TV. Another scenario in the 'Media' category called 'Video' sends a command to the Orbiter to list your video content. Telecom scenarios are created to make phone calls. Security scenarios are created to view cameras and to arm an alarm.

Some [[What_scenarios_are_created_automatically%3F|default scenarios]] are created for you at installation. A fully-functional system can run using only the default scenarios, if you choose. You can also change or remove the default scenarios or add new ones. This is done though the '''[[LinuxMCE Admin Website]]-->Wizard-->[[Scenarios]]''' menu. When creating a scenario, the [[LinuxMCE Admin Website]] will show you the most appropriate wizard, based on the category you pick. If you're adding an activity in the lighting category, for example, the wizard will display a list of the lights in the room and let you pick which ones to turn off. If you're creating a scenario in the security category, it will list the installed cameras and will allow you to select which ones to display.

A scenario can send a command to any device in the system. By default, scenarios in the lighting category show you the room lights, allowing you to select which ones to which to send commands. However, from the '''Wizard-->[[Scenarios]]''' menu for the specific scenario, you can also specify a command to any device in your home. You could make a phone call, for example, even from a scenario in the lighting category.

Certain scenarios are assigned to certain rooms by default. This can be customized, however. When you manually select a room from the Orbiter main menu, the default scenarios for that room are displayed. In general they control devices in that room, but this can also be changed. If your kitchen is near the garage and you want a scenario to 'turn off the garage light', you can assign a scenario to the room 'kitchen' that will do just that. It doesn't matter that the light is in the garage.

For a Media Director, the on-screen Orbiter User Interface appears on the TV screen. It is manipulated by the mouse/keyboard or remote control connected to your Media Director. By default it is set to display the scenarios for the room in which the Media Director is located.

In contrast, a mobile Orbiter (such as a webpad) can be carried throughout the house. It must be able to select the scenarios for multiple rooms. Fortunately, the option to manually select which room you are currently in is available on every Orbiter's main menu.

This can occasionally cause some confusion. Perhaps both the Living Room and the Bedroom have a scenario called 'TV'. You may have a web pad that is in the Bedroom, but you then carry it to the Living Room. You may forget to tell the web pad that it's now in the Living Room (at the bottom of the Orbiter screen it will still say 'Bedroom'). You hit the 'TV' button expecting the Living Room TV to come on, but in fact you're still controlling the Bedroom and the TV comes on there instead. Finally you may realize that you must change your room location to Living Room, and you can then finally control the TV there.

Once you get used to this concept, though, you'll find it very useful. Conveniently, any Orbiter can be set to control any room and choose from the scenarios assigned to that room. No matter which Orbiter you use, the same set of scenarios will be displayed for each specific room. For example, the kitchen scenarios will always be the same, no matter which Orbiter you are using. (The scenarios are assigned by room -- not by Orbiter.) No matter whether you pick up your mobile phone, your web pad, or your remote control, you will always be shown the same list of scenario options for the Living Room.

You have the option of preventing some family members from using certain scenarios. From the [[LinuxMCE Admin Website]], certain scenarios and rooms can be [[Users#Restrict_Access|restricted to certain users]]. Maybe little Suzy's mobile phone Orbiter should be restricted so that she is only able to control her room and the living room, for example. She would only be able to execute the scenarios in those rooms, but not the Master Bedroom. Other possible options include [[Users#Restrict_Access|requiring a pin code]] to access the scenarios for a particular room.

== Events ==

Devices report events, such as 'Playback started' and 'Motion Sensor tripped'. If you want something to happen automatically in LinuxMCE, you create Event Handlers that react to these events. For example, you can create an event handler that listens for the 'Motion Sensor tripped' event from a motion detector and turns on the lights in response. An event handler might listen for the 'Sunrise' event, which could then prompt the sprinklers to come on.

LinuxMCE creates several default event handlers. In rooms in which you have a TV and lights, an event handler is created that listens for the 'Watching Media' event sent by a media player. When the event is detected, the Showtime scenario (which dims the lights) is executed in response. When you start a movie, therefore, the Showtime activity will be executed and the lights will be dimmed. There are other default event handlers that monitor for events like 'Security Breach' and 'Fire Alarm' (from a home security system).

== Controlling an Orbiter ==

To control the system, you use an [[Orbiter]], which is the LinuxMCE term for a remote control. All [[Orbiters]] have the same basic function: to display the scenarios in the room you're in and let you select one. The different Orbiters may [[Selecting_the_Right_UI|display the User Interface slightly differently]], depending on their screen size, but the function and the list of scenarios is always the same. For example, the [[Selecting_the_Right_UI|"UI1" interface]] (which is used on webpads and PDAs) displays the scenarios in horizontal rows. (If there are more than will fit on a row, there will be a "more" button.) A home button is always displayed that takes you to the main menu. On smaller displays, as on mobile phones or desktop phones, there's not enough room to show the scenarios themselves. The top level menu shows only the categories: Lights, Media, Climate, Security and Telecom. Selecting a category displays the scenarios in that category.

[[Selecting_the_Right_UI|"UI2"]] is the [[Selecting_the_Right_UI|preferred User Interface]] for Media Stations. Using a traditional I/R remote is not much different from using any other Media Center PC remote. The menu button brings up the main menu, and you use the ''left/right/up/down/enter'' buttons to navigate it. The ''fast forward/rewind/skip +/skip -'' keys are used for media playback.

If you have a pointing device like a mouse or gyro air mouse, the UI2 interface also supports a unique control architecture that lets you do everything with 3 (programmable) buttons (plus ok and cancel). The 3 buttons are "MEDIA", "MENU", "AMBIANCE".

On a mouse with 3 programmable buttons (such as the [[Using_the_Gyration_Remote_GYR3101US_%28Non-Fiire_Chief%29|gyration]]), these functions correspond to the buttons from left to right. If you are using a traditional 3 button mouse, you can use the F6, F7 and F8 keys on the keyboard for the three programmable functions instead. In both cases, the left mouse button is "ok", and the right mouse button is "cancel/go back".

Mouse button behavior is "absolute" when you press and hold the media/menu/ambiance button and "relative" when you tap and release.

The "absolute" behavior is generally more efficient. For example, in the case of the middle button (F7), "absolute" behavior means the action is executed without having to additionally click "ok". If you press and hold the middle button (F7) while moving your mouse pointer to the option, then let go, that option is executed. If you instead tap and release the menu button ("relative" behavior), you will only highlight the menu option. You must then press ok (the left mouse button) to execute the option.

Categories appear along the bottom of the screen, and the scenarios in each category popup vertically (like a pull-down menu in a PC, except upside down). If the main menu isn't already visible, bring it up by pressing the "start" button on a Windows I/R remote, or the "menu" button on a 3-button mouse. To exit a menu, use the back button on the I/R remote, the cancel button (right mouse button on a 3-button mouse), or the ESC key on a keyboard.

In UI2 the media is always full screen. If you're not playing your own media, the background media (i.e. screensaver images) is gallery art from the Internet (using flickr) or [[Use_my_own_pictures_in_the_Screen_Saver|pictures you select]]. If only the screensaver images are displayed on the Media Station, press the menu/middle/F7 button to bring up the menu. Right click/ESC to get rid of it. (This works even if your own media is playing.)

If you're using UI2's 3-button navigation model, the normal media control options on a traditional remote are replaced with a single button: "media" (left soft button or F6). Press this and move the pointer up and down for your skip functions (''ch+, ch-, skip fwd, skip back''). Move the pointer left and right for speed control (''rewind, fast forward''). The further you move, the faster the media playback changes. If you hold the button down (the left soft button or F6), your movement will be "absolute". Instead of the traditional "jog shuttle-type" control, movement to the right skips to the end of your media, and movement to the left skips to the beginning. Once you get used to it, you will find that navigating media is orders of magnitude faster and easier with this model than with a traditional remote. You can find a spot in a 2 hour movie in only a couple seconds with a click of a single button (compared to a slew of button clicks required using a traditional remote).

Also, in UI2 you can press the "ambiance" button (right soft button or F8). Move up/down to adjust the lights, and left/right to adjust the volume. As with the media playback, if you hold the F8/right soft button down while you move left and right, your volume control is in "absolute" mode (not "relative"). Moving hard right turns up the volume full blast; hard left is mute. This requires you have a TV or receiver that is serial-controlled, however. LinuxMCE can then directly and instantly set the volume position in sync with your hand movements. (Few TVs and receivers have this feature, unfortunately.)

There are other media control functions besides the most commonly used ''fast fwd/rewind/skip up/skip down''. You can, for example, choose 'subtitles' while watching a DVD, 'guide' while watching TV, and 'random' while listening to an audio CD. In the UI2 3 button model, these functions appear on the main menu (on the left-most pad, entitled 'now playing') and changes according to the type of media you're playing. Press the menu button (middle button/F7) to select these options.

This 3 button model is a new concept and very different from traditional navigation. Most people find it much faster once they become accustomed to it.

==Reload Router & Regen Orbiters==

While using LinuxMCE you'll see sometimes a message asking if you want to [[Quick reload router|reload the router]], or if you want to [[Orbiter Generator|regenerate the Orbiter UIs]] (User Interfaces). In general, these options refresh the LinuxMCE databases so that changes to the system can be recognized.

===Reload Router===
All devices in LinuxMCE obtain their configuration information from the [[DCERouter]], which is the central piece of software on the Core. All devices request a list of the other devices in the home from the router, so they can respond to them appropriately. (For example, an IP camera device might turn on the lights in the room whenever you're viewing the camera. To do so, the IP camera needs to know what lights are in the room.) Typically a device requests this information only when it's starting up. When you connect additional plug and play devices to the system, these new devices generally will work immediately, but their functionality may not be fully enabled within the LinuxMCE system until the DCE router is reloaded. When the router reloads, it signals all devices on the system to simultaneously reload and re-request the system data. Each existing device can then work with each new device. This process is known as a 'reload'. It generally takes about 10 seconds. Every time you add or remove devices, or change a device's configuration, you may be asked to do a reload. If you're going to add more devices or make more device changes, you can do the reload once you're done. If you're in the middle of watching a movie or TV, you can postpone the reload, since media players generally stop playing during reloads. Phone calls aren't affected, though, and TV shows being recorded by MythTV in the background are also unaffected.

===Regen the Orbiter===
LinuxMCE's [[Selecting_the_Right_UI|Orbiter User Interfaces]] are all "pre-rendered" in order to be more efficient. The User Interface source images are all very high resolution, but need to be resized to accommodate the resolution of each Orbiter screen. The Core server has a list of the Orbiters used by your system, and will generate the appropriate User Interface screen for each Orbiter. It will do this each time you request a "regen". If you have five different types of Orbiters (each with a different type of screen), then five different images will be generated during each regen.

These User Interface screen images are stored in the Core. The appropriate UI image is sent to an Orbiter whenever it is activated. For many low-power devices (like mobile phones or desktop phones) there just isn't the processing power to do scaling and rendering of a User Interface screen on the fly. They need to be pre-rendered (with text pre-embedded in the images) to be efficient.

Adding new scenarios may result in the creation of new buttons for the User Interface, or changes to the text on existing buttons. Perhaps an entirely new screen will be created.

Until the User Interface images are regenerated, though, you won't be able to see these new buttons (or screens) on your Orbiter. During the regen, new User Interface images for each type of Orbiter is generated by the Core. This can take about 2-5 minutes, depending on how many Orbiter types you have in your system.

You needn't do a regen every time you add a scenario. You can wait until you have finished adding all the scenarios. Furthermore, you can also regen only the Orbiter you are currently using by doing a "Quick regen". This allows you to see the new User Interface (following the addition of new scenarios) without having to do a full regen for all the Orbiters. Once you have finished adding scenarios, then you can do a full regen.

This regen process can be a bit annoying, but is necessary. In future editions of LinuxMCE, it is planned to allow Media Directors, which have a lot more processing power, to render their on-screen Orbiter User Interfaces on the fly (so you don't have to do a regen each time you add or remove a scenario).

You can do a [[Orbiter Generator#Running OrbiterGen (performing a "regen")|full Orbiter regen or a Quick regen]] at any time by using buttons on the Core's LinuxMCE [[Launch Manager]].

==Managing your media==
LinuxMCE is always scanning for network shares, on Network-Attached Storage (NAS) devices and other Hard Disk Drives (HDDs) of PCs connected to the system (including Windows PCs). Universal Serial Bus (USB) drives are also detected. Every time a LinuxMCE finds a network share, you will be asked if you would like to use it. Whenever you reply "Yes", the file share can be used by any Media Director on the system. The file share is scanned for media, such as audio, video and photos, and any that are found are then cataloged in the Core's central database. For example, when you plug in a USB drive on a Media Station in the living room and tell LinuxMCE to use it, the media on the drive will be available to Media Directors in other rooms.

At the moment there is no way to restrict your media for 'local use only'; all Media Stations in the LinuxMCE system share the media catalog stored on the Core. (This is a limitation that will be addressed in the near future. Sometimes it is desirable to attach a USB drive in the master bedroom and not allow it to be shared, for example. ''Note: However, see [[folder lock|this article that describes a method to address this problem]].'')

Storage devices (NAS, USB drives, extra HDDs on the Core or Media Directors) are referred to as "Extra Drives". When an extra drive is added, it is listed in the device tree in '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]'''. Under 'Core' you'll see a device listed for each HDD in the Core, as well as for each NAS device. Under each Media Station will be listed the HDDs in that Media Station. By clicking on the device you can change the device's properties, such as the mount username/password. Each NAS device, and each file share on another PC, will show as a device listed under the Core; each is considered a child of the Core.

==Access control for shared media==
LinuxMCE creates a top level folder for 'public' media. This folder can be used by every user in the system. A 'private' media folder is also created for each user. Within each of those folders are sub-folders, labeled 'audio', 'video', 'pictures', 'data' and 'other'. Within each of those will also be sub-folders for the extra storage devices (NAS, USB, extra internal drives, etc). When you attach an extra storage device, you can specify whether the default directory structure should be used for it. Alternatively, you can specify 'just make it public' or 'make it private'.

Here's an example. Let's say you have 2 users: john and mary. You connect 3 storage devices:
# a NAS, for which you specify 'use default directory structure'. It is named 'Generic Network Storage [50]'
# a USB drive for which you specify 'make it all public'. It is named 'USB Drive [51]'
# a SATA drive for which you choose 'make it private for john'. It is named 'General Internal HDD [52]

Now let's say you're running Windows. Go to Network Neighborhood and find the LinuxMCE Core server. The directory tree ought to look like this:
<pre>
public
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
USB Drive [51]
john
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
General Internal HDD [52]
mary
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
</pre>
Whether you put your media under video, audio, pictures, data or other is unimportant. It will be scanned by LinuxMCE anyway. The contents of "General Internal HDD [52]" will be displayed in the folder john/other/General Internal HDD [52]. The contents of USB Drive [51] will be displayed in the folder public/other/USB Drive [51]. When John browses the contents in Network Neighborhood, he will be asked for his username and password. He can then access the content in both the public folder as well as the "john" folders (including General Internal HDD [52]). When Mary browses the contents with her username and password, she will see both the public and "mary" folders. She will not be able to see anything on General Internal HDD [52], however, since that drive was specified to be private for John.

In the case of John's private media, it won't be displayed in the LinuxMCE media browser unless you click 'Sources'-->'John'. However you ''can'' see the contents of General Internal HDD [52] (unless you deselect 'Sources'-->'Public' from the media browser). Generic Network Storage [50] would be different, however, since you specified to use the default directory structure for it. LinuxMCE will have created public directories on Generic Network Storage [50] for public video and public audio, as well as for john's video and mary's audio. The media file browser will show only the media that is in the public directories. (The same is true with the Windows Network Neighborhood browser.)

If Generic Network Storage [50] has existing media in the top (root) folder, you won't see it listed anywhere.

It is generally recommended, therefore, that when you add a new (blank) "extra" storage device, you choose to use the default directory structure on it. When you rip media to that device, the media can then be made either public or private, and LinuxMCE will automatically put it in the correct folder (audio, video, etc.).

If you connect an extra storage device that already has media on it, however, and that media isn't already organized in LinuxMCE's default directory structure, it's easiest if you simply 'make it all public' or 'make it all private'. If you were to 'use the default directory structure', you would need to manually move the files from the existing folders into one of the directory folders that LinuxMCE would then create for you.

When you rip files, you have the option of copying them to the Core. If you rip a CD and make it public, it will be stored in public/audio. If you go into Network Neighborhood and add a folder under public/audio, you would essentially be adding a folder on the Core. If you add a folder under public/audio/Generic Network Storage [50], you would be adding it to Generic Network Storage [50].

==Drive and network drive management==
This concept behind drive/network drive management is not the same as the method to which Linux and Windows users are accustomed. In Windows, for example, each network device shows up separately; they are never grouped together. There is an advantage to the way LinuxMCE manages drives. It's much simpler to add devices when you're a novice and don't understand networking. Further, if you're using an infrared remote control, you can manage drives with a single 'yes' or 'no,' click, which is very convenient. Lastly, all your media content is cataloged and presented in the same structure throughout the system, no matter which Media Director you're using or what room you're in.

In Windows, by comparison, if you connect a USB drive to a Windows PC in the bedroom, you won't see that content in the living room unless you 1) open file explorer, 2) create a new network share for it, 3) go into the living room, and 4) create a new mapped network drive there. (That isn't so easy to do with an infrared remote and without some knowledge of networking.) Further, you wouldn't be able to see the media in any other room in the house unless you were to also create mapped network shares in those rooms as well.

With LinuxMCE, when you connect a USB drive, for example, you can 'make it all public'; the media will be available everywhere. No other typing is required. With LinuxMCE, instead of managing multiple network shares and mapped drives, you can choose the Core's public folders in the Network Neighborhood browser from anywhere in the home, without having to know which storage devices the media is actually on. When you remove a USB drive from a Media Station, that media instantly disappears from the catalog displayed in every room. If you reattach it, it will re-appear.

You can also backup the media securely on the Core. LinuxMCE has built-in [http://en.wikipedia.org/wiki/RAID RAID] 5 (see '''[[LinuxMCE Admin Website]]-->Advanced-->[[RAID]]'''), so its HDD has similar backup capabilities to a [[NAS]] device.

To change the name of an extra device, go to the '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]''' and under the Core you will see listed the HDDs in the core and any connected NAS devices. Under each Media Station you will see the HDDs in that Media Station. All are given default names. You can change the description, which will also change the folder name. In the above example, changing "USB Drive [51]" to "Tokyo" means the directory public/other/USB Drive [51] would change to public/other/Tokyo.

You can see a list of the files in the system by folder In the '''[[LinuxMCE Admin Website]]-->Files & Media-->[[Media Files Sync]]''' menu. If a file is shown with a check box, the file exists both on the local disk as well as in LinuxMCE's master catalog. If it has a different icon, then LinuxMCE hasn't finished cataloging the media; just be patient. It should appear with a check mark soon (depending on how much new media was added).

Use this interface to manage change cover art and attributes. Under Files & Media there is also a cover art scan utility that will find cover art, as well as other attributes (actor, genre, etc.) obtained from Amazon.

==Linux operational details of network and disk mounts==
[[UpdateMedia]] is a daemon that constantly scans for media files in the /home/public and the /home/user_xxx folder created for each user. Any added media is cataloged in the pluto_media database File table, and attributes and cover art go into the Attribute and Picture tables. Under /home/public and /home/users_xxx is a data subfolder which contains the actual video, audio, pictures folders. (The /home/user_xxx directories themselves contain the system files for each user (like email boxes) as well as the main login for that user (in a "data" subfolder).

Extra devices are mounted as /mnt/device/xxx (where xxx is the device number). The mount point is the same whether it's a local drive or not. For example, USB drive [50] in a Media Station may be mounted as a local device named /mnt/device/50, but is also mounted as a Samba mount on other Media Stations as /mnt/device/50. The Core and the Media Stations all use the same mount names (/mnt/device/).

Within the /home/public/data and /home/user_xxx/data are symlinks to the physical directories specified by /mnt/device/xxx. Since the Core and all Media Stations mount the same /home directory (and all have the same /mnt/device mounts), they will all show the same files. Therefore, if the [[UpdateMedia]] daemon locates the file /home/public/data/audio/Generic Internal Drive [50]/The Beatles/Let it be.mp3, that file will be listed on every Media Station, too.

[[Category: Tutorials]]

Usage Intro

2008-07-12T22:36:24Z

Juanfe: /* Managing your media */

{| align="right"
| __TOC__
|}
LinuxMCE's main concepts are [[Devices]], Commands (aka [[Scenarios]] and Activities), and [[Events]]. An [[Orbiter]] is the device that displays the User Interface. It can be a [[Media Director|Media Station]], web pad, mobile phone, or other remote control device. The Orbiter User Interface is standardized for all Orbiters.

== Devices ==

A device is generally a piece of hardware or software, like the Xine Media Player, a light switch, or a mobile phone. Devices have three functions, abbreviated "DCE" (Data, Commands, Events):

# Retrieve configuration '''data'''
# Perform a '''command''' (turn on, turn off, fast forward, etc.)
# Report certain triggered '''events''' (e.g. 'motion detected', 'playback started', etc.)

== Scenarios ==

"[[Scenarios]]", "Activities", and "Command Groups" are interchangeable terms -- they mean the same thing. A scenario is a group of commands that can be sent to a device (or series of devices). In LinuxMCE, the default Orbiter main menu consists of several scenario categories, grouped by room. These categories are

* Lighting
* Media
* Climate
* Telecom
* Security

(These default categories are arbitrary and are set up at installation.) To perform an action in LinuxMCE, a scenario is chosen from one of these categories (located on the main menu of an Orbiter).

For example, in rooms which have both a TV and lights, LinuxMCE automatically creates a scenario called 'Showtime.' This scenario dims the lights to 10% whenever the TV starts playing. In rooms with a PVR or other TV-enabled device, another scenario is created called 'TV' (in the 'Media' category) to start the TV. Another scenario in the 'Media' category called 'Video' sends a command to the Orbiter to list your video content. Telecom scenarios are created to make phone calls. Security scenarios are created to view cameras and to arm an alarm.

Some [[What_scenarios_are_created_automatically%3F|default scenarios]] are created for you at installation. A fully-functional system can run using only the default scenarios, if you choose. You can also change or remove the default scenarios or add new ones. This is done though the '''[[LinuxMCE Admin Website]]-->Wizard-->[[Scenarios]]''' menu. When creating a scenario, the [[LinuxMCE Admin Website]] will show you the most appropriate wizard, based on the category you pick. If you're adding an activity in the lighting category, for example, the wizard will display a list of the lights in the room and let you pick which ones to turn off. If you're creating a scenario in the security category, it will list the installed cameras and will allow you to select which ones to display.

A scenario can send a command to any device in the system. By default, scenarios in the lighting category show you the room lights, allowing you to select which ones to which to send commands. However, from the '''Wizard-->[[Scenarios]]''' menu for the specific scenario, you can also specify a command to any device in your home. You could make a phone call, for example, even from a scenario in the lighting category.

Certain scenarios are assigned to certain rooms by default. This can be customized, however. When you manually select a room from the Orbiter main menu, the default scenarios for that room are displayed. In general they control devices in that room, but this can also be changed. If your kitchen is near the garage and you want a scenario to 'turn off the garage light', you can assign a scenario to the room 'kitchen' that will do just that. It doesn't matter that the light is in the garage.

For a Media Director, the on-screen Orbiter User Interface appears on the TV screen. It is manipulated by the mouse/keyboard or remote control connected to your Media Director. By default it is set to display the scenarios for the room in which the Media Director is located.

In contrast, a mobile Orbiter (such as a webpad) can be carried throughout the house. It must be able to select the scenarios for multiple rooms. Fortunately, the option to manually select which room you are currently in is available on every Orbiter's main menu.

This can occasionally cause some confusion. Perhaps both the Living Room and the Bedroom have a scenario called 'TV'. You may have a web pad that is in the Bedroom, but you then carry it to the Living Room. You may forget to tell the web pad that it's now in the Living Room (at the bottom of the Orbiter screen it will still say 'Bedroom'). You hit the 'TV' button expecting the Living Room TV to come on, but in fact you're still controlling the Bedroom and the TV comes on there instead. Finally you may realize that you must change your room location to Living Room, and you can then finally control the TV there.

Once you get used to this concept, though, you'll find it very useful. Conveniently, any Orbiter can be set to control any room and choose from the scenarios assigned to that room. No matter which Orbiter you use, the same set of scenarios will be displayed for each specific room. For example, the kitchen scenarios will always be the same, no matter which Orbiter you are using. (The scenarios are assigned by room -- not by Orbiter.) No matter whether you pick up your mobile phone, your web pad, or your remote control, you will always be shown the same list of scenario options for the Living Room.

You have the option of preventing some family members from using certain scenarios. From the [[LinuxMCE Admin Website]], certain scenarios and rooms can be [[Users#Restrict_Access|restricted to certain users]]. Maybe little Suzy's mobile phone Orbiter should be restricted so that she is only able to control her room and the living room, for example. She would only be able to execute the scenarios in those rooms, but not the Master Bedroom. Other possible options include [[Users#Restrict_Access|requiring a pin code]] to access the scenarios for a particular room.

== Events ==

Devices report events, such as 'Playback started' and 'Motion Sensor tripped'. If you want something to happen automatically in LinuxMCE, you create Event Handlers that react to these events. For example, you can create an event handler that listens for the 'Motion Sensor tripped' event from a motion detector and turns on the lights in response. An event handler might listen for the 'Sunrise' event, which could then prompt the sprinklers to come on.

LinuxMCE creates several default event handlers. In rooms in which you have a TV and lights, an event handler is created that listens for the 'Watching Media' event sent by a media player. When the event is detected, the Showtime scenario (which dims the lights) is executed in response. When you start a movie, therefore, the Showtime activity will be executed and the lights will be dimmed. There are other default event handlers that monitor for events like 'Security Breach' and 'Fire Alarm' (from a home security system).

== Controlling an Orbiter ==

To control the system, you use an [[Orbiter]], which is the LinuxMCE term for a remote control. All [[Orbiters]] have the same basic function: to display the scenarios in the room you're in and let you select one. The different Orbiters may [[Selecting_the_Right_UI|display the User Interface slightly differently]], depending on their screen size, but the function and the list of scenarios is always the same. For example, the [[Selecting_the_Right_UI|"UI1" interface]] (which is used on webpads and PDAs) displays the scenarios in horizontal rows. (If there are more than will fit on a row, there will be a "more" button.) A home button is always displayed that takes you to the main menu. On smaller displays, as on mobile phones or desktop phones, there's not enough room to show the scenarios themselves. The top level menu shows only the categories: Lights, Media, Climate, Security and Telecom. Selecting a category displays the scenarios in that category.

[[Selecting_the_Right_UI|"UI2"]] is the [[Selecting_the_Right_UI|preferred User Interface]] for Media Stations. Using a traditional I/R remote is not much different from using any other Media Center PC remote. The menu button brings up the main menu, and you use the ''left/right/up/down/enter'' buttons to navigate it. The ''fast forward/rewind/skip +/skip -'' keys are used for media playback.

If you have a pointing device like a mouse or gyro air mouse, the UI2 interface also supports a unique control architecture that lets you do everything with 3 (programmable) buttons (plus ok and cancel). The 3 buttons are "MEDIA", "MENU", "AMBIANCE".

On a mouse with 3 programmable buttons (such as the [[Using_the_Gyration_Remote_GYR3101US_%28Non-Fiire_Chief%29|gyration]]), these functions correspond to the buttons from left to right. If you are using a traditional 3 button mouse, you can use the F6, F7 and F8 keys on the keyboard for the three programmable functions instead. In both cases, the left mouse button is "ok", and the right mouse button is "cancel/go back".

Mouse button behavior is "absolute" when you press and hold the media/menu/ambiance button and "relative" when you tap and release.

The "absolute" behavior is generally more efficient. For example, in the case of the middle button (F7), "absolute" behavior means the action is executed without having to additionally click "ok". If you press and hold the middle button (F7) while moving your mouse pointer to the option, then let go, that option is executed. If you instead tap and release the menu button ("relative" behavior), you will only highlight the menu option. You must then press ok (the left mouse button) to execute the option.

Categories appear along the bottom of the screen, and the scenarios in each category popup vertically (like a pull-down menu in a PC, except upside down). If the main menu isn't already visible, bring it up by pressing the "start" button on a Windows I/R remote, or the "menu" button on a 3-button mouse. To exit a menu, use the back button on the I/R remote, the cancel button (right mouse button on a 3-button mouse), or the ESC key on a keyboard.

In UI2 the media is always full screen. If you're not playing your own media, the background media (i.e. screensaver images) is gallery art from the Internet (using flickr) or [[Use_my_own_pictures_in_the_Screen_Saver|pictures you select]]. If only the screensaver images are displayed on the Media Station, press the menu/middle/F7 button to bring up the menu. Right click/ESC to get rid of it. (This works even if your own media is playing.)

If you're using UI2's 3-button navigation model, the normal media control options on a traditional remote are replaced with a single button: "media" (left soft button or F6). Press this and move the pointer up and down for your skip functions (''ch+, ch-, skip fwd, skip back''). Move the pointer left and right for speed control (''rewind, fast forward''). The further you move, the faster the media playback changes. If you hold the button down (the left soft button or F6), your movement will be "absolute". Instead of the traditional "jog shuttle-type" control, movement to the right skips to the end of your media, and movement to the left skips to the beginning. Once you get used to it, you will find that navigating media is orders of magnitude faster and easier with this model than with a traditional remote. You can find a spot in a 2 hour movie in only a couple seconds with a click of a single button (compared to a slew of button clicks required using a traditional remote).

Also, in UI2 you can press the "ambiance" button (right soft button or F8). Move up/down to adjust the lights, and left/right to adjust the volume. As with the media playback, if you hold the F8/right soft button down while you move left and right, your volume control is in "absolute" mode (not "relative"). Moving hard right turns up the volume full blast; hard left is mute. This requires you have a TV or receiver that is serial-controlled, however. LinuxMCE can then directly and instantly set the volume position in sync with your hand movements. (Few TVs and receivers have this feature, unfortunately.)

There are other media control functions besides the most commonly used ''fast fwd/rewind/skip up/skip down''. You can, for example, choose 'subtitles' while watching a DVD, 'guide' while watching TV, and 'random' while listening to an audio CD. In the UI2 3 button model, these functions appear on the main menu (on the left-most pad, entitled 'now playing') and changes according to the type of media you're playing. Press the menu button (middle button/F7) to select these options.

This 3 button model is a new concept and very different from traditional navigation. Most people find it much faster once they become accustomed to it.

==Reload Router & Regen Orbiters==

While using LinuxMCE you'll see sometimes a message asking if you want to [[Quick reload router|reload the router]], or if you want to [[Orbiter Generator|regenerate the Orbiter UIs]] (User Interfaces). In general, these options refresh the LinuxMCE databases so that changes to the system can be recognized.

===Reload Router===
All devices in LinuxMCE obtain their configuration information from the [[DCERouter]], which is the central piece of software on the Core. All devices request a list of the other devices in the home from the router, so they can respond to them appropriately. (For example, an IP camera device might turn on the lights in the room whenever you're viewing the camera. To do so, the IP camera needs to know what lights are in the room.) Typically a device requests this information only when it's starting up. When you connect additional plug and play devices to the system, these new devices generally will work immediately, but their functionality may not be fully enabled within the LinuxMCE system until the DCE router is reloaded. When the router reloads, it signals all devices on the system to simultaneously reload and re-request the system data. Each existing device can then work with each new device. This process is known as a 'reload'. It generally takes about 10 seconds. Every time you add or remove devices, or change a device's configuration, you may be asked to do a reload. If you're going to add more devices or make more device changes, you can do the reload once you're done. If you're in the middle of watching a movie or TV, you can postpone the reload, since media players generally stop playing during reloads. Phone calls aren't affected, though, and TV shows being recorded by MythTV in the background are also unaffected.

===Regen the Orbiter===
LinuxMCE's [[Selecting_the_Right_UI|Orbiter User Interfaces]] are all "pre-rendered" in order to be more efficient. The User Interface source images are all very high resolution, but need to be resized to accommodate the resolution of each Orbiter screen. The Core server has a list of the Orbiters used by your system, and will generate the appropriate User Interface screen for each Orbiter. It will do this each time you request a "regen". If you have five different types of Orbiters (each with a different type of screen), then five different images will be generated during each regen.

These User Interface screen images are stored in the Core. The appropriate UI image is sent to an Orbiter whenever it is activated. For many low-power devices (like mobile phones or desktop phones) there just isn't the processing power to do scaling and rendering of a User Interface screen on the fly. They need to be pre-rendered (with text pre-embedded in the images) to be efficient.

Adding new scenarios may result in the creation of new buttons for the User Interface, or changes to the text on existing buttons. Perhaps an entirely new screen will be created.

Until the User Interface images are regenerated, though, you won't be able to see these new buttons (or screens) on your Orbiter. During the regen, new User Interface images for each type of Orbiter is generated by the Core. This can take about 2-5 minutes, depending on how many Orbiter types you have in your system.

You needn't do a regen every time you add a scenario. You can wait until you have finished adding all the scenarios. Furthermore, you can also regen only the Orbiter you are currently using by doing a "Quick regen". This allows you to see the new User Interface (following the addition of new scenarios) without having to do a full regen for all the Orbiters. Once you have finished adding scenarios, then you can do a full regen.

This regen process can be a bit annoying, but is necessary. In future editions of LinuxMCE, it is planned to allow Media Directors, which have a lot more processing power, to render their on-screen Orbiter User Interfaces on the fly (so you don't have to do a regen each time you add or remove a scenario).

You can do a [[Orbiter Generator#Running OrbiterGen (performing a "regen")|full Orbiter regen or a Quick regen]] at any time by using buttons on the Core's LinuxMCE [[Launch Manager]].

= Media Management =
==Managing your media==
LinuxMCE is always scanning for network shares, on Network-Attached Storage (NAS) devices and other Hard Disk Drives (HDDs) of PCs connected to the system (including Windows PCs). Universal Serial Bus (USB) drives are also detected. Every time a LinuxMCE finds a network share, you will be asked if you would like to use it. Whenever you reply "Yes", the file share can be used by any Media Director on the system. The file share is scanned for media, such as audio, video and photos, and any that are found are then cataloged in the Core's central database. For example, when you plug in a USB drive on a Media Station in the living room and tell LinuxMCE to use it, the media on the drive will be available to Media Directors in other rooms.

At the moment there is no way to restrict your media for 'local use only'; all Media Stations in the LinuxMCE system share the media catalog stored on the Core. (This is a limitation that will be addressed in the near future. Sometimes it is desirable to attach a USB drive in the master bedroom and not allow it to be shared, for example. ''Note: However, see [[folder lock|this article that describes a method to address this problem]].'')

Storage devices (NAS, USB drives, extra HDDs on the Core or Media Directors) are referred to as "Extra Drives". When an extra drive is added, it is listed in the device tree in '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]'''. Under 'Core' you'll see a device listed for each HDD in the Core, as well as for each NAS device. Under each Media Station will be listed the HDDs in that Media Station. By clicking on the device you can change the device's properties, such as the mount username/password. Each NAS device, and each file share on another PC, will show as a device listed under the Core; each is considered a child of the Core.

==Access control for shared media==
LinuxMCE creates a top level folder for 'public' media. This folder can be used by every user in the system. A 'private' media folder is also created for each user. Within each of those folders are sub-folders, labeled 'audio', 'video', 'pictures', 'data' and 'other'. Within each of those will also be sub-folders for the extra storage devices (NAS, USB, extra internal drives, etc). When you attach an extra storage device, you can specify whether the default directory structure should be used for it. Alternatively, you can specify 'just make it public' or 'make it private'.

Here's an example. Let's say you have 2 users: john and mary. You connect 3 storage devices:
# a NAS, for which you specify 'use default directory structure'. It is named 'Generic Network Storage [50]'
# a USB drive for which you specify 'make it all public'. It is named 'USB Drive [51]'
# a SATA drive for which you choose 'make it private for john'. It is named 'General Internal HDD [52]

Now let's say you're running Windows. Go to Network Neighborhood and find the LinuxMCE Core server. The directory tree ought to look like this:
<pre>
public
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
USB Drive [51]
john
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
General Internal HDD [52]
mary
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
</pre>
Whether you put your media under video, audio, pictures, data or other is unimportant. It will be scanned by LinuxMCE anyway. The contents of "General Internal HDD [52]" will be displayed in the folder john/other/General Internal HDD [52]. The contents of USB Drive [51] will be displayed in the folder public/other/USB Drive [51]. When John browses the contents in Network Neighborhood, he will be asked for his username and password. He can then access the content in both the public folder as well as the "john" folders (including General Internal HDD [52]). When Mary browses the contents with her username and password, she will see both the public and "mary" folders. She will not be able to see anything on General Internal HDD [52], however, since that drive was specified to be private for John.

In the case of John's private media, it won't be displayed in the LinuxMCE media browser unless you click 'Sources'-->'John'. However you ''can'' see the contents of General Internal HDD [52] (unless you deselect 'Sources'-->'Public' from the media browser). Generic Network Storage [50] would be different, however, since you specified to use the default directory structure for it. LinuxMCE will have created public directories on Generic Network Storage [50] for public video and public audio, as well as for john's video and mary's audio. The media file browser will show only the media that is in the public directories. (The same is true with the Windows Network Neighborhood browser.)

If Generic Network Storage [50] has existing media in the top (root) folder, you won't see it listed anywhere.

It is generally recommended, therefore, that when you add a new (blank) "extra" storage device, you choose to use the default directory structure on it. When you rip media to that device, the media can then be made either public or private, and LinuxMCE will automatically put it in the correct folder (audio, video, etc.).

If you connect an extra storage device that already has media on it, however, and that media isn't already organized in LinuxMCE's default directory structure, it's easiest if you simply 'make it all public' or 'make it all private'. If you were to 'use the default directory structure', you would need to manually move the files from the existing folders into one of the directory folders that LinuxMCE would then create for you.

When you rip files, you have the option of copying them to the Core. If you rip a CD and make it public, it will be stored in public/audio. If you go into Network Neighborhood and add a folder under public/audio, you would essentially be adding a folder on the Core. If you add a folder under public/audio/Generic Network Storage [50], you would be adding it to Generic Network Storage [50].

==Drive and network drive management==
This concept behind drive/network drive management is not the same as the method to which Linux and Windows users are accustomed. In Windows, for example, each network device shows up separately; they are never grouped together. There is an advantage to the way LinuxMCE manages drives. It's much simpler to add devices when you're a novice and don't understand networking. Further, if you're using an infrared remote control, you can manage drives with a single 'yes' or 'no,' click, which is very convenient. Lastly, all your media content is cataloged and presented in the same structure throughout the system, no matter which Media Director you're using or what room you're in.

In Windows, by comparison, if you connect a USB drive to a Windows PC in the bedroom, you won't see that content in the living room unless you 1) open file explorer, 2) create a new network share for it, 3) go into the living room, and 4) create a new mapped network drive there. (That isn't so easy to do with an infrared remote and without some knowledge of networking.) Further, you wouldn't be able to see the media in any other room in the house unless you were to also create mapped network shares in those rooms as well.

With LinuxMCE, when you connect a USB drive, for example, you can 'make it all public'; the media will be available everywhere. No other typing is required. With LinuxMCE, instead of managing multiple network shares and mapped drives, you can choose the Core's public folders in the Network Neighborhood browser from anywhere in the home, without having to know which storage devices the media is actually on. When you remove a USB drive from a Media Station, that media instantly disappears from the catalog displayed in every room. If you reattach it, it will re-appear.

You can also backup the media securely on the Core. LinuxMCE has built-in [http://en.wikipedia.org/wiki/RAID RAID] 5 (see '''[[LinuxMCE Admin Website]]-->Advanced-->[[RAID]]'''), so its HDD has similar backup capabilities to a [[NAS]] device.

To change the name of an extra device, go to the '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]''' and under the Core you will see listed the HDDs in the core and any connected NAS devices. Under each Media Station you will see the HDDs in that Media Station. All are given default names. You can change the description, which will also change the folder name. In the above example, changing "USB Drive [51]" to "Tokyo" means the directory public/other/USB Drive [51] would change to public/other/Tokyo.

You can see a list of the files in the system by folder In the '''[[LinuxMCE Admin Website]]-->Files & Media-->[[Media Files Sync]]''' menu. If a file is shown with a check box, the file exists both on the local disk as well as in LinuxMCE's master catalog. If it has a different icon, then LinuxMCE hasn't finished cataloging the media; just be patient. It should appear with a check mark soon (depending on how much new media was added).

Use this interface to manage change cover art and attributes. Under Files & Media there is also a cover art scan utility that will find cover art, as well as other attributes (actor, genre, etc.) obtained from Amazon.

==Linux operational details of network and disk mounts==
[[UpdateMedia]] is a daemon that constantly scans for media files in the /home/public and the /home/user_xxx folder created for each user. Any added media is cataloged in the pluto_media database File table, and attributes and cover art go into the Attribute and Picture tables. Under /home/public and /home/users_xxx is a data subfolder which contains the actual video, audio, pictures folders. (The /home/user_xxx directories themselves contain the system files for each user (like email boxes) as well as the main login for that user (in a "data" subfolder).

Extra devices are mounted as /mnt/device/xxx (where xxx is the device number). The mount point is the same whether it's a local drive or not. For example, USB drive [50] in a Media Station may be mounted as a local device named /mnt/device/50, but is also mounted as a Samba mount on other Media Stations as /mnt/device/50. The Core and the Media Stations all use the same mount names (/mnt/device/).

Within the /home/public/data and /home/user_xxx/data are symlinks to the physical directories specified by /mnt/device/xxx. Since the Core and all Media Stations mount the same /home directory (and all have the same /mnt/device mounts), they will all show the same files. Therefore, if the [[UpdateMedia]] daemon locates the file /home/public/data/audio/Generic Internal Drive [50]/The Beatles/Let it be.mp3, that file will be listed on every Media Station, too.

[[Category: Tutorials]]

Usage Intro

2008-07-12T22:35:19Z

Juanfe: /* Background and Linux operational details */

{| align="right"
| __TOC__
|}
LinuxMCE's main concepts are [[Devices]], Commands (aka [[Scenarios]] and Activities), and [[Events]]. An [[Orbiter]] is the device that displays the User Interface. It can be a [[Media Director|Media Station]], web pad, mobile phone, or other remote control device. The Orbiter User Interface is standardized for all Orbiters.

== Devices ==

A device is generally a piece of hardware or software, like the Xine Media Player, a light switch, or a mobile phone. Devices have three functions, abbreviated "DCE" (Data, Commands, Events):

# Retrieve configuration '''data'''
# Perform a '''command''' (turn on, turn off, fast forward, etc.)
# Report certain triggered '''events''' (e.g. 'motion detected', 'playback started', etc.)

== Scenarios ==

"[[Scenarios]]", "Activities", and "Command Groups" are interchangeable terms -- they mean the same thing. A scenario is a group of commands that can be sent to a device (or series of devices). In LinuxMCE, the default Orbiter main menu consists of several scenario categories, grouped by room. These categories are

* Lighting
* Media
* Climate
* Telecom
* Security

(These default categories are arbitrary and are set up at installation.) To perform an action in LinuxMCE, a scenario is chosen from one of these categories (located on the main menu of an Orbiter).

For example, in rooms which have both a TV and lights, LinuxMCE automatically creates a scenario called 'Showtime.' This scenario dims the lights to 10% whenever the TV starts playing. In rooms with a PVR or other TV-enabled device, another scenario is created called 'TV' (in the 'Media' category) to start the TV. Another scenario in the 'Media' category called 'Video' sends a command to the Orbiter to list your video content. Telecom scenarios are created to make phone calls. Security scenarios are created to view cameras and to arm an alarm.

Some [[What_scenarios_are_created_automatically%3F|default scenarios]] are created for you at installation. A fully-functional system can run using only the default scenarios, if you choose. You can also change or remove the default scenarios or add new ones. This is done though the '''[[LinuxMCE Admin Website]]-->Wizard-->[[Scenarios]]''' menu. When creating a scenario, the [[LinuxMCE Admin Website]] will show you the most appropriate wizard, based on the category you pick. If you're adding an activity in the lighting category, for example, the wizard will display a list of the lights in the room and let you pick which ones to turn off. If you're creating a scenario in the security category, it will list the installed cameras and will allow you to select which ones to display.

A scenario can send a command to any device in the system. By default, scenarios in the lighting category show you the room lights, allowing you to select which ones to which to send commands. However, from the '''Wizard-->[[Scenarios]]''' menu for the specific scenario, you can also specify a command to any device in your home. You could make a phone call, for example, even from a scenario in the lighting category.

Certain scenarios are assigned to certain rooms by default. This can be customized, however. When you manually select a room from the Orbiter main menu, the default scenarios for that room are displayed. In general they control devices in that room, but this can also be changed. If your kitchen is near the garage and you want a scenario to 'turn off the garage light', you can assign a scenario to the room 'kitchen' that will do just that. It doesn't matter that the light is in the garage.

For a Media Director, the on-screen Orbiter User Interface appears on the TV screen. It is manipulated by the mouse/keyboard or remote control connected to your Media Director. By default it is set to display the scenarios for the room in which the Media Director is located.

In contrast, a mobile Orbiter (such as a webpad) can be carried throughout the house. It must be able to select the scenarios for multiple rooms. Fortunately, the option to manually select which room you are currently in is available on every Orbiter's main menu.

This can occasionally cause some confusion. Perhaps both the Living Room and the Bedroom have a scenario called 'TV'. You may have a web pad that is in the Bedroom, but you then carry it to the Living Room. You may forget to tell the web pad that it's now in the Living Room (at the bottom of the Orbiter screen it will still say 'Bedroom'). You hit the 'TV' button expecting the Living Room TV to come on, but in fact you're still controlling the Bedroom and the TV comes on there instead. Finally you may realize that you must change your room location to Living Room, and you can then finally control the TV there.

Once you get used to this concept, though, you'll find it very useful. Conveniently, any Orbiter can be set to control any room and choose from the scenarios assigned to that room. No matter which Orbiter you use, the same set of scenarios will be displayed for each specific room. For example, the kitchen scenarios will always be the same, no matter which Orbiter you are using. (The scenarios are assigned by room -- not by Orbiter.) No matter whether you pick up your mobile phone, your web pad, or your remote control, you will always be shown the same list of scenario options for the Living Room.

You have the option of preventing some family members from using certain scenarios. From the [[LinuxMCE Admin Website]], certain scenarios and rooms can be [[Users#Restrict_Access|restricted to certain users]]. Maybe little Suzy's mobile phone Orbiter should be restricted so that she is only able to control her room and the living room, for example. She would only be able to execute the scenarios in those rooms, but not the Master Bedroom. Other possible options include [[Users#Restrict_Access|requiring a pin code]] to access the scenarios for a particular room.

== Events ==

Devices report events, such as 'Playback started' and 'Motion Sensor tripped'. If you want something to happen automatically in LinuxMCE, you create Event Handlers that react to these events. For example, you can create an event handler that listens for the 'Motion Sensor tripped' event from a motion detector and turns on the lights in response. An event handler might listen for the 'Sunrise' event, which could then prompt the sprinklers to come on.

LinuxMCE creates several default event handlers. In rooms in which you have a TV and lights, an event handler is created that listens for the 'Watching Media' event sent by a media player. When the event is detected, the Showtime scenario (which dims the lights) is executed in response. When you start a movie, therefore, the Showtime activity will be executed and the lights will be dimmed. There are other default event handlers that monitor for events like 'Security Breach' and 'Fire Alarm' (from a home security system).

== Controlling an Orbiter ==

To control the system, you use an [[Orbiter]], which is the LinuxMCE term for a remote control. All [[Orbiters]] have the same basic function: to display the scenarios in the room you're in and let you select one. The different Orbiters may [[Selecting_the_Right_UI|display the User Interface slightly differently]], depending on their screen size, but the function and the list of scenarios is always the same. For example, the [[Selecting_the_Right_UI|"UI1" interface]] (which is used on webpads and PDAs) displays the scenarios in horizontal rows. (If there are more than will fit on a row, there will be a "more" button.) A home button is always displayed that takes you to the main menu. On smaller displays, as on mobile phones or desktop phones, there's not enough room to show the scenarios themselves. The top level menu shows only the categories: Lights, Media, Climate, Security and Telecom. Selecting a category displays the scenarios in that category.

[[Selecting_the_Right_UI|"UI2"]] is the [[Selecting_the_Right_UI|preferred User Interface]] for Media Stations. Using a traditional I/R remote is not much different from using any other Media Center PC remote. The menu button brings up the main menu, and you use the ''left/right/up/down/enter'' buttons to navigate it. The ''fast forward/rewind/skip +/skip -'' keys are used for media playback.

If you have a pointing device like a mouse or gyro air mouse, the UI2 interface also supports a unique control architecture that lets you do everything with 3 (programmable) buttons (plus ok and cancel). The 3 buttons are "MEDIA", "MENU", "AMBIANCE".

On a mouse with 3 programmable buttons (such as the [[Using_the_Gyration_Remote_GYR3101US_%28Non-Fiire_Chief%29|gyration]]), these functions correspond to the buttons from left to right. If you are using a traditional 3 button mouse, you can use the F6, F7 and F8 keys on the keyboard for the three programmable functions instead. In both cases, the left mouse button is "ok", and the right mouse button is "cancel/go back".

Mouse button behavior is "absolute" when you press and hold the media/menu/ambiance button and "relative" when you tap and release.

The "absolute" behavior is generally more efficient. For example, in the case of the middle button (F7), "absolute" behavior means the action is executed without having to additionally click "ok". If you press and hold the middle button (F7) while moving your mouse pointer to the option, then let go, that option is executed. If you instead tap and release the menu button ("relative" behavior), you will only highlight the menu option. You must then press ok (the left mouse button) to execute the option.

Categories appear along the bottom of the screen, and the scenarios in each category popup vertically (like a pull-down menu in a PC, except upside down). If the main menu isn't already visible, bring it up by pressing the "start" button on a Windows I/R remote, or the "menu" button on a 3-button mouse. To exit a menu, use the back button on the I/R remote, the cancel button (right mouse button on a 3-button mouse), or the ESC key on a keyboard.

In UI2 the media is always full screen. If you're not playing your own media, the background media (i.e. screensaver images) is gallery art from the Internet (using flickr) or [[Use_my_own_pictures_in_the_Screen_Saver|pictures you select]]. If only the screensaver images are displayed on the Media Station, press the menu/middle/F7 button to bring up the menu. Right click/ESC to get rid of it. (This works even if your own media is playing.)

If you're using UI2's 3-button navigation model, the normal media control options on a traditional remote are replaced with a single button: "media" (left soft button or F6). Press this and move the pointer up and down for your skip functions (''ch+, ch-, skip fwd, skip back''). Move the pointer left and right for speed control (''rewind, fast forward''). The further you move, the faster the media playback changes. If you hold the button down (the left soft button or F6), your movement will be "absolute". Instead of the traditional "jog shuttle-type" control, movement to the right skips to the end of your media, and movement to the left skips to the beginning. Once you get used to it, you will find that navigating media is orders of magnitude faster and easier with this model than with a traditional remote. You can find a spot in a 2 hour movie in only a couple seconds with a click of a single button (compared to a slew of button clicks required using a traditional remote).

Also, in UI2 you can press the "ambiance" button (right soft button or F8). Move up/down to adjust the lights, and left/right to adjust the volume. As with the media playback, if you hold the F8/right soft button down while you move left and right, your volume control is in "absolute" mode (not "relative"). Moving hard right turns up the volume full blast; hard left is mute. This requires you have a TV or receiver that is serial-controlled, however. LinuxMCE can then directly and instantly set the volume position in sync with your hand movements. (Few TVs and receivers have this feature, unfortunately.)

There are other media control functions besides the most commonly used ''fast fwd/rewind/skip up/skip down''. You can, for example, choose 'subtitles' while watching a DVD, 'guide' while watching TV, and 'random' while listening to an audio CD. In the UI2 3 button model, these functions appear on the main menu (on the left-most pad, entitled 'now playing') and changes according to the type of media you're playing. Press the menu button (middle button/F7) to select these options.

This 3 button model is a new concept and very different from traditional navigation. Most people find it much faster once they become accustomed to it.

==Reload Router & Regen Orbiters==

While using LinuxMCE you'll see sometimes a message asking if you want to [[Quick reload router|reload the router]], or if you want to [[Orbiter Generator|regenerate the Orbiter UIs]] (User Interfaces). In general, these options refresh the LinuxMCE databases so that changes to the system can be recognized.

===Reload Router===
All devices in LinuxMCE obtain their configuration information from the [[DCERouter]], which is the central piece of software on the Core. All devices request a list of the other devices in the home from the router, so they can respond to them appropriately. (For example, an IP camera device might turn on the lights in the room whenever you're viewing the camera. To do so, the IP camera needs to know what lights are in the room.) Typically a device requests this information only when it's starting up. When you connect additional plug and play devices to the system, these new devices generally will work immediately, but their functionality may not be fully enabled within the LinuxMCE system until the DCE router is reloaded. When the router reloads, it signals all devices on the system to simultaneously reload and re-request the system data. Each existing device can then work with each new device. This process is known as a 'reload'. It generally takes about 10 seconds. Every time you add or remove devices, or change a device's configuration, you may be asked to do a reload. If you're going to add more devices or make more device changes, you can do the reload once you're done. If you're in the middle of watching a movie or TV, you can postpone the reload, since media players generally stop playing during reloads. Phone calls aren't affected, though, and TV shows being recorded by MythTV in the background are also unaffected.

===Regen the Orbiter===
LinuxMCE's [[Selecting_the_Right_UI|Orbiter User Interfaces]] are all "pre-rendered" in order to be more efficient. The User Interface source images are all very high resolution, but need to be resized to accommodate the resolution of each Orbiter screen. The Core server has a list of the Orbiters used by your system, and will generate the appropriate User Interface screen for each Orbiter. It will do this each time you request a "regen". If you have five different types of Orbiters (each with a different type of screen), then five different images will be generated during each regen.

These User Interface screen images are stored in the Core. The appropriate UI image is sent to an Orbiter whenever it is activated. For many low-power devices (like mobile phones or desktop phones) there just isn't the processing power to do scaling and rendering of a User Interface screen on the fly. They need to be pre-rendered (with text pre-embedded in the images) to be efficient.

Adding new scenarios may result in the creation of new buttons for the User Interface, or changes to the text on existing buttons. Perhaps an entirely new screen will be created.

Until the User Interface images are regenerated, though, you won't be able to see these new buttons (or screens) on your Orbiter. During the regen, new User Interface images for each type of Orbiter is generated by the Core. This can take about 2-5 minutes, depending on how many Orbiter types you have in your system.

You needn't do a regen every time you add a scenario. You can wait until you have finished adding all the scenarios. Furthermore, you can also regen only the Orbiter you are currently using by doing a "Quick regen". This allows you to see the new User Interface (following the addition of new scenarios) without having to do a full regen for all the Orbiters. Once you have finished adding scenarios, then you can do a full regen.

This regen process can be a bit annoying, but is necessary. In future editions of LinuxMCE, it is planned to allow Media Directors, which have a lot more processing power, to render their on-screen Orbiter User Interfaces on the fly (so you don't have to do a regen each time you add or remove a scenario).

You can do a [[Orbiter Generator#Running OrbiterGen (performing a "regen")|full Orbiter regen or a Quick regen]] at any time by using buttons on the Core's LinuxMCE [[Launch Manager]].

== Managing your media ==

LinuxMCE is always scanning for network shares, on Network-Attached Storage (NAS) devices and other Hard Disk Drives (HDDs) of PCs connected to the system (including Windows PCs). Universal Serial Bus (USB) drives are also detected. Every time a LinuxMCE finds a network share, you will be asked if you would like to use it. Whenever you reply "Yes", the file share can be used by any Media Director on the system. The file share is scanned for media, such as audio, video and photos, and any that are found are then cataloged in the Core's central database. For example, when you plug in a USB drive on a Media Station in the living room and tell LinuxMCE to use it, the media on the drive will be available to Media Directors in other rooms.

At the moment there is no way to restrict your media for 'local use only'; all Media Stations in the LinuxMCE system share the media catalog stored on the Core. (This is a limitation that will be addressed in the near future. Sometimes it is desirable to attach a USB drive in the master bedroom and not allow it to be shared, for example. ''Note: However, see [[folder lock|this article that describes a method to address this problem]].'')

Storage devices (NAS, USB drives, extra HDDs on the Core or Media Directors) are referred to as "Extra Drives". When an extra drive is added, it is listed in the device tree in '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]'''. Under 'Core' you'll see a device listed for each HDD in the Core, as well as for each NAS device. Under each Media Station will be listed the HDDs in that Media Station. By clicking on the device you can change the device's properties, such as the mount username/password. Each NAS device, and each file share on another PC, will show as a device listed under the Core; each is considered a child of the Core.

===Access control for shared media===
LinuxMCE creates a top level folder for 'public' media. This folder can be used by every user in the system. A 'private' media folder is also created for each user. Within each of those folders are sub-folders, labeled 'audio', 'video', 'pictures', 'data' and 'other'. Within each of those will also be sub-folders for the extra storage devices (NAS, USB, extra internal drives, etc). When you attach an extra storage device, you can specify whether the default directory structure should be used for it. Alternatively, you can specify 'just make it public' or 'make it private'.

Here's an example. Let's say you have 2 users: john and mary. You connect 3 storage devices:
# a NAS, for which you specify 'use default directory structure'. It is named 'Generic Network Storage [50]'
# a USB drive for which you specify 'make it all public'. It is named 'USB Drive [51]'
# a SATA drive for which you choose 'make it private for john'. It is named 'General Internal HDD [52]

Now let's say you're running Windows. Go to Network Neighborhood and find the LinuxMCE Core server. The directory tree ought to look like this:
<pre>
public
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
USB Drive [51]
john
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
General Internal HDD [52]
mary
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
</pre>
Whether you put your media under video, audio, pictures, data or other is unimportant. It will be scanned by LinuxMCE anyway. The contents of "General Internal HDD [52]" will be displayed in the folder john/other/General Internal HDD [52]. The contents of USB Drive [51] will be displayed in the folder public/other/USB Drive [51]. When John browses the contents in Network Neighborhood, he will be asked for his username and password. He can then access the content in both the public folder as well as the "john" folders (including General Internal HDD [52]). When Mary browses the contents with her username and password, she will see both the public and "mary" folders. She will not be able to see anything on General Internal HDD [52], however, since that drive was specified to be private for John.

In the case of John's private media, it won't be displayed in the LinuxMCE media browser unless you click 'Sources'-->'John'. However you ''can'' see the contents of General Internal HDD [52] (unless you deselect 'Sources'-->'Public' from the media browser). Generic Network Storage [50] would be different, however, since you specified to use the default directory structure for it. LinuxMCE will have created public directories on Generic Network Storage [50] for public video and public audio, as well as for john's video and mary's audio. The media file browser will show only the media that is in the public directories. (The same is true with the Windows Network Neighborhood browser.)

If Generic Network Storage [50] has existing media in the top (root) folder, you won't see it listed anywhere.

It is generally recommended, therefore, that when you add a new (blank) "extra" storage device, you choose to use the default directory structure on it. When you rip media to that device, the media can then be made either public or private, and LinuxMCE will automatically put it in the correct folder (audio, video, etc.).

If you connect an extra storage device that already has media on it, however, and that media isn't already organized in LinuxMCE's default directory structure, it's easiest if you simply 'make it all public' or 'make it all private'. If you were to 'use the default directory structure', you would need to manually move the files from the existing folders into one of the directory folders that LinuxMCE would then create for you.

When you rip files, you have the option of copying them to the Core. If you rip a CD and make it public, it will be stored in public/audio. If you go into Network Neighborhood and add a folder under public/audio, you would essentially be adding a folder on the Core. If you add a folder under public/audio/Generic Network Storage [50], you would be adding it to Generic Network Storage [50].

===Drive and network drive management===
This concept behind drive/network drive management is not the same as the method to which Linux and Windows users are accustomed. In Windows, for example, each network device shows up separately; they are never grouped together. There is an advantage to the way LinuxMCE manages drives. It's much simpler to add devices when you're a novice and don't understand networking. Further, if you're using an infrared remote control, you can manage drives with a single 'yes' or 'no,' click, which is very convenient. Lastly, all your media content is cataloged and presented in the same structure throughout the system, no matter which Media Director you're using or what room you're in.

In Windows, by comparison, if you connect a USB drive to a Windows PC in the bedroom, you won't see that content in the living room unless you 1) open file explorer, 2) create a new network share for it, 3) go into the living room, and 4) create a new mapped network drive there. (That isn't so easy to do with an infrared remote and without some knowledge of networking.) Further, you wouldn't be able to see the media in any other room in the house unless you were to also create mapped network shares in those rooms as well.

With LinuxMCE, when you connect a USB drive, for example, you can 'make it all public'; the media will be available everywhere. No other typing is required. With LinuxMCE, instead of managing multiple network shares and mapped drives, you can choose the Core's public folders in the Network Neighborhood browser from anywhere in the home, without having to know which storage devices the media is actually on. When you remove a USB drive from a Media Station, that media instantly disappears from the catalog displayed in every room. If you reattach it, it will re-appear.

You can also backup the media securely on the Core. LinuxMCE has built-in [http://en.wikipedia.org/wiki/RAID RAID] 5 (see '''[[LinuxMCE Admin Website]]-->Advanced-->[[RAID]]'''), so its HDD has similar backup capabilities to a [[NAS]] device.

To change the name of an extra device, go to the '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]''' and under the Core you will see listed the HDDs in the core and any connected NAS devices. Under each Media Station you will see the HDDs in that Media Station. All are given default names. You can change the description, which will also change the folder name. In the above example, changing "USB Drive [51]" to "Tokyo" means the directory public/other/USB Drive [51] would change to public/other/Tokyo.

You can see a list of the files in the system by folder In the '''[[LinuxMCE Admin Website]]-->Files & Media-->[[Media Files Sync]]''' menu. If a file is shown with a check box, the file exists both on the local disk as well as in LinuxMCE's master catalog. If it has a different icon, then LinuxMCE hasn't finished cataloging the media; just be patient. It should appear with a check mark soon (depending on how much new media was added).

Use this interface to manage change cover art and attributes. Under Files & Media there is also a cover art scan utility that will find cover art, as well as other attributes (actor, genre, etc.) obtained from Amazon.

====Linux operational details of network and disk mounts====
[[UpdateMedia]] is a daemon that constantly scans for media files in the /home/public and the /home/user_xxx folder created for each user. Any added media is cataloged in the pluto_media database File table, and attributes and cover art go into the Attribute and Picture tables. Under /home/public and /home/users_xxx is a data subfolder which contains the actual video, audio, pictures folders. (The /home/user_xxx directories themselves contain the system files for each user (like email boxes) as well as the main login for that user (in a "data" subfolder).

Extra devices are mounted as /mnt/device/xxx (where xxx is the device number). The mount point is the same whether it's a local drive or not. For example, USB drive [50] in a Media Station may be mounted as a local device named /mnt/device/50, but is also mounted as a Samba mount on other Media Stations as /mnt/device/50. The Core and the Media Stations all use the same mount names (/mnt/device/).

Within the /home/public/data and /home/user_xxx/data are symlinks to the physical directories specified by /mnt/device/xxx. Since the Core and all Media Stations mount the same /home directory (and all have the same /mnt/device mounts), they will all show the same files. Therefore, if the [[UpdateMedia]] daemon locates the file /home/public/data/audio/Generic Internal Drive [50]/The Beatles/Let it be.mp3, that file will be listed on every Media Station, too.

[[Category: Tutorials]]

Usage Intro

2008-07-12T22:34:38Z

Juanfe: /* Managing your media */

{| align="right"
| __TOC__
|}
LinuxMCE's main concepts are [[Devices]], Commands (aka [[Scenarios]] and Activities), and [[Events]]. An [[Orbiter]] is the device that displays the User Interface. It can be a [[Media Director|Media Station]], web pad, mobile phone, or other remote control device. The Orbiter User Interface is standardized for all Orbiters.

== Devices ==

A device is generally a piece of hardware or software, like the Xine Media Player, a light switch, or a mobile phone. Devices have three functions, abbreviated "DCE" (Data, Commands, Events):

# Retrieve configuration '''data'''
# Perform a '''command''' (turn on, turn off, fast forward, etc.)
# Report certain triggered '''events''' (e.g. 'motion detected', 'playback started', etc.)

== Scenarios ==

"[[Scenarios]]", "Activities", and "Command Groups" are interchangeable terms -- they mean the same thing. A scenario is a group of commands that can be sent to a device (or series of devices). In LinuxMCE, the default Orbiter main menu consists of several scenario categories, grouped by room. These categories are

* Lighting
* Media
* Climate
* Telecom
* Security

(These default categories are arbitrary and are set up at installation.) To perform an action in LinuxMCE, a scenario is chosen from one of these categories (located on the main menu of an Orbiter).

For example, in rooms which have both a TV and lights, LinuxMCE automatically creates a scenario called 'Showtime.' This scenario dims the lights to 10% whenever the TV starts playing. In rooms with a PVR or other TV-enabled device, another scenario is created called 'TV' (in the 'Media' category) to start the TV. Another scenario in the 'Media' category called 'Video' sends a command to the Orbiter to list your video content. Telecom scenarios are created to make phone calls. Security scenarios are created to view cameras and to arm an alarm.

Some [[What_scenarios_are_created_automatically%3F|default scenarios]] are created for you at installation. A fully-functional system can run using only the default scenarios, if you choose. You can also change or remove the default scenarios or add new ones. This is done though the '''[[LinuxMCE Admin Website]]-->Wizard-->[[Scenarios]]''' menu. When creating a scenario, the [[LinuxMCE Admin Website]] will show you the most appropriate wizard, based on the category you pick. If you're adding an activity in the lighting category, for example, the wizard will display a list of the lights in the room and let you pick which ones to turn off. If you're creating a scenario in the security category, it will list the installed cameras and will allow you to select which ones to display.

A scenario can send a command to any device in the system. By default, scenarios in the lighting category show you the room lights, allowing you to select which ones to which to send commands. However, from the '''Wizard-->[[Scenarios]]''' menu for the specific scenario, you can also specify a command to any device in your home. You could make a phone call, for example, even from a scenario in the lighting category.

Certain scenarios are assigned to certain rooms by default. This can be customized, however. When you manually select a room from the Orbiter main menu, the default scenarios for that room are displayed. In general they control devices in that room, but this can also be changed. If your kitchen is near the garage and you want a scenario to 'turn off the garage light', you can assign a scenario to the room 'kitchen' that will do just that. It doesn't matter that the light is in the garage.

For a Media Director, the on-screen Orbiter User Interface appears on the TV screen. It is manipulated by the mouse/keyboard or remote control connected to your Media Director. By default it is set to display the scenarios for the room in which the Media Director is located.

In contrast, a mobile Orbiter (such as a webpad) can be carried throughout the house. It must be able to select the scenarios for multiple rooms. Fortunately, the option to manually select which room you are currently in is available on every Orbiter's main menu.

This can occasionally cause some confusion. Perhaps both the Living Room and the Bedroom have a scenario called 'TV'. You may have a web pad that is in the Bedroom, but you then carry it to the Living Room. You may forget to tell the web pad that it's now in the Living Room (at the bottom of the Orbiter screen it will still say 'Bedroom'). You hit the 'TV' button expecting the Living Room TV to come on, but in fact you're still controlling the Bedroom and the TV comes on there instead. Finally you may realize that you must change your room location to Living Room, and you can then finally control the TV there.

Once you get used to this concept, though, you'll find it very useful. Conveniently, any Orbiter can be set to control any room and choose from the scenarios assigned to that room. No matter which Orbiter you use, the same set of scenarios will be displayed for each specific room. For example, the kitchen scenarios will always be the same, no matter which Orbiter you are using. (The scenarios are assigned by room -- not by Orbiter.) No matter whether you pick up your mobile phone, your web pad, or your remote control, you will always be shown the same list of scenario options for the Living Room.

You have the option of preventing some family members from using certain scenarios. From the [[LinuxMCE Admin Website]], certain scenarios and rooms can be [[Users#Restrict_Access|restricted to certain users]]. Maybe little Suzy's mobile phone Orbiter should be restricted so that she is only able to control her room and the living room, for example. She would only be able to execute the scenarios in those rooms, but not the Master Bedroom. Other possible options include [[Users#Restrict_Access|requiring a pin code]] to access the scenarios for a particular room.

== Events ==

Devices report events, such as 'Playback started' and 'Motion Sensor tripped'. If you want something to happen automatically in LinuxMCE, you create Event Handlers that react to these events. For example, you can create an event handler that listens for the 'Motion Sensor tripped' event from a motion detector and turns on the lights in response. An event handler might listen for the 'Sunrise' event, which could then prompt the sprinklers to come on.

LinuxMCE creates several default event handlers. In rooms in which you have a TV and lights, an event handler is created that listens for the 'Watching Media' event sent by a media player. When the event is detected, the Showtime scenario (which dims the lights) is executed in response. When you start a movie, therefore, the Showtime activity will be executed and the lights will be dimmed. There are other default event handlers that monitor for events like 'Security Breach' and 'Fire Alarm' (from a home security system).

== Controlling an Orbiter ==

To control the system, you use an [[Orbiter]], which is the LinuxMCE term for a remote control. All [[Orbiters]] have the same basic function: to display the scenarios in the room you're in and let you select one. The different Orbiters may [[Selecting_the_Right_UI|display the User Interface slightly differently]], depending on their screen size, but the function and the list of scenarios is always the same. For example, the [[Selecting_the_Right_UI|"UI1" interface]] (which is used on webpads and PDAs) displays the scenarios in horizontal rows. (If there are more than will fit on a row, there will be a "more" button.) A home button is always displayed that takes you to the main menu. On smaller displays, as on mobile phones or desktop phones, there's not enough room to show the scenarios themselves. The top level menu shows only the categories: Lights, Media, Climate, Security and Telecom. Selecting a category displays the scenarios in that category.

[[Selecting_the_Right_UI|"UI2"]] is the [[Selecting_the_Right_UI|preferred User Interface]] for Media Stations. Using a traditional I/R remote is not much different from using any other Media Center PC remote. The menu button brings up the main menu, and you use the ''left/right/up/down/enter'' buttons to navigate it. The ''fast forward/rewind/skip +/skip -'' keys are used for media playback.

If you have a pointing device like a mouse or gyro air mouse, the UI2 interface also supports a unique control architecture that lets you do everything with 3 (programmable) buttons (plus ok and cancel). The 3 buttons are "MEDIA", "MENU", "AMBIANCE".

On a mouse with 3 programmable buttons (such as the [[Using_the_Gyration_Remote_GYR3101US_%28Non-Fiire_Chief%29|gyration]]), these functions correspond to the buttons from left to right. If you are using a traditional 3 button mouse, you can use the F6, F7 and F8 keys on the keyboard for the three programmable functions instead. In both cases, the left mouse button is "ok", and the right mouse button is "cancel/go back".

Mouse button behavior is "absolute" when you press and hold the media/menu/ambiance button and "relative" when you tap and release.

The "absolute" behavior is generally more efficient. For example, in the case of the middle button (F7), "absolute" behavior means the action is executed without having to additionally click "ok". If you press and hold the middle button (F7) while moving your mouse pointer to the option, then let go, that option is executed. If you instead tap and release the menu button ("relative" behavior), you will only highlight the menu option. You must then press ok (the left mouse button) to execute the option.

Categories appear along the bottom of the screen, and the scenarios in each category popup vertically (like a pull-down menu in a PC, except upside down). If the main menu isn't already visible, bring it up by pressing the "start" button on a Windows I/R remote, or the "menu" button on a 3-button mouse. To exit a menu, use the back button on the I/R remote, the cancel button (right mouse button on a 3-button mouse), or the ESC key on a keyboard.

In UI2 the media is always full screen. If you're not playing your own media, the background media (i.e. screensaver images) is gallery art from the Internet (using flickr) or [[Use_my_own_pictures_in_the_Screen_Saver|pictures you select]]. If only the screensaver images are displayed on the Media Station, press the menu/middle/F7 button to bring up the menu. Right click/ESC to get rid of it. (This works even if your own media is playing.)

If you're using UI2's 3-button navigation model, the normal media control options on a traditional remote are replaced with a single button: "media" (left soft button or F6). Press this and move the pointer up and down for your skip functions (''ch+, ch-, skip fwd, skip back''). Move the pointer left and right for speed control (''rewind, fast forward''). The further you move, the faster the media playback changes. If you hold the button down (the left soft button or F6), your movement will be "absolute". Instead of the traditional "jog shuttle-type" control, movement to the right skips to the end of your media, and movement to the left skips to the beginning. Once you get used to it, you will find that navigating media is orders of magnitude faster and easier with this model than with a traditional remote. You can find a spot in a 2 hour movie in only a couple seconds with a click of a single button (compared to a slew of button clicks required using a traditional remote).

Also, in UI2 you can press the "ambiance" button (right soft button or F8). Move up/down to adjust the lights, and left/right to adjust the volume. As with the media playback, if you hold the F8/right soft button down while you move left and right, your volume control is in "absolute" mode (not "relative"). Moving hard right turns up the volume full blast; hard left is mute. This requires you have a TV or receiver that is serial-controlled, however. LinuxMCE can then directly and instantly set the volume position in sync with your hand movements. (Few TVs and receivers have this feature, unfortunately.)

There are other media control functions besides the most commonly used ''fast fwd/rewind/skip up/skip down''. You can, for example, choose 'subtitles' while watching a DVD, 'guide' while watching TV, and 'random' while listening to an audio CD. In the UI2 3 button model, these functions appear on the main menu (on the left-most pad, entitled 'now playing') and changes according to the type of media you're playing. Press the menu button (middle button/F7) to select these options.

This 3 button model is a new concept and very different from traditional navigation. Most people find it much faster once they become accustomed to it.

==Reload Router & Regen Orbiters==

While using LinuxMCE you'll see sometimes a message asking if you want to [[Quick reload router|reload the router]], or if you want to [[Orbiter Generator|regenerate the Orbiter UIs]] (User Interfaces). In general, these options refresh the LinuxMCE databases so that changes to the system can be recognized.

===Reload Router===
All devices in LinuxMCE obtain their configuration information from the [[DCERouter]], which is the central piece of software on the Core. All devices request a list of the other devices in the home from the router, so they can respond to them appropriately. (For example, an IP camera device might turn on the lights in the room whenever you're viewing the camera. To do so, the IP camera needs to know what lights are in the room.) Typically a device requests this information only when it's starting up. When you connect additional plug and play devices to the system, these new devices generally will work immediately, but their functionality may not be fully enabled within the LinuxMCE system until the DCE router is reloaded. When the router reloads, it signals all devices on the system to simultaneously reload and re-request the system data. Each existing device can then work with each new device. This process is known as a 'reload'. It generally takes about 10 seconds. Every time you add or remove devices, or change a device's configuration, you may be asked to do a reload. If you're going to add more devices or make more device changes, you can do the reload once you're done. If you're in the middle of watching a movie or TV, you can postpone the reload, since media players generally stop playing during reloads. Phone calls aren't affected, though, and TV shows being recorded by MythTV in the background are also unaffected.

===Regen the Orbiter===
LinuxMCE's [[Selecting_the_Right_UI|Orbiter User Interfaces]] are all "pre-rendered" in order to be more efficient. The User Interface source images are all very high resolution, but need to be resized to accommodate the resolution of each Orbiter screen. The Core server has a list of the Orbiters used by your system, and will generate the appropriate User Interface screen for each Orbiter. It will do this each time you request a "regen". If you have five different types of Orbiters (each with a different type of screen), then five different images will be generated during each regen.

These User Interface screen images are stored in the Core. The appropriate UI image is sent to an Orbiter whenever it is activated. For many low-power devices (like mobile phones or desktop phones) there just isn't the processing power to do scaling and rendering of a User Interface screen on the fly. They need to be pre-rendered (with text pre-embedded in the images) to be efficient.

Adding new scenarios may result in the creation of new buttons for the User Interface, or changes to the text on existing buttons. Perhaps an entirely new screen will be created.

Until the User Interface images are regenerated, though, you won't be able to see these new buttons (or screens) on your Orbiter. During the regen, new User Interface images for each type of Orbiter is generated by the Core. This can take about 2-5 minutes, depending on how many Orbiter types you have in your system.

You needn't do a regen every time you add a scenario. You can wait until you have finished adding all the scenarios. Furthermore, you can also regen only the Orbiter you are currently using by doing a "Quick regen". This allows you to see the new User Interface (following the addition of new scenarios) without having to do a full regen for all the Orbiters. Once you have finished adding scenarios, then you can do a full regen.

This regen process can be a bit annoying, but is necessary. In future editions of LinuxMCE, it is planned to allow Media Directors, which have a lot more processing power, to render their on-screen Orbiter User Interfaces on the fly (so you don't have to do a regen each time you add or remove a scenario).

You can do a [[Orbiter Generator#Running OrbiterGen (performing a "regen")|full Orbiter regen or a Quick regen]] at any time by using buttons on the Core's LinuxMCE [[Launch Manager]].

== Managing your media ==

LinuxMCE is always scanning for network shares, on Network-Attached Storage (NAS) devices and other Hard Disk Drives (HDDs) of PCs connected to the system (including Windows PCs). Universal Serial Bus (USB) drives are also detected. Every time a LinuxMCE finds a network share, you will be asked if you would like to use it. Whenever you reply "Yes", the file share can be used by any Media Director on the system. The file share is scanned for media, such as audio, video and photos, and any that are found are then cataloged in the Core's central database. For example, when you plug in a USB drive on a Media Station in the living room and tell LinuxMCE to use it, the media on the drive will be available to Media Directors in other rooms.

At the moment there is no way to restrict your media for 'local use only'; all Media Stations in the LinuxMCE system share the media catalog stored on the Core. (This is a limitation that will be addressed in the near future. Sometimes it is desirable to attach a USB drive in the master bedroom and not allow it to be shared, for example. ''Note: However, see [[folder lock|this article that describes a method to address this problem]].'')

Storage devices (NAS, USB drives, extra HDDs on the Core or Media Directors) are referred to as "Extra Drives". When an extra drive is added, it is listed in the device tree in '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]'''. Under 'Core' you'll see a device listed for each HDD in the Core, as well as for each NAS device. Under each Media Station will be listed the HDDs in that Media Station. By clicking on the device you can change the device's properties, such as the mount username/password. Each NAS device, and each file share on another PC, will show as a device listed under the Core; each is considered a child of the Core.

===Access control for shared media===
LinuxMCE creates a top level folder for 'public' media. This folder can be used by every user in the system. A 'private' media folder is also created for each user. Within each of those folders are sub-folders, labeled 'audio', 'video', 'pictures', 'data' and 'other'. Within each of those will also be sub-folders for the extra storage devices (NAS, USB, extra internal drives, etc). When you attach an extra storage device, you can specify whether the default directory structure should be used for it. Alternatively, you can specify 'just make it public' or 'make it private'.

Here's an example. Let's say you have 2 users: john and mary. You connect 3 storage devices:
# a NAS, for which you specify 'use default directory structure'. It is named 'Generic Network Storage [50]'
# a USB drive for which you specify 'make it all public'. It is named 'USB Drive [51]'
# a SATA drive for which you choose 'make it private for john'. It is named 'General Internal HDD [52]

Now let's say you're running Windows. Go to Network Neighborhood and find the LinuxMCE Core server. The directory tree ought to look like this:
<pre>
public
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
USB Drive [51]
john
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
General Internal HDD [52]
mary
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
</pre>
Whether you put your media under video, audio, pictures, data or other is unimportant. It will be scanned by LinuxMCE anyway. The contents of "General Internal HDD [52]" will be displayed in the folder john/other/General Internal HDD [52]. The contents of USB Drive [51] will be displayed in the folder public/other/USB Drive [51]. When John browses the contents in Network Neighborhood, he will be asked for his username and password. He can then access the content in both the public folder as well as the "john" folders (including General Internal HDD [52]). When Mary browses the contents with her username and password, she will see both the public and "mary" folders. She will not be able to see anything on General Internal HDD [52], however, since that drive was specified to be private for John.

In the case of John's private media, it won't be displayed in the LinuxMCE media browser unless you click 'Sources'-->'John'. However you ''can'' see the contents of General Internal HDD [52] (unless you deselect 'Sources'-->'Public' from the media browser). Generic Network Storage [50] would be different, however, since you specified to use the default directory structure for it. LinuxMCE will have created public directories on Generic Network Storage [50] for public video and public audio, as well as for john's video and mary's audio. The media file browser will show only the media that is in the public directories. (The same is true with the Windows Network Neighborhood browser.)

If Generic Network Storage [50] has existing media in the top (root) folder, you won't see it listed anywhere.

It is generally recommended, therefore, that when you add a new (blank) "extra" storage device, you choose to use the default directory structure on it. When you rip media to that device, the media can then be made either public or private, and LinuxMCE will automatically put it in the correct folder (audio, video, etc.).

If you connect an extra storage device that already has media on it, however, and that media isn't already organized in LinuxMCE's default directory structure, it's easiest if you simply 'make it all public' or 'make it all private'. If you were to 'use the default directory structure', you would need to manually move the files from the existing folders into one of the directory folders that LinuxMCE would then create for you.

When you rip files, you have the option of copying them to the Core. If you rip a CD and make it public, it will be stored in public/audio. If you go into Network Neighborhood and add a folder under public/audio, you would essentially be adding a folder on the Core. If you add a folder under public/audio/Generic Network Storage [50], you would be adding it to Generic Network Storage [50].

===Drive and network drive management===
This concept behind drive/network drive management is not the same as the method to which Linux and Windows users are accustomed. In Windows, for example, each network device shows up separately; they are never grouped together. There is an advantage to the way LinuxMCE manages drives. It's much simpler to add devices when you're a novice and don't understand networking. Further, if you're using an infrared remote control, you can manage drives with a single 'yes' or 'no,' click, which is very convenient. Lastly, all your media content is cataloged and presented in the same structure throughout the system, no matter which Media Director you're using or what room you're in.

In Windows, by comparison, if you connect a USB drive to a Windows PC in the bedroom, you won't see that content in the living room unless you 1) open file explorer, 2) create a new network share for it, 3) go into the living room, and 4) create a new mapped network drive there. (That isn't so easy to do with an infrared remote and without some knowledge of networking.) Further, you wouldn't be able to see the media in any other room in the house unless you were to also create mapped network shares in those rooms as well.

With LinuxMCE, when you connect a USB drive, for example, you can 'make it all public'; the media will be available everywhere. No other typing is required. With LinuxMCE, instead of managing multiple network shares and mapped drives, you can choose the Core's public folders in the Network Neighborhood browser from anywhere in the home, without having to know which storage devices the media is actually on. When you remove a USB drive from a Media Station, that media instantly disappears from the catalog displayed in every room. If you reattach it, it will re-appear.

You can also backup the media securely on the Core. LinuxMCE has built-in [http://en.wikipedia.org/wiki/RAID RAID] 5 (see '''[[LinuxMCE Admin Website]]-->Advanced-->[[RAID]]'''), so its HDD has similar backup capabilities to a [[NAS]] device.

To change the name of an extra device, go to the '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]''' and under the Core you will see listed the HDDs in the core and any connected NAS devices. Under each Media Station you will see the HDDs in that Media Station. All are given default names. You can change the description, which will also change the folder name. In the above example, changing "USB Drive [51]" to "Tokyo" means the directory public/other/USB Drive [51] would change to public/other/Tokyo.

You can see a list of the files in the system by folder In the '''[[LinuxMCE Admin Website]]-->Files & Media-->[[Media Files Sync]]''' menu. If a file is shown with a check box, the file exists both on the local disk as well as in LinuxMCE's master catalog. If it has a different icon, then LinuxMCE hasn't finished cataloging the media; just be patient. It should appear with a check mark soon (depending on how much new media was added).

Use this interface to manage change cover art and attributes. Under Files & Media there is also a cover art scan utility that will find cover art, as well as other attributes (actor, genre, etc.) obtained from Amazon.

====Background and Linux operational details====
[[UpdateMedia]] is a daemon that constantly scans for media files in the /home/public and the /home/user_xxx folder created for each user. Any added media is cataloged in the pluto_media database File table, and attributes and cover art go into the Attribute and Picture tables. Under /home/public and /home/users_xxx is a data subfolder which contains the actual video, audio, pictures folders. (The /home/user_xxx directories themselves contain the system files for each user (like email boxes) as well as the main login for that user (in a "data" subfolder).

Extra devices are mounted as /mnt/device/xxx (where xxx is the device number). The mount point is the same whether it's a local drive or not. For example, USB drive [50] in a Media Station may be mounted as a local device named /mnt/device/50, but is also mounted as a Samba mount on other Media Stations as /mnt/device/50. The Core and the Media Stations all use the same mount names (/mnt/device/).

Within the /home/public/data and /home/user_xxx/data are symlinks to the physical directories specified by /mnt/device/xxx. Since the Core and all Media Stations mount the same /home directory (and all have the same /mnt/device mounts), they will all show the same files. Therefore, if the [[UpdateMedia]] daemon locates the file /home/public/data/audio/Generic Internal Drive [50]/The Beatles/Let it be.mp3, that file will be listed on every Media Station, too.

[[Category: Tutorials]]

Help:Editing

2008-07-12T22:30:01Z

Juanfe:

[http://en.wikipedia.org/wiki/Help:Editing link on wikipedia]

You can look at "edit" of this page to see how the following simple markup works:

=Top Header=
==Second: This is how you can do a section header==
===Third: Which can be nested by adding more equal signs===
====Fourth Header====
The headings will be put into a table of contents at the top, but only when the page has 4 or more section headers (nested or not).

*This is an unordered (bullet) list.
**These can also be nested

#This is an ordered (numbered) list
##I think these can be nested as well
##They can
#Next ordered (numbered) list
##Nested
##Nested

:This will be indented
::Indented more

Lines starting with a space will be "preformatted", and placed in one of those typical dotted boxes.

''Italic text''

'''bold text'''

'''''italic and bold'''''

Urls are automaticly recognized, but there are more possibilities. For example:
http://some.domain/page.html shows the URL 'as is'
[http://some.domain/page.html] shows up as an increasing number
[http://some.domain/page.html alternative text] shows up as "alternative text"

[[other wiki page]] link to other_wiki_page, shows as "other wiki page"
[[other wiki page|alternative text]] link to other_wiki_page, shows as "alternative text"

<nowiki>this will stop the wiki from applying formatting, useful if you don't want url's turned into links for instance: http://some.domain/page.html</nowiki>

Alternatively you can also use the standard HTML tags.
===Third Level: You unnest by removing one level of equal signs===

Help:Editing

2008-07-12T22:29:03Z

Juanfe:

[http://en.wikipedia.org/wiki/Help:Editing link on wikipedia]

You can look at "edit" of this page to see how the following simple markup works:

=Top Header=
==This is how you can do a section header==
===Which can be nested by adding more equal signs===
====Fourth Header====
The headings will be put into a table of contents at the top, but only when the page has 4 or more section headers (nested or not).

*This is an unordered (bullet) list.
**These can also be nested

#This is an ordered (numbered) list
##I think these can be nested as well
##They can
#Next ordered (numbered) list
##Nested
##Nested

:This will be indented
::Indented more

Lines starting with a space will be "preformatted", and placed in one of those typical dotted boxes.

''Italic text''

'''bold text'''

'''''italic and bold'''''

Urls are automaticly recognized, but there are more possibilities. For example:
http://some.domain/page.html shows the URL 'as is'
[http://some.domain/page.html] shows up as an increasing number
[http://some.domain/page.html alternative text] shows up as "alternative text"

[[other wiki page]] link to other_wiki_page, shows as "other wiki page"
[[other wiki page|alternative text]] link to other_wiki_page, shows as "alternative text"

<nowiki>this will stop the wiki from applying formatting, useful if you don't want url's turned into links for instance: http://some.domain/page.html</nowiki>

Alternatively you can also use the standard HTML tags.
===You unnest by removing one level of equal signs===

Help:Editing

2008-07-12T22:27:06Z

Juanfe: /* Fourth Header */

Usage Intro

2008-07-12T22:24:17Z

Juanfe: /* Managing your media */

{| align="right"
| __TOC__
|}
LinuxMCE's main concepts are [[Devices]], Commands (aka [[Scenarios]] and Activities), and [[Events]]. An [[Orbiter]] is the device that displays the User Interface. It can be a [[Media Director|Media Station]], web pad, mobile phone, or other remote control device. The Orbiter User Interface is standardized for all Orbiters.

== Devices ==

A device is generally a piece of hardware or software, like the Xine Media Player, a light switch, or a mobile phone. Devices have three functions, abbreviated "DCE" (Data, Commands, Events):

# Retrieve configuration '''data'''
# Perform a '''command''' (turn on, turn off, fast forward, etc.)
# Report certain triggered '''events''' (e.g. 'motion detected', 'playback started', etc.)

== Scenarios ==

"[[Scenarios]]", "Activities", and "Command Groups" are interchangeable terms -- they mean the same thing. A scenario is a group of commands that can be sent to a device (or series of devices). In LinuxMCE, the default Orbiter main menu consists of several scenario categories, grouped by room. These categories are

* Lighting
* Media
* Climate
* Telecom
* Security

(These default categories are arbitrary and are set up at installation.) To perform an action in LinuxMCE, a scenario is chosen from one of these categories (located on the main menu of an Orbiter).

For example, in rooms which have both a TV and lights, LinuxMCE automatically creates a scenario called 'Showtime.' This scenario dims the lights to 10% whenever the TV starts playing. In rooms with a PVR or other TV-enabled device, another scenario is created called 'TV' (in the 'Media' category) to start the TV. Another scenario in the 'Media' category called 'Video' sends a command to the Orbiter to list your video content. Telecom scenarios are created to make phone calls. Security scenarios are created to view cameras and to arm an alarm.

Some [[What_scenarios_are_created_automatically%3F|default scenarios]] are created for you at installation. A fully-functional system can run using only the default scenarios, if you choose. You can also change or remove the default scenarios or add new ones. This is done though the '''[[LinuxMCE Admin Website]]-->Wizard-->[[Scenarios]]''' menu. When creating a scenario, the [[LinuxMCE Admin Website]] will show you the most appropriate wizard, based on the category you pick. If you're adding an activity in the lighting category, for example, the wizard will display a list of the lights in the room and let you pick which ones to turn off. If you're creating a scenario in the security category, it will list the installed cameras and will allow you to select which ones to display.

A scenario can send a command to any device in the system. By default, scenarios in the lighting category show you the room lights, allowing you to select which ones to which to send commands. However, from the '''Wizard-->[[Scenarios]]''' menu for the specific scenario, you can also specify a command to any device in your home. You could make a phone call, for example, even from a scenario in the lighting category.

Certain scenarios are assigned to certain rooms by default. This can be customized, however. When you manually select a room from the Orbiter main menu, the default scenarios for that room are displayed. In general they control devices in that room, but this can also be changed. If your kitchen is near the garage and you want a scenario to 'turn off the garage light', you can assign a scenario to the room 'kitchen' that will do just that. It doesn't matter that the light is in the garage.

For a Media Director, the on-screen Orbiter User Interface appears on the TV screen. It is manipulated by the mouse/keyboard or remote control connected to your Media Director. By default it is set to display the scenarios for the room in which the Media Director is located.

In contrast, a mobile Orbiter (such as a webpad) can be carried throughout the house. It must be able to select the scenarios for multiple rooms. Fortunately, the option to manually select which room you are currently in is available on every Orbiter's main menu.

This can occasionally cause some confusion. Perhaps both the Living Room and the Bedroom have a scenario called 'TV'. You may have a web pad that is in the Bedroom, but you then carry it to the Living Room. You may forget to tell the web pad that it's now in the Living Room (at the bottom of the Orbiter screen it will still say 'Bedroom'). You hit the 'TV' button expecting the Living Room TV to come on, but in fact you're still controlling the Bedroom and the TV comes on there instead. Finally you may realize that you must change your room location to Living Room, and you can then finally control the TV there.

Once you get used to this concept, though, you'll find it very useful. Conveniently, any Orbiter can be set to control any room and choose from the scenarios assigned to that room. No matter which Orbiter you use, the same set of scenarios will be displayed for each specific room. For example, the kitchen scenarios will always be the same, no matter which Orbiter you are using. (The scenarios are assigned by room -- not by Orbiter.) No matter whether you pick up your mobile phone, your web pad, or your remote control, you will always be shown the same list of scenario options for the Living Room.

You have the option of preventing some family members from using certain scenarios. From the [[LinuxMCE Admin Website]], certain scenarios and rooms can be [[Users#Restrict_Access|restricted to certain users]]. Maybe little Suzy's mobile phone Orbiter should be restricted so that she is only able to control her room and the living room, for example. She would only be able to execute the scenarios in those rooms, but not the Master Bedroom. Other possible options include [[Users#Restrict_Access|requiring a pin code]] to access the scenarios for a particular room.

== Events ==

Devices report events, such as 'Playback started' and 'Motion Sensor tripped'. If you want something to happen automatically in LinuxMCE, you create Event Handlers that react to these events. For example, you can create an event handler that listens for the 'Motion Sensor tripped' event from a motion detector and turns on the lights in response. An event handler might listen for the 'Sunrise' event, which could then prompt the sprinklers to come on.

LinuxMCE creates several default event handlers. In rooms in which you have a TV and lights, an event handler is created that listens for the 'Watching Media' event sent by a media player. When the event is detected, the Showtime scenario (which dims the lights) is executed in response. When you start a movie, therefore, the Showtime activity will be executed and the lights will be dimmed. There are other default event handlers that monitor for events like 'Security Breach' and 'Fire Alarm' (from a home security system).

== Controlling an Orbiter ==

To control the system, you use an [[Orbiter]], which is the LinuxMCE term for a remote control. All [[Orbiters]] have the same basic function: to display the scenarios in the room you're in and let you select one. The different Orbiters may [[Selecting_the_Right_UI|display the User Interface slightly differently]], depending on their screen size, but the function and the list of scenarios is always the same. For example, the [[Selecting_the_Right_UI|"UI1" interface]] (which is used on webpads and PDAs) displays the scenarios in horizontal rows. (If there are more than will fit on a row, there will be a "more" button.) A home button is always displayed that takes you to the main menu. On smaller displays, as on mobile phones or desktop phones, there's not enough room to show the scenarios themselves. The top level menu shows only the categories: Lights, Media, Climate, Security and Telecom. Selecting a category displays the scenarios in that category.

[[Selecting_the_Right_UI|"UI2"]] is the [[Selecting_the_Right_UI|preferred User Interface]] for Media Stations. Using a traditional I/R remote is not much different from using any other Media Center PC remote. The menu button brings up the main menu, and you use the ''left/right/up/down/enter'' buttons to navigate it. The ''fast forward/rewind/skip +/skip -'' keys are used for media playback.

If you have a pointing device like a mouse or gyro air mouse, the UI2 interface also supports a unique control architecture that lets you do everything with 3 (programmable) buttons (plus ok and cancel). The 3 buttons are "MEDIA", "MENU", "AMBIANCE".

On a mouse with 3 programmable buttons (such as the [[Using_the_Gyration_Remote_GYR3101US_%28Non-Fiire_Chief%29|gyration]]), these functions correspond to the buttons from left to right. If you are using a traditional 3 button mouse, you can use the F6, F7 and F8 keys on the keyboard for the three programmable functions instead. In both cases, the left mouse button is "ok", and the right mouse button is "cancel/go back".

Mouse button behavior is "absolute" when you press and hold the media/menu/ambiance button and "relative" when you tap and release.

The "absolute" behavior is generally more efficient. For example, in the case of the middle button (F7), "absolute" behavior means the action is executed without having to additionally click "ok". If you press and hold the middle button (F7) while moving your mouse pointer to the option, then let go, that option is executed. If you instead tap and release the menu button ("relative" behavior), you will only highlight the menu option. You must then press ok (the left mouse button) to execute the option.

Categories appear along the bottom of the screen, and the scenarios in each category popup vertically (like a pull-down menu in a PC, except upside down). If the main menu isn't already visible, bring it up by pressing the "start" button on a Windows I/R remote, or the "menu" button on a 3-button mouse. To exit a menu, use the back button on the I/R remote, the cancel button (right mouse button on a 3-button mouse), or the ESC key on a keyboard.

In UI2 the media is always full screen. If you're not playing your own media, the background media (i.e. screensaver images) is gallery art from the Internet (using flickr) or [[Use_my_own_pictures_in_the_Screen_Saver|pictures you select]]. If only the screensaver images are displayed on the Media Station, press the menu/middle/F7 button to bring up the menu. Right click/ESC to get rid of it. (This works even if your own media is playing.)

If you're using UI2's 3-button navigation model, the normal media control options on a traditional remote are replaced with a single button: "media" (left soft button or F6). Press this and move the pointer up and down for your skip functions (''ch+, ch-, skip fwd, skip back''). Move the pointer left and right for speed control (''rewind, fast forward''). The further you move, the faster the media playback changes. If you hold the button down (the left soft button or F6), your movement will be "absolute". Instead of the traditional "jog shuttle-type" control, movement to the right skips to the end of your media, and movement to the left skips to the beginning. Once you get used to it, you will find that navigating media is orders of magnitude faster and easier with this model than with a traditional remote. You can find a spot in a 2 hour movie in only a couple seconds with a click of a single button (compared to a slew of button clicks required using a traditional remote).

Also, in UI2 you can press the "ambiance" button (right soft button or F8). Move up/down to adjust the lights, and left/right to adjust the volume. As with the media playback, if you hold the F8/right soft button down while you move left and right, your volume control is in "absolute" mode (not "relative"). Moving hard right turns up the volume full blast; hard left is mute. This requires you have a TV or receiver that is serial-controlled, however. LinuxMCE can then directly and instantly set the volume position in sync with your hand movements. (Few TVs and receivers have this feature, unfortunately.)

There are other media control functions besides the most commonly used ''fast fwd/rewind/skip up/skip down''. You can, for example, choose 'subtitles' while watching a DVD, 'guide' while watching TV, and 'random' while listening to an audio CD. In the UI2 3 button model, these functions appear on the main menu (on the left-most pad, entitled 'now playing') and changes according to the type of media you're playing. Press the menu button (middle button/F7) to select these options.

This 3 button model is a new concept and very different from traditional navigation. Most people find it much faster once they become accustomed to it.

==Reload Router & Regen Orbiters==

While using LinuxMCE you'll see sometimes a message asking if you want to [[Quick reload router|reload the router]], or if you want to [[Orbiter Generator|regenerate the Orbiter UIs]] (User Interfaces). In general, these options refresh the LinuxMCE databases so that changes to the system can be recognized.

===Reload Router===
All devices in LinuxMCE obtain their configuration information from the [[DCERouter]], which is the central piece of software on the Core. All devices request a list of the other devices in the home from the router, so they can respond to them appropriately. (For example, an IP camera device might turn on the lights in the room whenever you're viewing the camera. To do so, the IP camera needs to know what lights are in the room.) Typically a device requests this information only when it's starting up. When you connect additional plug and play devices to the system, these new devices generally will work immediately, but their functionality may not be fully enabled within the LinuxMCE system until the DCE router is reloaded. When the router reloads, it signals all devices on the system to simultaneously reload and re-request the system data. Each existing device can then work with each new device. This process is known as a 'reload'. It generally takes about 10 seconds. Every time you add or remove devices, or change a device's configuration, you may be asked to do a reload. If you're going to add more devices or make more device changes, you can do the reload once you're done. If you're in the middle of watching a movie or TV, you can postpone the reload, since media players generally stop playing during reloads. Phone calls aren't affected, though, and TV shows being recorded by MythTV in the background are also unaffected.

===Regen the Orbiter===
LinuxMCE's [[Selecting_the_Right_UI|Orbiter User Interfaces]] are all "pre-rendered" in order to be more efficient. The User Interface source images are all very high resolution, but need to be resized to accommodate the resolution of each Orbiter screen. The Core server has a list of the Orbiters used by your system, and will generate the appropriate User Interface screen for each Orbiter. It will do this each time you request a "regen". If you have five different types of Orbiters (each with a different type of screen), then five different images will be generated during each regen.

These User Interface screen images are stored in the Core. The appropriate UI image is sent to an Orbiter whenever it is activated. For many low-power devices (like mobile phones or desktop phones) there just isn't the processing power to do scaling and rendering of a User Interface screen on the fly. They need to be pre-rendered (with text pre-embedded in the images) to be efficient.

Adding new scenarios may result in the creation of new buttons for the User Interface, or changes to the text on existing buttons. Perhaps an entirely new screen will be created.

Until the User Interface images are regenerated, though, you won't be able to see these new buttons (or screens) on your Orbiter. During the regen, new User Interface images for each type of Orbiter is generated by the Core. This can take about 2-5 minutes, depending on how many Orbiter types you have in your system.

You needn't do a regen every time you add a scenario. You can wait until you have finished adding all the scenarios. Furthermore, you can also regen only the Orbiter you are currently using by doing a "Quick regen". This allows you to see the new User Interface (following the addition of new scenarios) without having to do a full regen for all the Orbiters. Once you have finished adding scenarios, then you can do a full regen.

This regen process can be a bit annoying, but is necessary. In future editions of LinuxMCE, it is planned to allow Media Directors, which have a lot more processing power, to render their on-screen Orbiter User Interfaces on the fly (so you don't have to do a regen each time you add or remove a scenario).

You can do a [[Orbiter Generator#Running OrbiterGen (performing a "regen")|full Orbiter regen or a Quick regen]] at any time by using buttons on the Core's LinuxMCE [[Launch Manager]].

== Managing your media ==

LinuxMCE is always scanning for network shares, on Network-Attached Storage (NAS) devices and other Hard Disk Drives (HDDs) of PCs connected to the system (including Windows PCs). Universal Serial Bus (USB) drives are also detected. Every time a LinuxMCE finds a network share, you will be asked if you would like to use it. Whenever you reply "Yes", the file share can be used by any Media Director on the system. The file share is scanned for media, such as audio, video and photos, and any that are found are then cataloged in the Core's central database. For example, when you plug in a USB drive on a Media Station in the living room and tell LinuxMCE to use it, the media on the drive will be available to Media Directors in other rooms.

At the moment there is no way to restrict your media for 'local use only'; all Media Stations in the LinuxMCE system share the media catalog stored on the Core. (This is a limitation that will be addressed in the near future. Sometimes it is desirable to attach a USB drive in the master bedroom and not allow it to be shared, for example. ''Note: However, see [[folder lock|this article that describes a method to address this problem]].'')

Storage devices (NAS, USB drives, extra HDDs on the Core or Media Directors) are referred to as "Extra Drives". When an extra drive is added, it is listed in the device tree in '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]'''. Under 'Core' you'll see a device listed for each HDD in the Core, as well as for each NAS device. Under each Media Station will be listed the HDDs in that Media Station. By clicking on the device you can change the device's properties, such as the mount username/password. Each NAS device, and each file share on another PC, will show as a device listed under the Core; each is considered a child of the Core.

LinuxMCE creates a top level folder for 'public' media. This folder can be used by every user in the system. A 'private' media folder is also created for each user. Within each of those folders are sub-folders, labeled 'audio', 'video', 'pictures', 'data' and 'other'. Within each of those will also be sub-folders for the extra storage devices (NAS, USB, extra internal drives, etc). When you attach an extra storage device, you can specify whether the default directory structure should be used for it. Alternatively, you can specify 'just make it public' or 'make it private'.

Here's an example. Let's say you have 2 users: john and mary. You connect 3 storage devices:
# a NAS, for which you specify 'use default directory structure'. It is named 'Generic Network Storage [50]'
# a USB drive for which you specify 'make it all public'. It is named 'USB Drive [51]'
# a SATA drive for which you choose 'make it private for john'. It is named 'General Internal HDD [52]

Now let's say you're running Windows. Go to Network Neighborhood and find the LinuxMCE Core server. The directory tree ought to look like this:
<pre>
public
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
USB Drive [51]
john
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
General Internal HDD [52]
mary
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
</pre>
Whether you put your media under video, audio, pictures, data or other is unimportant. It will be scanned by LinuxMCE anyway. The contents of "General Internal HDD [52]" will be displayed in the folder john/other/General Internal HDD [52]. The contents of USB Drive [51] will be displayed in the folder public/other/USB Drive [51]. When John browses the contents in Network Neighborhood, he will be asked for his username and password. He can then access the content in both the public folder as well as the "john" folders (including General Internal HDD [52]). When Mary browses the contents with her username and password, she will see both the public and "mary" folders. She will not be able to see anything on General Internal HDD [52], however, since that drive was specified to be private for John.

In the case of John's private media, it won't be displayed in the LinuxMCE media browser unless you click 'Sources'-->'John'. However you ''can'' see the contents of General Internal HDD [52] (unless you deselect 'Sources'-->'Public' from the media browser). Generic Network Storage [50] would be different, however, since you specified to use the default directory structure for it. LinuxMCE will have created public directories on Generic Network Storage [50] for public video and public audio, as well as for john's video and mary's audio. The media file browser will show only the media that is in the public directories. (The same is true with the Windows Network Neighborhood browser.)

If Generic Network Storage [50] has existing media in the top (root) folder, you won't see it listed anywhere.

It is generally recommended, therefore, that when you add a new (blank) "extra" storage device, you choose to use the default directory structure on it. When you rip media to that device, the media can then be made either public or private, and LinuxMCE will automatically put it in the correct folder (audio, video, etc.).

If you connect an extra storage device that already has media on it, however, and that media isn't already organized in LinuxMCE's default directory structure, it's easiest if you simply 'make it all public' or 'make it all private'. If you were to 'use the default directory structure', you would need to manually move the files from the existing folders into one of the directory folders that LinuxMCE would then create for you.

When you rip files, you have the option of copying them to the Core. If you rip a CD and make it public, it will be stored in public/audio. If you go into Network Neighborhood and add a folder under public/audio, you would essentially be adding a folder on the Core. If you add a folder under public/audio/Generic Network Storage [50], you would be adding it to Generic Network Storage [50].

This concept behind drive/network drive management is not the same as the method to which Linux and Windows users are accustomed. In Windows, for example, each network device shows up separately; they are never grouped together. There is an advantage to the way LinuxMCE manages drives. It's much simpler to add devices when you're a novice and don't understand networking. Further, if you're using an infrared remote control, you can manage drives with a single 'yes' or 'no,' click, which is very convenient. Lastly, all your media content is cataloged and presented in the same structure throughout the system, no matter which Media Director you're using or what room you're in.

In Windows, by comparison, if you connect a USB drive to a Windows PC in the bedroom, you won't see that content in the living room unless you 1) open file explorer, 2) create a new network share for it, 3) go into the living room, and 4) create a new mapped network drive there. (That isn't so easy to do with an infrared remote and without some knowledge of networking.) Further, you wouldn't be able to see the media in any other room in the house unless you were to also create mapped network shares in those rooms as well.

With LinuxMCE, when you connect a USB drive, for example, you can 'make it all public'; the media will be available everywhere. No other typing is required. With LinuxMCE, instead of managing multiple network shares and mapped drives, you can choose the Core's public folders in the Network Neighborhood browser from anywhere in the home, without having to know which storage devices the media is actually on. When you remove a USB drive from a Media Station, that media instantly disappears from the catalog displayed in every room. If you reattach it, it will re-appear.

You can also backup the media securely on the Core. LinuxMCE has built-in [http://en.wikipedia.org/wiki/RAID RAID] 5 (see '''[[LinuxMCE Admin Website]]-->Advanced-->[[RAID]]'''), so its HDD has similar backup capabilities to an [[NAS]].

To change the name of an extra device, go to the '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]''' and under the Core you will see listed the HDDs in the core and any connected NAS devices. Under each Media Station you will see the HDDs in that Media Station. All are given default names. You can change the description, which will also change the folder name. In the above example, changing "USB Drive [51]" to "Tokyo" means the directory public/other/USB Drive [51] would change to public/other/Tokyo.

In the '''[[LinuxMCE Admin Website]]-->Files & Media-->[[Media Files Sync]]''' is listed the files in the system by folder. You can change the cover art and attributes. If a file is shown with a check box, the file exists both on the local disk as well as in LinuxMCE's master catalog. If it has a different icon, then LinuxMCE hasn't finished cataloging the media; just be patient. It should appear with a check mark soon (depending on how much new media was added). Under Files & Media there is also a cover art scan utility that will find cover art, as well as other attributes (actor, genre, etc.) obtained from Amazon.

====Background details====
Here's how it works: [[UpdateMedia]] is a daemon that constantly scans for media files in the /home/public and the /home/user_xxx folder created for each user. Any added media is cataloged in the pluto_media database File table, and attributes and cover art go into the Attribute and Picture tables. Under /home/public and /home/users_xxx is a data subfolder which contains the actual video, audio, pictures folders. (The /home/user_xxx directories themselves contain the system files for each user (like email boxes) as well as the main login for that user (in a "data" subfolder).

Extra devices are mounted as /mnt/device/xxx (where xxx is the device number). The mount point is the same whether it's a local drive or not. For example, USB drive [50] in a Media Station may be mounted as a local device named /mnt/device/50, but is also mounted as a Samba mount on other Media Stations as /mnt/device/50. The Core and the Media Stations all use the same mount names (/mnt/device/).

Within the /home/public/data and /home/user_xxx/data are symlinks to the physical directories specified by /mnt/device/xxx. Since the Core and all Media Stations mount the same /home directory (and all have the same /mnt/device mounts), they will all show the same files. Therefore, if the [[UpdateMedia]] daemon locates the file /home/public/data/audio/Generic Internal Drive [50]/The Beatles/Let it be.mp3, that file will be listed on every Media Station, too.

[[Category: Tutorials]]

Usage Intro

2008-07-12T22:23:48Z

Juanfe: /* Managing your media */

{| align="right"
| __TOC__
|}
LinuxMCE's main concepts are [[Devices]], Commands (aka [[Scenarios]] and Activities), and [[Events]]. An [[Orbiter]] is the device that displays the User Interface. It can be a [[Media Director|Media Station]], web pad, mobile phone, or other remote control device. The Orbiter User Interface is standardized for all Orbiters.

== Devices ==

A device is generally a piece of hardware or software, like the Xine Media Player, a light switch, or a mobile phone. Devices have three functions, abbreviated "DCE" (Data, Commands, Events):

# Retrieve configuration '''data'''
# Perform a '''command''' (turn on, turn off, fast forward, etc.)
# Report certain triggered '''events''' (e.g. 'motion detected', 'playback started', etc.)

== Scenarios ==

"[[Scenarios]]", "Activities", and "Command Groups" are interchangeable terms -- they mean the same thing. A scenario is a group of commands that can be sent to a device (or series of devices). In LinuxMCE, the default Orbiter main menu consists of several scenario categories, grouped by room. These categories are

* Lighting
* Media
* Climate
* Telecom
* Security

(These default categories are arbitrary and are set up at installation.) To perform an action in LinuxMCE, a scenario is chosen from one of these categories (located on the main menu of an Orbiter).

For example, in rooms which have both a TV and lights, LinuxMCE automatically creates a scenario called 'Showtime.' This scenario dims the lights to 10% whenever the TV starts playing. In rooms with a PVR or other TV-enabled device, another scenario is created called 'TV' (in the 'Media' category) to start the TV. Another scenario in the 'Media' category called 'Video' sends a command to the Orbiter to list your video content. Telecom scenarios are created to make phone calls. Security scenarios are created to view cameras and to arm an alarm.

Some [[What_scenarios_are_created_automatically%3F|default scenarios]] are created for you at installation. A fully-functional system can run using only the default scenarios, if you choose. You can also change or remove the default scenarios or add new ones. This is done though the '''[[LinuxMCE Admin Website]]-->Wizard-->[[Scenarios]]''' menu. When creating a scenario, the [[LinuxMCE Admin Website]] will show you the most appropriate wizard, based on the category you pick. If you're adding an activity in the lighting category, for example, the wizard will display a list of the lights in the room and let you pick which ones to turn off. If you're creating a scenario in the security category, it will list the installed cameras and will allow you to select which ones to display.

A scenario can send a command to any device in the system. By default, scenarios in the lighting category show you the room lights, allowing you to select which ones to which to send commands. However, from the '''Wizard-->[[Scenarios]]''' menu for the specific scenario, you can also specify a command to any device in your home. You could make a phone call, for example, even from a scenario in the lighting category.

Certain scenarios are assigned to certain rooms by default. This can be customized, however. When you manually select a room from the Orbiter main menu, the default scenarios for that room are displayed. In general they control devices in that room, but this can also be changed. If your kitchen is near the garage and you want a scenario to 'turn off the garage light', you can assign a scenario to the room 'kitchen' that will do just that. It doesn't matter that the light is in the garage.

For a Media Director, the on-screen Orbiter User Interface appears on the TV screen. It is manipulated by the mouse/keyboard or remote control connected to your Media Director. By default it is set to display the scenarios for the room in which the Media Director is located.

In contrast, a mobile Orbiter (such as a webpad) can be carried throughout the house. It must be able to select the scenarios for multiple rooms. Fortunately, the option to manually select which room you are currently in is available on every Orbiter's main menu.

This can occasionally cause some confusion. Perhaps both the Living Room and the Bedroom have a scenario called 'TV'. You may have a web pad that is in the Bedroom, but you then carry it to the Living Room. You may forget to tell the web pad that it's now in the Living Room (at the bottom of the Orbiter screen it will still say 'Bedroom'). You hit the 'TV' button expecting the Living Room TV to come on, but in fact you're still controlling the Bedroom and the TV comes on there instead. Finally you may realize that you must change your room location to Living Room, and you can then finally control the TV there.

Once you get used to this concept, though, you'll find it very useful. Conveniently, any Orbiter can be set to control any room and choose from the scenarios assigned to that room. No matter which Orbiter you use, the same set of scenarios will be displayed for each specific room. For example, the kitchen scenarios will always be the same, no matter which Orbiter you are using. (The scenarios are assigned by room -- not by Orbiter.) No matter whether you pick up your mobile phone, your web pad, or your remote control, you will always be shown the same list of scenario options for the Living Room.

You have the option of preventing some family members from using certain scenarios. From the [[LinuxMCE Admin Website]], certain scenarios and rooms can be [[Users#Restrict_Access|restricted to certain users]]. Maybe little Suzy's mobile phone Orbiter should be restricted so that she is only able to control her room and the living room, for example. She would only be able to execute the scenarios in those rooms, but not the Master Bedroom. Other possible options include [[Users#Restrict_Access|requiring a pin code]] to access the scenarios for a particular room.

== Events ==

Devices report events, such as 'Playback started' and 'Motion Sensor tripped'. If you want something to happen automatically in LinuxMCE, you create Event Handlers that react to these events. For example, you can create an event handler that listens for the 'Motion Sensor tripped' event from a motion detector and turns on the lights in response. An event handler might listen for the 'Sunrise' event, which could then prompt the sprinklers to come on.

LinuxMCE creates several default event handlers. In rooms in which you have a TV and lights, an event handler is created that listens for the 'Watching Media' event sent by a media player. When the event is detected, the Showtime scenario (which dims the lights) is executed in response. When you start a movie, therefore, the Showtime activity will be executed and the lights will be dimmed. There are other default event handlers that monitor for events like 'Security Breach' and 'Fire Alarm' (from a home security system).

== Controlling an Orbiter ==

To control the system, you use an [[Orbiter]], which is the LinuxMCE term for a remote control. All [[Orbiters]] have the same basic function: to display the scenarios in the room you're in and let you select one. The different Orbiters may [[Selecting_the_Right_UI|display the User Interface slightly differently]], depending on their screen size, but the function and the list of scenarios is always the same. For example, the [[Selecting_the_Right_UI|"UI1" interface]] (which is used on webpads and PDAs) displays the scenarios in horizontal rows. (If there are more than will fit on a row, there will be a "more" button.) A home button is always displayed that takes you to the main menu. On smaller displays, as on mobile phones or desktop phones, there's not enough room to show the scenarios themselves. The top level menu shows only the categories: Lights, Media, Climate, Security and Telecom. Selecting a category displays the scenarios in that category.

[[Selecting_the_Right_UI|"UI2"]] is the [[Selecting_the_Right_UI|preferred User Interface]] for Media Stations. Using a traditional I/R remote is not much different from using any other Media Center PC remote. The menu button brings up the main menu, and you use the ''left/right/up/down/enter'' buttons to navigate it. The ''fast forward/rewind/skip +/skip -'' keys are used for media playback.

If you have a pointing device like a mouse or gyro air mouse, the UI2 interface also supports a unique control architecture that lets you do everything with 3 (programmable) buttons (plus ok and cancel). The 3 buttons are "MEDIA", "MENU", "AMBIANCE".

On a mouse with 3 programmable buttons (such as the [[Using_the_Gyration_Remote_GYR3101US_%28Non-Fiire_Chief%29|gyration]]), these functions correspond to the buttons from left to right. If you are using a traditional 3 button mouse, you can use the F6, F7 and F8 keys on the keyboard for the three programmable functions instead. In both cases, the left mouse button is "ok", and the right mouse button is "cancel/go back".

Mouse button behavior is "absolute" when you press and hold the media/menu/ambiance button and "relative" when you tap and release.

The "absolute" behavior is generally more efficient. For example, in the case of the middle button (F7), "absolute" behavior means the action is executed without having to additionally click "ok". If you press and hold the middle button (F7) while moving your mouse pointer to the option, then let go, that option is executed. If you instead tap and release the menu button ("relative" behavior), you will only highlight the menu option. You must then press ok (the left mouse button) to execute the option.

Categories appear along the bottom of the screen, and the scenarios in each category popup vertically (like a pull-down menu in a PC, except upside down). If the main menu isn't already visible, bring it up by pressing the "start" button on a Windows I/R remote, or the "menu" button on a 3-button mouse. To exit a menu, use the back button on the I/R remote, the cancel button (right mouse button on a 3-button mouse), or the ESC key on a keyboard.

In UI2 the media is always full screen. If you're not playing your own media, the background media (i.e. screensaver images) is gallery art from the Internet (using flickr) or [[Use_my_own_pictures_in_the_Screen_Saver|pictures you select]]. If only the screensaver images are displayed on the Media Station, press the menu/middle/F7 button to bring up the menu. Right click/ESC to get rid of it. (This works even if your own media is playing.)

If you're using UI2's 3-button navigation model, the normal media control options on a traditional remote are replaced with a single button: "media" (left soft button or F6). Press this and move the pointer up and down for your skip functions (''ch+, ch-, skip fwd, skip back''). Move the pointer left and right for speed control (''rewind, fast forward''). The further you move, the faster the media playback changes. If you hold the button down (the left soft button or F6), your movement will be "absolute". Instead of the traditional "jog shuttle-type" control, movement to the right skips to the end of your media, and movement to the left skips to the beginning. Once you get used to it, you will find that navigating media is orders of magnitude faster and easier with this model than with a traditional remote. You can find a spot in a 2 hour movie in only a couple seconds with a click of a single button (compared to a slew of button clicks required using a traditional remote).

Also, in UI2 you can press the "ambiance" button (right soft button or F8). Move up/down to adjust the lights, and left/right to adjust the volume. As with the media playback, if you hold the F8/right soft button down while you move left and right, your volume control is in "absolute" mode (not "relative"). Moving hard right turns up the volume full blast; hard left is mute. This requires you have a TV or receiver that is serial-controlled, however. LinuxMCE can then directly and instantly set the volume position in sync with your hand movements. (Few TVs and receivers have this feature, unfortunately.)

There are other media control functions besides the most commonly used ''fast fwd/rewind/skip up/skip down''. You can, for example, choose 'subtitles' while watching a DVD, 'guide' while watching TV, and 'random' while listening to an audio CD. In the UI2 3 button model, these functions appear on the main menu (on the left-most pad, entitled 'now playing') and changes according to the type of media you're playing. Press the menu button (middle button/F7) to select these options.

This 3 button model is a new concept and very different from traditional navigation. Most people find it much faster once they become accustomed to it.

==Reload Router & Regen Orbiters==

While using LinuxMCE you'll see sometimes a message asking if you want to [[Quick reload router|reload the router]], or if you want to [[Orbiter Generator|regenerate the Orbiter UIs]] (User Interfaces). In general, these options refresh the LinuxMCE databases so that changes to the system can be recognized.

===Reload Router===
All devices in LinuxMCE obtain their configuration information from the [[DCERouter]], which is the central piece of software on the Core. All devices request a list of the other devices in the home from the router, so they can respond to them appropriately. (For example, an IP camera device might turn on the lights in the room whenever you're viewing the camera. To do so, the IP camera needs to know what lights are in the room.) Typically a device requests this information only when it's starting up. When you connect additional plug and play devices to the system, these new devices generally will work immediately, but their functionality may not be fully enabled within the LinuxMCE system until the DCE router is reloaded. When the router reloads, it signals all devices on the system to simultaneously reload and re-request the system data. Each existing device can then work with each new device. This process is known as a 'reload'. It generally takes about 10 seconds. Every time you add or remove devices, or change a device's configuration, you may be asked to do a reload. If you're going to add more devices or make more device changes, you can do the reload once you're done. If you're in the middle of watching a movie or TV, you can postpone the reload, since media players generally stop playing during reloads. Phone calls aren't affected, though, and TV shows being recorded by MythTV in the background are also unaffected.

===Regen the Orbiter===
LinuxMCE's [[Selecting_the_Right_UI|Orbiter User Interfaces]] are all "pre-rendered" in order to be more efficient. The User Interface source images are all very high resolution, but need to be resized to accommodate the resolution of each Orbiter screen. The Core server has a list of the Orbiters used by your system, and will generate the appropriate User Interface screen for each Orbiter. It will do this each time you request a "regen". If you have five different types of Orbiters (each with a different type of screen), then five different images will be generated during each regen.

These User Interface screen images are stored in the Core. The appropriate UI image is sent to an Orbiter whenever it is activated. For many low-power devices (like mobile phones or desktop phones) there just isn't the processing power to do scaling and rendering of a User Interface screen on the fly. They need to be pre-rendered (with text pre-embedded in the images) to be efficient.

Adding new scenarios may result in the creation of new buttons for the User Interface, or changes to the text on existing buttons. Perhaps an entirely new screen will be created.

Until the User Interface images are regenerated, though, you won't be able to see these new buttons (or screens) on your Orbiter. During the regen, new User Interface images for each type of Orbiter is generated by the Core. This can take about 2-5 minutes, depending on how many Orbiter types you have in your system.

You needn't do a regen every time you add a scenario. You can wait until you have finished adding all the scenarios. Furthermore, you can also regen only the Orbiter you are currently using by doing a "Quick regen". This allows you to see the new User Interface (following the addition of new scenarios) without having to do a full regen for all the Orbiters. Once you have finished adding scenarios, then you can do a full regen.

This regen process can be a bit annoying, but is necessary. In future editions of LinuxMCE, it is planned to allow Media Directors, which have a lot more processing power, to render their on-screen Orbiter User Interfaces on the fly (so you don't have to do a regen each time you add or remove a scenario).

You can do a [[Orbiter Generator#Running OrbiterGen (performing a "regen")|full Orbiter regen or a Quick regen]] at any time by using buttons on the Core's LinuxMCE [[Launch Manager]].

== Managing your media ==

LinuxMCE is always scanning for network shares, on Network-Attached Storage (NAS) devices and other Hard Disk Drives (HDDs) of PCs connected to the system (including Windows PCs). Universal Serial Bus (USB) drives are also detected. Every time a LinuxMCE finds a network share, you will be asked if you would like to use it. Whenever you reply "Yes", the file share can be used by any Media Director on the system. The file share is scanned for media, such as audio, video and photos,and any that are found \are then cataloged in the Core's central database. For example, when you plug in a USB drive on a Media Station in the living room and tell LinuxMCE to use it, the media on the drive will be available to Media Directors in other rooms.

At the moment there is no way to restrict your media for 'local use only'; all Media Stations in the LinuxMCE system share the media catalog stored on the Core. (This is a limitation that will be addressed in the near future. Sometimes it is desirable to attach a USB drive in the master bedroom and not allow it to be shared, for example. ''Note: However, see [[folder lock|this article that describes a method to address this problem]].'')

Storage devices (NAS, USB drives, extra HDDs on the Core or Media Directors) are referred to as "Extra Drives". When an extra drive is added, it is listed in the device tree in '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]'''. Under 'Core' you'll see a device listed for each HDD in the Core, as well as for each NAS device. Under each Media Station will be listed the HDDs in that Media Station. By clicking on the device you can change the device's properties, such as the mount username/password. Each NAS device, and each file share on another PC, will show as a device listed under the Core; each is considered a child of the Core.

LinuxMCE creates a top level folder for 'public' media. This folder can be used by every user in the system. A 'private' media folder is also created for each user. Within each of those folders are sub-folders, labeled 'audio', 'video', 'pictures', 'data' and 'other'. Within each of those will also be sub-folders for the extra storage devices (NAS, USB, extra internal drives, etc). When you attach an extra storage device, you can specify whether the default directory structure should be used for it. Alternatively, you can specify 'just make it public' or 'make it private'.

Here's an example. Let's say you have 2 users: john and mary. You connect 3 storage devices:
# a NAS, for which you specify 'use default directory structure'. It is named 'Generic Network Storage [50]'
# a USB drive for which you specify 'make it all public'. It is named 'USB Drive [51]'
# a SATA drive for which you choose 'make it private for john'. It is named 'General Internal HDD [52]

Now let's say you're running Windows. Go to Network Neighborhood and find the LinuxMCE Core server. The directory tree ought to look like this:
<pre>
public
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
USB Drive [51]
john
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
General Internal HDD [52]
mary
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
</pre>
Whether you put your media under video, audio, pictures, data or other is unimportant. It will be scanned by LinuxMCE anyway. The contents of "General Internal HDD [52]" will be displayed in the folder john/other/General Internal HDD [52]. The contents of USB Drive [51] will be displayed in the folder public/other/USB Drive [51]. When John browses the contents in Network Neighborhood, he will be asked for his username and password. He can then access the content in both the public folder as well as the "john" folders (including General Internal HDD [52]). When Mary browses the contents with her username and password, she will see both the public and "mary" folders. She will not be able to see anything on General Internal HDD [52], however, since that drive was specified to be private for John.

In the case of John's private media, it won't be displayed in the LinuxMCE media browser unless you click 'Sources'-->'John'. However you ''can'' see the contents of General Internal HDD [52] (unless you deselect 'Sources'-->'Public' from the media browser). Generic Network Storage [50] would be different, however, since you specified to use the default directory structure for it. LinuxMCE will have created public directories on Generic Network Storage [50] for public video and public audio, as well as for john's video and mary's audio. The media file browser will show only the media that is in the public directories. (The same is true with the Windows Network Neighborhood browser.)

If Generic Network Storage [50] has existing media in the top (root) folder, you won't see it listed anywhere.

It is generally recommended, therefore, that when you add a new (blank) "extra" storage device, you choose to use the default directory structure on it. When you rip media to that device, the media can then be made either public or private, and LinuxMCE will automatically put it in the correct folder (audio, video, etc.).

If you connect an extra storage device that already has media on it, however, and that media isn't already organized in LinuxMCE's default directory structure, it's easiest if you simply 'make it all public' or 'make it all private'. If you were to 'use the default directory structure', you would need to manually move the files from the existing folders into one of the directory folders that LinuxMCE would then create for you.

When you rip files, you have the option of copying them to the Core. If you rip a CD and make it public, it will be stored in public/audio. If you go into Network Neighborhood and add a folder under public/audio, you would essentially be adding a folder on the Core. If you add a folder under public/audio/Generic Network Storage [50], you would be adding it to Generic Network Storage [50].

This concept behind drive/network drive management is not the same as the method to which Linux and Windows users are accustomed. In Windows, for example, each network device shows up separately; they are never grouped together. There is an advantage to the way LinuxMCE manages drives. It's much simpler to add devices when you're a novice and don't understand networking. Further, if you're using an infrared remote control, you can manage drives with a single 'yes' or 'no,' click, which is very convenient. Lastly, all your media content is cataloged and presented in the same structure throughout the system, no matter which Media Director you're using or what room you're in.

In Windows, by comparison, if you connect a USB drive to a Windows PC in the bedroom, you won't see that content in the living room unless you 1) open file explorer, 2) create a new network share for it, 3) go into the living room, and 4) create a new mapped network drive there. (That isn't so easy to do with an infrared remote and without some knowledge of networking.) Further, you wouldn't be able to see the media in any other room in the house unless you were to also create mapped network shares in those rooms as well.

With LinuxMCE, when you connect a USB drive, for example, you can 'make it all public'; the media will be available everywhere. No other typing is required. With LinuxMCE, instead of managing multiple network shares and mapped drives, you can choose the Core's public folders in the Network Neighborhood browser from anywhere in the home, without having to know which storage devices the media is actually on. When you remove a USB drive from a Media Station, that media instantly disappears from the catalog displayed in every room. If you reattach it, it will re-appear.

You can also backup the media securely on the Core. LinuxMCE has built-in [http://en.wikipedia.org/wiki/RAID RAID] 5 (see '''[[LinuxMCE Admin Website]]-->Advanced-->[[RAID]]'''), so its HDD has similar backup capabilities to an [[NAS]].

To change the name of an extra device, go to the '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]''' and under the Core you will see listed the HDDs in the core and any connected NAS devices. Under each Media Station you will see the HDDs in that Media Station. All are given default names. You can change the description, which will also change the folder name. In the above example, changing "USB Drive [51]" to "Tokyo" means the directory public/other/USB Drive [51] would change to public/other/Tokyo.

In the '''[[LinuxMCE Admin Website]]-->Files & Media-->[[Media Files Sync]]''' is listed the files in the system by folder. You can change the cover art and attributes. If a file is shown with a check box, the file exists both on the local disk as well as in LinuxMCE's master catalog. If it has a different icon, then LinuxMCE hasn't finished cataloging the media; just be patient. It should appear with a check mark soon (depending on how much new media was added). Under Files & Media there is also a cover art scan utility that will find cover art, as well as other attributes (actor, genre, etc.) obtained from Amazon.

====Background details====
Here's how it works: [[UpdateMedia]] is a daemon that constantly scans for media files in the /home/public and the /home/user_xxx folder created for each user. Any added media is cataloged in the pluto_media database File table, and attributes and cover art go into the Attribute and Picture tables. Under /home/public and /home/users_xxx is a data subfolder which contains the actual video, audio, pictures folders. (The /home/user_xxx directories themselves contain the system files for each user (like email boxes) as well as the main login for that user (in a "data" subfolder).

Extra devices are mounted as /mnt/device/xxx (where xxx is the device number). The mount point is the same whether it's a local drive or not. For example, USB drive [50] in a Media Station may be mounted as a local device named /mnt/device/50, but is also mounted as a Samba mount on other Media Stations as /mnt/device/50. The Core and the Media Stations all use the same mount names (/mnt/device/).

Within the /home/public/data and /home/user_xxx/data are symlinks to the physical directories specified by /mnt/device/xxx. Since the Core and all Media Stations mount the same /home directory (and all have the same /mnt/device mounts), they will all show the same files. Therefore, if the [[UpdateMedia]] daemon locates the file /home/public/data/audio/Generic Internal Drive [50]/The Beatles/Let it be.mp3, that file will be listed on every Media Station, too.

[[Category: Tutorials]]

Usage Intro

2008-07-12T22:21:56Z

Juanfe: /* Managing your media */

{| align="right"
| __TOC__
|}
LinuxMCE's main concepts are [[Devices]], Commands (aka [[Scenarios]] and Activities), and [[Events]]. An [[Orbiter]] is the device that displays the User Interface. It can be a [[Media Director|Media Station]], web pad, mobile phone, or other remote control device. The Orbiter User Interface is standardized for all Orbiters.

== Devices ==

A device is generally a piece of hardware or software, like the Xine Media Player, a light switch, or a mobile phone. Devices have three functions, abbreviated "DCE" (Data, Commands, Events):

# Retrieve configuration '''data'''
# Perform a '''command''' (turn on, turn off, fast forward, etc.)
# Report certain triggered '''events''' (e.g. 'motion detected', 'playback started', etc.)

== Scenarios ==

"[[Scenarios]]", "Activities", and "Command Groups" are interchangeable terms -- they mean the same thing. A scenario is a group of commands that can be sent to a device (or series of devices). In LinuxMCE, the default Orbiter main menu consists of several scenario categories, grouped by room. These categories are

* Lighting
* Media
* Climate
* Telecom
* Security

(These default categories are arbitrary and are set up at installation.) To perform an action in LinuxMCE, a scenario is chosen from one of these categories (located on the main menu of an Orbiter).

For example, in rooms which have both a TV and lights, LinuxMCE automatically creates a scenario called 'Showtime.' This scenario dims the lights to 10% whenever the TV starts playing. In rooms with a PVR or other TV-enabled device, another scenario is created called 'TV' (in the 'Media' category) to start the TV. Another scenario in the 'Media' category called 'Video' sends a command to the Orbiter to list your video content. Telecom scenarios are created to make phone calls. Security scenarios are created to view cameras and to arm an alarm.

Some [[What_scenarios_are_created_automatically%3F|default scenarios]] are created for you at installation. A fully-functional system can run using only the default scenarios, if you choose. You can also change or remove the default scenarios or add new ones. This is done though the '''[[LinuxMCE Admin Website]]-->Wizard-->[[Scenarios]]''' menu. When creating a scenario, the [[LinuxMCE Admin Website]] will show you the most appropriate wizard, based on the category you pick. If you're adding an activity in the lighting category, for example, the wizard will display a list of the lights in the room and let you pick which ones to turn off. If you're creating a scenario in the security category, it will list the installed cameras and will allow you to select which ones to display.

A scenario can send a command to any device in the system. By default, scenarios in the lighting category show you the room lights, allowing you to select which ones to which to send commands. However, from the '''Wizard-->[[Scenarios]]''' menu for the specific scenario, you can also specify a command to any device in your home. You could make a phone call, for example, even from a scenario in the lighting category.

Certain scenarios are assigned to certain rooms by default. This can be customized, however. When you manually select a room from the Orbiter main menu, the default scenarios for that room are displayed. In general they control devices in that room, but this can also be changed. If your kitchen is near the garage and you want a scenario to 'turn off the garage light', you can assign a scenario to the room 'kitchen' that will do just that. It doesn't matter that the light is in the garage.

For a Media Director, the on-screen Orbiter User Interface appears on the TV screen. It is manipulated by the mouse/keyboard or remote control connected to your Media Director. By default it is set to display the scenarios for the room in which the Media Director is located.

In contrast, a mobile Orbiter (such as a webpad) can be carried throughout the house. It must be able to select the scenarios for multiple rooms. Fortunately, the option to manually select which room you are currently in is available on every Orbiter's main menu.

This can occasionally cause some confusion. Perhaps both the Living Room and the Bedroom have a scenario called 'TV'. You may have a web pad that is in the Bedroom, but you then carry it to the Living Room. You may forget to tell the web pad that it's now in the Living Room (at the bottom of the Orbiter screen it will still say 'Bedroom'). You hit the 'TV' button expecting the Living Room TV to come on, but in fact you're still controlling the Bedroom and the TV comes on there instead. Finally you may realize that you must change your room location to Living Room, and you can then finally control the TV there.

Once you get used to this concept, though, you'll find it very useful. Conveniently, any Orbiter can be set to control any room and choose from the scenarios assigned to that room. No matter which Orbiter you use, the same set of scenarios will be displayed for each specific room. For example, the kitchen scenarios will always be the same, no matter which Orbiter you are using. (The scenarios are assigned by room -- not by Orbiter.) No matter whether you pick up your mobile phone, your web pad, or your remote control, you will always be shown the same list of scenario options for the Living Room.

You have the option of preventing some family members from using certain scenarios. From the [[LinuxMCE Admin Website]], certain scenarios and rooms can be [[Users#Restrict_Access|restricted to certain users]]. Maybe little Suzy's mobile phone Orbiter should be restricted so that she is only able to control her room and the living room, for example. She would only be able to execute the scenarios in those rooms, but not the Master Bedroom. Other possible options include [[Users#Restrict_Access|requiring a pin code]] to access the scenarios for a particular room.

== Events ==

Devices report events, such as 'Playback started' and 'Motion Sensor tripped'. If you want something to happen automatically in LinuxMCE, you create Event Handlers that react to these events. For example, you can create an event handler that listens for the 'Motion Sensor tripped' event from a motion detector and turns on the lights in response. An event handler might listen for the 'Sunrise' event, which could then prompt the sprinklers to come on.

LinuxMCE creates several default event handlers. In rooms in which you have a TV and lights, an event handler is created that listens for the 'Watching Media' event sent by a media player. When the event is detected, the Showtime scenario (which dims the lights) is executed in response. When you start a movie, therefore, the Showtime activity will be executed and the lights will be dimmed. There are other default event handlers that monitor for events like 'Security Breach' and 'Fire Alarm' (from a home security system).

== Controlling an Orbiter ==

To control the system, you use an [[Orbiter]], which is the LinuxMCE term for a remote control. All [[Orbiters]] have the same basic function: to display the scenarios in the room you're in and let you select one. The different Orbiters may [[Selecting_the_Right_UI|display the User Interface slightly differently]], depending on their screen size, but the function and the list of scenarios is always the same. For example, the [[Selecting_the_Right_UI|"UI1" interface]] (which is used on webpads and PDAs) displays the scenarios in horizontal rows. (If there are more than will fit on a row, there will be a "more" button.) A home button is always displayed that takes you to the main menu. On smaller displays, as on mobile phones or desktop phones, there's not enough room to show the scenarios themselves. The top level menu shows only the categories: Lights, Media, Climate, Security and Telecom. Selecting a category displays the scenarios in that category.

[[Selecting_the_Right_UI|"UI2"]] is the [[Selecting_the_Right_UI|preferred User Interface]] for Media Stations. Using a traditional I/R remote is not much different from using any other Media Center PC remote. The menu button brings up the main menu, and you use the ''left/right/up/down/enter'' buttons to navigate it. The ''fast forward/rewind/skip +/skip -'' keys are used for media playback.

If you have a pointing device like a mouse or gyro air mouse, the UI2 interface also supports a unique control architecture that lets you do everything with 3 (programmable) buttons (plus ok and cancel). The 3 buttons are "MEDIA", "MENU", "AMBIANCE".

On a mouse with 3 programmable buttons (such as the [[Using_the_Gyration_Remote_GYR3101US_%28Non-Fiire_Chief%29|gyration]]), these functions correspond to the buttons from left to right. If you are using a traditional 3 button mouse, you can use the F6, F7 and F8 keys on the keyboard for the three programmable functions instead. In both cases, the left mouse button is "ok", and the right mouse button is "cancel/go back".

Mouse button behavior is "absolute" when you press and hold the media/menu/ambiance button and "relative" when you tap and release.

The "absolute" behavior is generally more efficient. For example, in the case of the middle button (F7), "absolute" behavior means the action is executed without having to additionally click "ok". If you press and hold the middle button (F7) while moving your mouse pointer to the option, then let go, that option is executed. If you instead tap and release the menu button ("relative" behavior), you will only highlight the menu option. You must then press ok (the left mouse button) to execute the option.

Categories appear along the bottom of the screen, and the scenarios in each category popup vertically (like a pull-down menu in a PC, except upside down). If the main menu isn't already visible, bring it up by pressing the "start" button on a Windows I/R remote, or the "menu" button on a 3-button mouse. To exit a menu, use the back button on the I/R remote, the cancel button (right mouse button on a 3-button mouse), or the ESC key on a keyboard.

In UI2 the media is always full screen. If you're not playing your own media, the background media (i.e. screensaver images) is gallery art from the Internet (using flickr) or [[Use_my_own_pictures_in_the_Screen_Saver|pictures you select]]. If only the screensaver images are displayed on the Media Station, press the menu/middle/F7 button to bring up the menu. Right click/ESC to get rid of it. (This works even if your own media is playing.)

If you're using UI2's 3-button navigation model, the normal media control options on a traditional remote are replaced with a single button: "media" (left soft button or F6). Press this and move the pointer up and down for your skip functions (''ch+, ch-, skip fwd, skip back''). Move the pointer left and right for speed control (''rewind, fast forward''). The further you move, the faster the media playback changes. If you hold the button down (the left soft button or F6), your movement will be "absolute". Instead of the traditional "jog shuttle-type" control, movement to the right skips to the end of your media, and movement to the left skips to the beginning. Once you get used to it, you will find that navigating media is orders of magnitude faster and easier with this model than with a traditional remote. You can find a spot in a 2 hour movie in only a couple seconds with a click of a single button (compared to a slew of button clicks required using a traditional remote).

Also, in UI2 you can press the "ambiance" button (right soft button or F8). Move up/down to adjust the lights, and left/right to adjust the volume. As with the media playback, if you hold the F8/right soft button down while you move left and right, your volume control is in "absolute" mode (not "relative"). Moving hard right turns up the volume full blast; hard left is mute. This requires you have a TV or receiver that is serial-controlled, however. LinuxMCE can then directly and instantly set the volume position in sync with your hand movements. (Few TVs and receivers have this feature, unfortunately.)

There are other media control functions besides the most commonly used ''fast fwd/rewind/skip up/skip down''. You can, for example, choose 'subtitles' while watching a DVD, 'guide' while watching TV, and 'random' while listening to an audio CD. In the UI2 3 button model, these functions appear on the main menu (on the left-most pad, entitled 'now playing') and changes according to the type of media you're playing. Press the menu button (middle button/F7) to select these options.

This 3 button model is a new concept and very different from traditional navigation. Most people find it much faster once they become accustomed to it.

==Reload Router & Regen Orbiters==

While using LinuxMCE you'll see sometimes a message asking if you want to [[Quick reload router|reload the router]], or if you want to [[Orbiter Generator|regenerate the Orbiter UIs]] (User Interfaces). In general, these options refresh the LinuxMCE databases so that changes to the system can be recognized.

===Reload Router===
All devices in LinuxMCE obtain their configuration information from the [[DCERouter]], which is the central piece of software on the Core. All devices request a list of the other devices in the home from the router, so they can respond to them appropriately. (For example, an IP camera device might turn on the lights in the room whenever you're viewing the camera. To do so, the IP camera needs to know what lights are in the room.) Typically a device requests this information only when it's starting up. When you connect additional plug and play devices to the system, these new devices generally will work immediately, but their functionality may not be fully enabled within the LinuxMCE system until the DCE router is reloaded. When the router reloads, it signals all devices on the system to simultaneously reload and re-request the system data. Each existing device can then work with each new device. This process is known as a 'reload'. It generally takes about 10 seconds. Every time you add or remove devices, or change a device's configuration, you may be asked to do a reload. If you're going to add more devices or make more device changes, you can do the reload once you're done. If you're in the middle of watching a movie or TV, you can postpone the reload, since media players generally stop playing during reloads. Phone calls aren't affected, though, and TV shows being recorded by MythTV in the background are also unaffected.

===Regen the Orbiter===
LinuxMCE's [[Selecting_the_Right_UI|Orbiter User Interfaces]] are all "pre-rendered" in order to be more efficient. The User Interface source images are all very high resolution, but need to be resized to accommodate the resolution of each Orbiter screen. The Core server has a list of the Orbiters used by your system, and will generate the appropriate User Interface screen for each Orbiter. It will do this each time you request a "regen". If you have five different types of Orbiters (each with a different type of screen), then five different images will be generated during each regen.

These User Interface screen images are stored in the Core. The appropriate UI image is sent to an Orbiter whenever it is activated. For many low-power devices (like mobile phones or desktop phones) there just isn't the processing power to do scaling and rendering of a User Interface screen on the fly. They need to be pre-rendered (with text pre-embedded in the images) to be efficient.

Adding new scenarios may result in the creation of new buttons for the User Interface, or changes to the text on existing buttons. Perhaps an entirely new screen will be created.

Until the User Interface images are regenerated, though, you won't be able to see these new buttons (or screens) on your Orbiter. During the regen, new User Interface images for each type of Orbiter is generated by the Core. This can take about 2-5 minutes, depending on how many Orbiter types you have in your system.

You needn't do a regen every time you add a scenario. You can wait until you have finished adding all the scenarios. Furthermore, you can also regen only the Orbiter you are currently using by doing a "Quick regen". This allows you to see the new User Interface (following the addition of new scenarios) without having to do a full regen for all the Orbiters. Once you have finished adding scenarios, then you can do a full regen.

This regen process can be a bit annoying, but is necessary. In future editions of LinuxMCE, it is planned to allow Media Directors, which have a lot more processing power, to render their on-screen Orbiter User Interfaces on the fly (so you don't have to do a regen each time you add or remove a scenario).

You can do a [[Orbiter Generator#Running OrbiterGen (performing a "regen")|full Orbiter regen or a Quick regen]] at any time by using buttons on the Core's LinuxMCE [[Launch Manager]].

== Managing your media ==

LinuxMCE is always scanning for network shares, on Network-Attached Storage (NAS) devices and other Hard Disk Drives (HDDs) of PCs connected to the system (including Windows PCs). Universal Serial Bus (USB) drives are also detected. You will be asked if you "if you want to use it" every time a network share is found. Whenever you reply "Yes", the file share can be used by any Media Director on the system. The file share is scanned for media (audio, video and photos) which is then cataloged in the Core's central database. For example, when you plug in a USB drive on a Media Station in the living room and say 'yes' to use it, the media on the drive will be available to Media Directors in other rooms.

At the moment there is no way to restrict your media for 'local use only'; all Media Stations in the LinuxMCE system share the media catalog stored on the Core. (This is a limitation that will be addressed in the near future. Sometimes it is desirable to attach a USB drive in the master bedroom and not allow it to be shared, for example. ''Note: However, see [[folder lock|this article that describes a method to address this problem]].'')

Storage devices (NAS, USB drives, extra HDDs on the Core or Media Directors) are referred to as "Extra Drives". When an extra drive is added, it is listed in the device tree in '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]'''. Under 'Core' you'll see a device listed for each HDD in the Core, as well as for each NAS device. Under each Media Station will be listed the HDDs in that Media Station. By clicking on the device you can change the device's properties, such as the mount username/password. Each NAS device, and each file share on another PC, will show as a device listed under the Core; each is considered a child of the Core.

LinuxMCE creates a top level folder for 'public' media. This folder can be used by every user in the system. A 'private' media folder is also created for each user. Within each of those folders are sub-folders, labeled 'audio', 'video', 'pictures', 'data' and 'other'. Within each of those will also be sub-folders for the extra storage devices (NAS, USB, extra internal drives, etc). When you attach an extra storage device, you can specify whether the default directory structure should be used for it. Alternatively, you can specify 'just make it public' or 'make it private'.

Here's an example. Let's say you have 2 users: john and mary. You connect 3 storage devices:
# a NAS, for which you specify 'use default directory structure'. It is named 'Generic Network Storage [50]'
# a USB drive for which you specify 'make it all public'. It is named 'USB Drive [51]'
# a SATA drive for which you choose 'make it private for john'. It is named 'General Internal HDD [52]

Now let's say you're running Windows. Go to Network Neighborhood and find the LinuxMCE Core server. The directory tree ought to look like this:
<pre>
public
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
USB Drive [51]
john
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
General Internal HDD [52]
mary
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
</pre>
Whether you put your media under video, audio, pictures, data or other is unimportant. It will be scanned by LinuxMCE anyway. The contents of "General Internal HDD [52]" will be displayed in the folder john/other/General Internal HDD [52]. The contents of USB Drive [51] will be displayed in the folder public/other/USB Drive [51]. When John browses the contents in Network Neighborhood, he will be asked for his username and password. He can then access the content in both the public folder as well as the "john" folders (including General Internal HDD [52]). When Mary browses the contents with her username and password, she will see both the public and "mary" folders. She will not be able to see anything on General Internal HDD [52], however, since that drive was specified to be private for John.

In the case of John's private media, it won't be displayed in the LinuxMCE media browser unless you click 'Sources'-->'John'. However you ''can'' see the contents of General Internal HDD [52] (unless you deselect 'Sources'-->'Public' from the media browser). Generic Network Storage [50] would be different, however, since you specified to use the default directory structure for it. LinuxMCE will have created public directories on Generic Network Storage [50] for public video and public audio, as well as for john's video and mary's audio. The media file browser will show only the media that is in the public directories. (The same is true with the Windows Network Neighborhood browser.)

If Generic Network Storage [50] has existing media in the top (root) folder, you won't see it listed anywhere.

It is generally recommended, therefore, that when you add a new (blank) "extra" storage device, you choose to use the default directory structure on it. When you rip media to that device, the media can then be made either public or private, and LinuxMCE will automatically put it in the correct folder (audio, video, etc.).

If you connect an extra storage device that already has media on it, however, and that media isn't already organized in LinuxMCE's default directory structure, it's easiest if you simply 'make it all public' or 'make it all private'. If you were to 'use the default directory structure', you would need to manually move the files from the existing folders into one of the directory folders that LinuxMCE would then create for you.

When you rip files, you have the option of copying them to the Core. If you rip a CD and make it public, it will be stored in public/audio. If you go into Network Neighborhood and add a folder under public/audio, you would essentially be adding a folder on the Core. If you add a folder under public/audio/Generic Network Storage [50], you would be adding it to Generic Network Storage [50].

This concept behind drive/network drive management is not the same as the method to which Linux and Windows users are accustomed. In Windows, for example, each network device shows up separately; they are never grouped together. There is an advantage to the way LinuxMCE manages drives. It's much simpler to add devices when you're a novice and don't understand networking. Further, if you're using an infrared remote control, you can manage drives with a single 'yes' or 'no,' click, which is very convenient. Lastly, all your media content is cataloged and presented in the same structure throughout the system, no matter which Media Director you're using or what room you're in.

In Windows, by comparison, if you connect a USB drive to a Windows PC in the bedroom, you won't see that content in the living room unless you 1) open file explorer, 2) create a new network share for it, 3) go into the living room, and 4) create a new mapped network drive there. (That isn't so easy to do with an infrared remote and without some knowledge of networking.) Further, you wouldn't be able to see the media in any other room in the house unless you were to also create mapped network shares in those rooms as well.

With LinuxMCE, when you connect a USB drive, for example, you can 'make it all public'; the media will be available everywhere. No other typing is required. With LinuxMCE, instead of managing multiple network shares and mapped drives, you can choose the Core's public folders in the Network Neighborhood browser from anywhere in the home, without having to know which storage devices the media is actually on. When you remove a USB drive from a Media Station, that media instantly disappears from the catalog displayed in every room. If you reattach it, it will re-appear.

You can also backup the media securely on the Core. LinuxMCE has built-in [http://en.wikipedia.org/wiki/RAID RAID] 5 (see '''[[LinuxMCE Admin Website]]-->Advanced-->[[RAID]]'''), so its HDD has similar backup capabilities to an [[NAS]].

To change the name of an extra device, go to the '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]''' and under the Core you will see listed the HDDs in the core and any connected NAS devices. Under each Media Station you will see the HDDs in that Media Station. All are given default names. You can change the description, which will also change the folder name. In the above example, changing "USB Drive [51]" to "Tokyo" means the directory public/other/USB Drive [51] would change to public/other/Tokyo.

In the '''[[LinuxMCE Admin Website]]-->Files & Media-->[[Media Files Sync]]''' is listed the files in the system by folder. You can change the cover art and attributes. If a file is shown with a check box, the file exists both on the local disk as well as in LinuxMCE's master catalog. If it has a different icon, then LinuxMCE hasn't finished cataloging the media; just be patient. It should appear with a check mark soon (depending on how much new media was added). Under Files & Media there is also a cover art scan utility that will find cover art, as well as other attributes (actor, genre, etc.) obtained from Amazon.

====Background details====
Here's how it works: [[UpdateMedia]] is a daemon that constantly scans for media files in the /home/public and the /home/user_xxx folder created for each user. Any added media is cataloged in the pluto_media database File table, and attributes and cover art go into the Attribute and Picture tables. Under /home/public and /home/users_xxx is a data subfolder which contains the actual video, audio, pictures folders. (The /home/user_xxx directories themselves contain the system files for each user (like email boxes) as well as the main login for that user (in a "data" subfolder).

Extra devices are mounted as /mnt/device/xxx (where xxx is the device number). The mount point is the same whether it's a local drive or not. For example, USB drive [50] in a Media Station may be mounted as a local device named /mnt/device/50, but is also mounted as a Samba mount on other Media Stations as /mnt/device/50. The Core and the Media Stations all use the same mount names (/mnt/device/).

Within the /home/public/data and /home/user_xxx/data are symlinks to the physical directories specified by /mnt/device/xxx. Since the Core and all Media Stations mount the same /home directory (and all have the same /mnt/device mounts), they will all show the same files. Therefore, if the [[UpdateMedia]] daemon locates the file /home/public/data/audio/Generic Internal Drive [50]/The Beatles/Let it be.mp3, that file will be listed on every Media Station, too.

[[Category: Tutorials]]

Usage Intro

2008-07-12T22:09:44Z

Juanfe:

{| align="right"
| __TOC__
|}
LinuxMCE's main concepts are [[Devices]], Commands (aka [[Scenarios]] and Activities), and [[Events]]. An [[Orbiter]] is the device that displays the User Interface. It can be a [[Media Director|Media Station]], web pad, mobile phone, or other remote control device. The Orbiter User Interface is standardized for all Orbiters.

== Devices ==

A device is generally a piece of hardware or software, like the Xine Media Player, a light switch, or a mobile phone. Devices have three functions, abbreviated "DCE" (Data, Commands, Events):

# Retrieve configuration '''data'''
# Perform a '''command''' (turn on, turn off, fast forward, etc.)
# Report certain triggered '''events''' (e.g. 'motion detected', 'playback started', etc.)

== Scenarios ==

"[[Scenarios]]", "Activities", and "Command Groups" are interchangeable terms -- they mean the same thing. A scenario is a group of commands that can be sent to a device (or series of devices). In LinuxMCE, the default Orbiter main menu consists of several scenario categories, grouped by room. These categories are

* Lighting
* Media
* Climate
* Telecom
* Security

(These default categories are arbitrary and are set up at installation.) To perform an action in LinuxMCE, a scenario is chosen from one of these categories (located on the main menu of an Orbiter).

For example, in rooms which have both a TV and lights, LinuxMCE automatically creates a scenario called 'Showtime.' This scenario dims the lights to 10% whenever the TV starts playing. In rooms with a PVR or other TV-enabled device, another scenario is created called 'TV' (in the 'Media' category) to start the TV. Another scenario in the 'Media' category called 'Video' sends a command to the Orbiter to list your video content. Telecom scenarios are created to make phone calls. Security scenarios are created to view cameras and to arm an alarm.

Some [[What_scenarios_are_created_automatically%3F|default scenarios]] are created for you at installation. A fully-functional system can run using only the default scenarios, if you choose. You can also change or remove the default scenarios or add new ones. This is done though the '''[[LinuxMCE Admin Website]]-->Wizard-->[[Scenarios]]''' menu. When creating a scenario, the [[LinuxMCE Admin Website]] will show you the most appropriate wizard, based on the category you pick. If you're adding an activity in the lighting category, for example, the wizard will display a list of the lights in the room and let you pick which ones to turn off. If you're creating a scenario in the security category, it will list the installed cameras and will allow you to select which ones to display.

A scenario can send a command to any device in the system. By default, scenarios in the lighting category show you the room lights, allowing you to select which ones to which to send commands. However, from the '''Wizard-->[[Scenarios]]''' menu for the specific scenario, you can also specify a command to any device in your home. You could make a phone call, for example, even from a scenario in the lighting category.

Certain scenarios are assigned to certain rooms by default. This can be customized, however. When you manually select a room from the Orbiter main menu, the default scenarios for that room are displayed. In general they control devices in that room, but this can also be changed. If your kitchen is near the garage and you want a scenario to 'turn off the garage light', you can assign a scenario to the room 'kitchen' that will do just that. It doesn't matter that the light is in the garage.

For a Media Director, the on-screen Orbiter User Interface appears on the TV screen. It is manipulated by the mouse/keyboard or remote control connected to your Media Director. By default it is set to display the scenarios for the room in which the Media Director is located.

In contrast, a mobile Orbiter (such as a webpad) can be carried throughout the house. It must be able to select the scenarios for multiple rooms. Fortunately, the option to manually select which room you are currently in is available on every Orbiter's main menu.

This can occasionally cause some confusion. Perhaps both the Living Room and the Bedroom have a scenario called 'TV'. You may have a web pad that is in the Bedroom, but you then carry it to the Living Room. You may forget to tell the web pad that it's now in the Living Room (at the bottom of the Orbiter screen it will still say 'Bedroom'). You hit the 'TV' button expecting the Living Room TV to come on, but in fact you're still controlling the Bedroom and the TV comes on there instead. Finally you may realize that you must change your room location to Living Room, and you can then finally control the TV there.

Once you get used to this concept, though, you'll find it very useful. Conveniently, any Orbiter can be set to control any room and choose from the scenarios assigned to that room. No matter which Orbiter you use, the same set of scenarios will be displayed for each specific room. For example, the kitchen scenarios will always be the same, no matter which Orbiter you are using. (The scenarios are assigned by room -- not by Orbiter.) No matter whether you pick up your mobile phone, your web pad, or your remote control, you will always be shown the same list of scenario options for the Living Room.

You have the option of preventing some family members from using certain scenarios. From the [[LinuxMCE Admin Website]], certain scenarios and rooms can be [[Users#Restrict_Access|restricted to certain users]]. Maybe little Suzy's mobile phone Orbiter should be restricted so that she is only able to control her room and the living room, for example. She would only be able to execute the scenarios in those rooms, but not the Master Bedroom. Other possible options include [[Users#Restrict_Access|requiring a pin code]] to access the scenarios for a particular room.

== Events ==

Devices report events, such as 'Playback started' and 'Motion Sensor tripped'. If you want something to happen automatically in LinuxMCE, you create Event Handlers that react to these events. For example, you can create an event handler that listens for the 'Motion Sensor tripped' event from a motion detector and turns on the lights in response. An event handler might listen for the 'Sunrise' event, which could then prompt the sprinklers to come on.

LinuxMCE creates several default event handlers. In rooms in which you have a TV and lights, an event handler is created that listens for the 'Watching Media' event sent by a media player. When the event is detected, the Showtime scenario (which dims the lights) is executed in response. When you start a movie, therefore, the Showtime activity will be executed and the lights will be dimmed. There are other default event handlers that monitor for events like 'Security Breach' and 'Fire Alarm' (from a home security system).

== Controlling an Orbiter ==

To control the system, you use an [[Orbiter]], which is the LinuxMCE term for a remote control. All [[Orbiters]] have the same basic function: to display the scenarios in the room you're in and let you select one. The different Orbiters may [[Selecting_the_Right_UI|display the User Interface slightly differently]], depending on their screen size, but the function and the list of scenarios is always the same. For example, the [[Selecting_the_Right_UI|"UI1" interface]] (which is used on webpads and PDAs) displays the scenarios in horizontal rows. (If there are more than will fit on a row, there will be a "more" button.) A home button is always displayed that takes you to the main menu. On smaller displays, as on mobile phones or desktop phones, there's not enough room to show the scenarios themselves. The top level menu shows only the categories: Lights, Media, Climate, Security and Telecom. Selecting a category displays the scenarios in that category.

[[Selecting_the_Right_UI|"UI2"]] is the [[Selecting_the_Right_UI|preferred User Interface]] for Media Stations. Using a traditional I/R remote is not much different from using any other Media Center PC remote. The menu button brings up the main menu, and you use the ''left/right/up/down/enter'' buttons to navigate it. The ''fast forward/rewind/skip +/skip -'' keys are used for media playback.

If you have a pointing device like a mouse or gyro air mouse, the UI2 interface also supports a unique control architecture that lets you do everything with 3 (programmable) buttons (plus ok and cancel). The 3 buttons are "MEDIA", "MENU", "AMBIANCE".

On a mouse with 3 programmable buttons (such as the [[Using_the_Gyration_Remote_GYR3101US_%28Non-Fiire_Chief%29|gyration]]), these functions correspond to the buttons from left to right. If you are using a traditional 3 button mouse, you can use the F6, F7 and F8 keys on the keyboard for the three programmable functions instead. In both cases, the left mouse button is "ok", and the right mouse button is "cancel/go back".

Mouse button behavior is "absolute" when you press and hold the media/menu/ambiance button and "relative" when you tap and release.

The "absolute" behavior is generally more efficient. For example, in the case of the middle button (F7), "absolute" behavior means the action is executed without having to additionally click "ok". If you press and hold the middle button (F7) while moving your mouse pointer to the option, then let go, that option is executed. If you instead tap and release the menu button ("relative" behavior), you will only highlight the menu option. You must then press ok (the left mouse button) to execute the option.

Categories appear along the bottom of the screen, and the scenarios in each category popup vertically (like a pull-down menu in a PC, except upside down). If the main menu isn't already visible, bring it up by pressing the "start" button on a Windows I/R remote, or the "menu" button on a 3-button mouse. To exit a menu, use the back button on the I/R remote, the cancel button (right mouse button on a 3-button mouse), or the ESC key on a keyboard.

In UI2 the media is always full screen. If you're not playing your own media, the background media (i.e. screensaver images) is gallery art from the Internet (using flickr) or [[Use_my_own_pictures_in_the_Screen_Saver|pictures you select]]. If only the screensaver images are displayed on the Media Station, press the menu/middle/F7 button to bring up the menu. Right click/ESC to get rid of it. (This works even if your own media is playing.)

If you're using UI2's 3-button navigation model, the normal media control options on a traditional remote are replaced with a single button: "media" (left soft button or F6). Press this and move the pointer up and down for your skip functions (''ch+, ch-, skip fwd, skip back''). Move the pointer left and right for speed control (''rewind, fast forward''). The further you move, the faster the media playback changes. If you hold the button down (the left soft button or F6), your movement will be "absolute". Instead of the traditional "jog shuttle-type" control, movement to the right skips to the end of your media, and movement to the left skips to the beginning. Once you get used to it, you will find that navigating media is orders of magnitude faster and easier with this model than with a traditional remote. You can find a spot in a 2 hour movie in only a couple seconds with a click of a single button (compared to a slew of button clicks required using a traditional remote).

Also, in UI2 you can press the "ambiance" button (right soft button or F8). Move up/down to adjust the lights, and left/right to adjust the volume. As with the media playback, if you hold the F8/right soft button down while you move left and right, your volume control is in "absolute" mode (not "relative"). Moving hard right turns up the volume full blast; hard left is mute. This requires you have a TV or receiver that is serial-controlled, however. LinuxMCE can then directly and instantly set the volume position in sync with your hand movements. (Few TVs and receivers have this feature, unfortunately.)

There are other media control functions besides the most commonly used ''fast fwd/rewind/skip up/skip down''. You can, for example, choose 'subtitles' while watching a DVD, 'guide' while watching TV, and 'random' while listening to an audio CD. In the UI2 3 button model, these functions appear on the main menu (on the left-most pad, entitled 'now playing') and changes according to the type of media you're playing. Press the menu button (middle button/F7) to select these options.

This 3 button model is a new concept and very different from traditional navigation. Most people find it much faster once they become accustomed to it.

==Reload Router & Regen Orbiters==

While using LinuxMCE you'll see sometimes a message asking if you want to [[Quick reload router|reload the router]], or if you want to [[Orbiter Generator|regenerate the Orbiter UIs]] (User Interfaces). In general, these options refresh the LinuxMCE databases so that changes to the system can be recognized.

===Reload Router===
All devices in LinuxMCE obtain their configuration information from the [[DCERouter]], which is the central piece of software on the Core. All devices request a list of the other devices in the home from the router, so they can respond to them appropriately. (For example, an IP camera device might turn on the lights in the room whenever you're viewing the camera. To do so, the IP camera needs to know what lights are in the room.) Typically a device requests this information only when it's starting up. When you connect additional plug and play devices to the system, these new devices generally will work immediately, but their functionality may not be fully enabled within the LinuxMCE system until the DCE router is reloaded. When the router reloads, it signals all devices on the system to simultaneously reload and re-request the system data. Each existing device can then work with each new device. This process is known as a 'reload'. It generally takes about 10 seconds. Every time you add or remove devices, or change a device's configuration, you may be asked to do a reload. If you're going to add more devices or make more device changes, you can do the reload once you're done. If you're in the middle of watching a movie or TV, you can postpone the reload, since media players generally stop playing during reloads. Phone calls aren't affected, though, and TV shows being recorded by MythTV in the background are also unaffected.

===Regen the Orbiter===
LinuxMCE's [[Selecting_the_Right_UI|Orbiter User Interfaces]] are all "pre-rendered" in order to be more efficient. The User Interface source images are all very high resolution, but need to be resized to accommodate the resolution of each Orbiter screen. The Core server has a list of the Orbiters used by your system, and will generate the appropriate User Interface screen for each Orbiter. It will do this each time you request a "regen". If you have five different types of Orbiters (each with a different type of screen), then five different images will be generated during each regen.

These User Interface screen images are stored in the Core. The appropriate UI image is sent to an Orbiter whenever it is activated. For many low-power devices (like mobile phones or desktop phones) there just isn't the processing power to do scaling and rendering of a User Interface screen on the fly. They need to be pre-rendered (with text pre-embedded in the images) to be efficient.

Adding new scenarios may result in the creation of new buttons for the User Interface, or changes to the text on existing buttons. Perhaps an entirely new screen will be created.

Until the User Interface images are regenerated, though, you won't be able to see these new buttons (or screens) on your Orbiter. During the regen, new User Interface images for each type of Orbiter is generated by the Core. This can take about 2-5 minutes, depending on how many Orbiter types you have in your system.

You needn't do a regen every time you add a scenario. You can wait until you have finished adding all the scenarios. Furthermore, you can also regen only the Orbiter you are currently using by doing a "Quick regen". This allows you to see the new User Interface (following the addition of new scenarios) without having to do a full regen for all the Orbiters. Once you have finished adding scenarios, then you can do a full regen.

This regen process can be a bit annoying, but is necessary. In future editions of LinuxMCE, it is planned to allow Media Directors, which have a lot more processing power, to render their on-screen Orbiter User Interfaces on the fly (so you don't have to do a regen each time you add or remove a scenario).

You can do a [[Orbiter Generator#Running OrbiterGen (performing a "regen")|full Orbiter regen or a Quick regen]] at any time by using buttons on the Core's LinuxMCE [[Launch Manager]].

== Managing your media ==

LinuxMCE is always scanning for network shares, on NAS devices and other HDDs of PCs connected to the system (including Windows PCs). USB drives are also detected. You will be asked if you "if you want to use it" every time a network share is found. Whenever you reply "Yes", the file share can be used by any Media Director on the system. The file share is scanned for media (audio, video and photos) which is then cataloged in the Core's central database. For example, when you plug in a USB drive on a Media Station in the living room and say 'yes' to use it, the media on the drive will be available to Media Directors in other rooms.

At the moment there is no way to restrict your media for 'local use only'; all Media Stations in the LinuxMCE system share the media catalog stored on the Core. (This is a limitation that will be addressed in the near future. Sometimes it is desirable to attach a USB drive in the master bedroom and not allow it to be shared, for example. ''Note: However, see [[folder lock|this article that describes a method to address this problem]].'')

Storage devices (NAS, USB drives, extra HDDs on the Core or Media Directors) are referred to as "Extra Drives". When an extra drive is added, it is listed in the device tree in '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]'''. Under 'Core' you'll see a device listed for each HDD in the Core, as well as for each NAS device. Under each Media Station will be listed the HDDs in that Media Station. By clicking on the device you can change the device's properties, such as the mount username/password. Each NAS device, and each file share on another PC, will show as a device listed under the Core; each is considered a child of the Core.

LinuxMCE creates a top level folder for 'public' media. This folder can be used by every user in the system. A 'private' media folder is also created for each user. Within each of those folders are sub-folders, labeled 'audio', 'video', 'pictures', 'data' and 'other'. Within each of those will also be sub-folders for the extra storage devices (NAS, USB, extra internal drives, etc). When you attach an extra storage device, you can specify whether the default directory structure should be used for it. Alternatively, you can specify 'just make it public' or 'make it private'.

Here's an example. Let's say you have 2 users: john and mary. You connect 3 storage devices:
# a NAS, for which you specify 'use default directory structure'. It is named 'Generic Network Storage [50]'
# a USB drive for which you specify 'make it all public'. It is named 'USB Drive [51]'
# a SATA drive for which you choose 'make it private for john'. It is named 'General Internal HDD [52]

Now let's say you're running Windows. Go to Network Neighborhood and find the LinuxMCE Core server. The directory tree ought to look like this:
<pre>
public
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
USB Drive [51]
john
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
General Internal HDD [52]
mary
video
Generic Network Storage [50]
audio
Generic Network Storage [50]
pictures
Generic Network Storage [50]
data
Generic Network Storage [50]
other
</pre>
Whether you put your media under video, audio, pictures, data or other is unimportant. It will be scanned by LinuxMCE anyway. The contents of "General Internal HDD [52]" will be displayed in the folder john/other/General Internal HDD [52]. The contents of USB Drive [51] will be displayed in the folder public/other/USB Drive [51]. When John browses the contents in Network Neighborhood, he will be asked for his username and password. He can then access the content in both the public folder as well as the "john" folders (including General Internal HDD [52]). When Mary browses the contents with her username and password, she will see both the public and "mary" folders. She will not be able to see anything on General Internal HDD [52], however, since that drive was specified to be private for John.

In the case of John's private media, it won't be displayed in the LinuxMCE media browser unless you click 'Sources'-->'John'. However you ''can'' see the contents of General Internal HDD [52] (unless you deselect 'Sources'-->'Public' from the media browser). Generic Network Storage [50] would be different, however, since you specified to use the default directory structure for it. LinuxMCE will have created public directories on Generic Network Storage [50] for public video and public audio, as well as for john's video and mary's audio. The media file browser will show only the media that is in the public directories. (The same is true with the Windows Network Neighborhood browser.)

If Generic Network Storage [50] has existing media in the top (root) folder, you won't see it listed anywhere.

It is generally recommended, therefore, that when you add a new (blank) "extra" storage device, you choose to use the default directory structure on it. When you rip media to that device, the media can then be made either public or private, and LinuxMCE will automatically put it in the correct folder (audio, video, etc.).

If you connect an extra storage device that already has media on it, however, and that media isn't already organized in LinuxMCE's default directory structure, it's easiest if you simply 'make it all public' or 'make it all private'. If you were to 'use the default directory structure', you would need to manually move the files from the existing folders into one of the directory folders that LinuxMCE would then create for you.

When you rip files, you have the option of copying them to the Core. If you rip a CD and make it public, it will be stored in public/audio. If you go into Network Neighborhood and add a folder under public/audio, you would essentially be adding a folder on the Core. If you add a folder under public/audio/Generic Network Storage [50], you would be adding it to Generic Network Storage [50].

This concept behind drive/network drive management is not the same as the method to which Linux and Windows users are accustomed. In Windows, for example, each network device shows up separately; they are never grouped together. There is an advantage to the way LinuxMCE manages drives. It's much simpler to add devices when you're a novice and don't understand networking. Further, if you're using an infrared remote control, you can manage drives with a single 'yes' or 'no,' click, which is very convenient. Lastly, all your media content is cataloged and presented in the same structure throughout the system, no matter which Media Director you're using or what room you're in.

In Windows, by comparison, if you connect a USB drive to a Windows PC in the bedroom, you won't see that content in the living room unless you 1) open file explorer, 2) create a new network share for it, 3) go into the living room, and 4) create a new mapped network drive there. (That isn't so easy to do with an infrared remote and without some knowledge of networking.) Further, you wouldn't be able to see the media in any other room in the house unless you were to also create mapped network shares in those rooms as well.

With LinuxMCE, when you connect a USB drive, for example, you can 'make it all public'; the media will be available everywhere. No other typing is required. With LinuxMCE, instead of managing multiple network shares and mapped drives, you can choose the Core's public folders in the Network Neighborhood browser from anywhere in the home, without having to know which storage devices the media is actually on. When you remove a USB drive from a Media Station, that media instantly disappears from the catalog displayed in every room. If you reattach it, it will re-appear.

You can also backup the media securely on the Core. LinuxMCE has built-in [http://en.wikipedia.org/wiki/RAID RAID] 5 (see '''[[LinuxMCE Admin Website]]-->Advanced-->[[RAID]]'''), so its HDD has similar backup capabilities to an [[NAS]].

To change the name of an extra device, go to the '''[[LinuxMCE Admin Website]]-->Advanced-->Configuration-->[[Devices]]''' and under the Core you will see listed the HDDs in the core and any connected NAS devices. Under each Media Station you will see the HDDs in that Media Station. All are given default names. You can change the description, which will also change the folder name. In the above example, changing "USB Drive [51]" to "Tokyo" means the directory public/other/USB Drive [51] would change to public/other/Tokyo.

In the '''[[LinuxMCE Admin Website]]-->Files & Media-->[[Media Files Sync]]''' is listed the files in the system by folder. You can change the cover art and attributes. If a file is shown with a check box, the file exists both on the local disk as well as in LinuxMCE's master catalog. If it has a different icon, then LinuxMCE hasn't finished cataloging the media; just be patient. It should appear with a check mark soon (depending on how much new media was added). Under Files & Media there is also a cover art scan utility that will find cover art, as well as other attributes (actor, genre, etc.) obtained from Amazon.

====Background details====
Here's how it works: [[UpdateMedia]] is a daemon that constantly scans for media files in the /home/public and the /home/user_xxx folder created for each user. Any added media is cataloged in the pluto_media database File table, and attributes and cover art go into the Attribute and Picture tables. Under /home/public and /home/users_xxx is a data subfolder which contains the actual video, audio, pictures folders. (The /home/user_xxx directories themselves contain the system files for each user (like email boxes) as well as the main login for that user (in a "data" subfolder).

Extra devices are mounted as /mnt/device/xxx (where xxx is the device number). The mount point is the same whether it's a local drive or not. For example, USB drive [50] in a Media Station may be mounted as a local device named /mnt/device/50, but is also mounted as a Samba mount on other Media Stations as /mnt/device/50. The Core and the Media Stations all use the same mount names (/mnt/device/).

Within the /home/public/data and /home/user_xxx/data are symlinks to the physical directories specified by /mnt/device/xxx. Since the Core and all Media Stations mount the same /home directory (and all have the same /mnt/device mounts), they will all show the same files. Therefore, if the [[UpdateMedia]] daemon locates the file /home/public/data/audio/Generic Internal Drive [50]/The Beatles/Let it be.mp3, that file will be listed on every Media Station, too.

[[Category: Tutorials]]