Skip to content

Quickstart

Jump to bottom Edit New page
Brian Gapinski edited this page Apr 11, 2014 · 4 revisions

#Quickstart cmdr is a low-cost solution to control devices typically found in multimedia classrooms. The main project can be found here.

cmdr consists primarily of three parts.

  1. cmdr-daemon: This is the main program that controls the devices.
  2. cmdr-devices: The drivers that handle communication between the devices and cmdr.
  3. cmdr-server: Though not a critical component of cmdr, cmdr-server offers a one-stop solution for users to configure and monitor multiple cmdr instances.

This document will focus on the various aspects of cmdr-daemon. For more info about the other parts, see the documentation on their respective project pages.

##cmdr-daemon ###The Deployment Process cmdr itself is just a bit of software responsible for handling messages between devices. Nonetheless, a fair amount of setup is required before things can get working. Our current model consists of:

  • Asus EeeBox PC EB1030
  • Mimo Touch 2 Display USB Touchscreen
  • Ubuntu Server

We use a custom build of Ubuntu Server LTS that does most of the preconfiguration for us. Information on how to create the image can be found here. The isolinux.cfg file is responsible for booting into the installer without the need of any user input whereas the preseed file is responsible for setting up a default user and environment as well as running our postinstall.sh script which configures chef. Instructions on how to deploy the cmdr software can be found here.

####Dependencies Dependencies have to be manually installed.

  • CouchDB >= 1.2
  • RVM
  • Ruby 1.9.3 (Install with RVM)
  • RabbitMQ-Server
  • Avahi-Daemon (optional dependency for cmdr-server integration)

Our deployments display chrome in fullscreen loaded with the interface. This requires installing X11 as well as a window manager (we use Awesome).

###How cmdr Works. cmdr is a decently sized project with a Ruby backend and JavaScript frontend communicating with websockets.

The basic flow of command is as follows:

  1. A user interacts with the touchscreen. This initiates a request which is sent to the backend over a websocket.
  2. The backend receives the message. The message is interpreted and the appropriate action is carried out. Since the user initiated the request, this will typically be a request to change the state of the room.
  3. The backend determines which device needs to be changed based on the message contents and sends the request to the appropriate device.
  4. The device executes the request and returns its state.
  5. The backend updates the database to accurately reflect the current state of the room. A message is sent to the frontend notifying that the state of the room has changed.
  6. The frontend interprets the respone and updates the display to accurately reflect the current state of the room.

###Important Directories

  • bin contains the cmdr executables
  • lib contains all the library code for cmdr. Most development takes place here.
  • lib/cmdr contains the classes that are responsible for handling communication.
  • lib/cmdr/devices contains all the drivers for the various devices.
  • tp6 contains the frontend code.
  • tasks contains various rules for rake.

###Digging Deep: The Important Files. The important parts of the program are found inside the lib directory. This will serve as a brief summary of the most important parts and their role to the overall cmdr program. More detail can be found in the actual file documentation.

  • cmdr.rb:

    This is the "main" program. This file is responsible for starting each device thread. Other than that, this file is not too important.

  • cmdr_websocket.rb

    Arguably one of the more important files in the cmdr project. cmdr_websocket is responsible for managing the websocket server that communicates with the frontend. Messages from the user get sent here and are parsed here before being sent out to the relevant device. All of the device messages get sent here and parsed before being sent to the frontend. Internal management is through a state machine that represents the current state of the room. In other words, every message goes through cmdr_websocket.

  • device.rb

    This is the main device file that all other devices inherit from. It specifies the Domain Specific Language (DSL) that the device drivers are written in. More information about writing device drivers can be found here. The documentation provides other useful information as well.

  • SocketDevice.rb

    This class allows devices to communicate over tcp/ip connections. SocketDevice defines how messages are sent to devices and parses responses.

  • socketclient.rb

    Whereas SocketDevice handles communication with the device, socketclient handles the actual tcp/ip connection.

  • RS232.rb

    This class is essentially a mirror of SocketDevice except that it specifies communication over RS232 serial connections.

##Setting up the Database cmdr looks for a rooms database. If this database does not exist, cmdr will automatically create it and populate it with some default data. The default is very minimal and will not provide enough data for cmdr to do anything useful. So let's add some documents.

###Configuring the Database Note: Currently, configuring the database is a nightmare. Documents have to be manually added and adjusted to whatever is needed. This aspect of cmdr is currently a work in progress. Right now, we suggest using CouchDB's replication features to copy a configured database and make the necessary changes.

The rooms database contains various types of documents:

  • building: This document represents a building. Buildings contain rooms and rooms contain devices.
  • room: This document represents a room. It is identified with the MAC address of the current device running cmdr and lists the devices contained in this room as well as some metadata.
  • device: These documents define the devices belonging to a room. They contain the following fields:
    • class: The type of device. This should be the name of the driver that this device uses.
    • belongs_to: This is the id of the room document that this device belongs to.
    • attributes: Information about a specific device. Configuration of a device should be done inside a config hash inside this field.
  • source: These documents define the actual inputs/outputs for the room. Example: A pc plugged into the hdmi port is a source.
    • name: The name of the source.
    • input: This defines the channels on the input/output devices to use.
  • action: These documents list the options we care about. An action defines something that can happen in the room (eg change to a specific source). All actions are displayed on the touchscreen.
    • name: The text that displays on the touchscreen.
    • settings: Various settings for the action.
      • source: The id of the associated source document. When the action is selected, it will change the state of the room to those listed in the document with this id.
Add a custom footer
Add a custom sidebar
Clone this wiki locally