Green Book Manual

Introduction What is Green Book Quick Start Guide First things first Frames Entities Circuits Find box So far so good Usage Basic Data Entry Login Use the TEST site for practicing Placing devices in Racks or Desks Wiring Devices Optional information Disconnecting and Deleting wires Constrains Changing Device information Altering Ports Placing Frames Frame Number and Designation Adding Locations Creating Device Definitions Adding Ports Bidirectional Signals Multi-pins connectors Frames Entering Data from Manual or Datasheet Entities Entering data from direct visual inspection Advanced Data Entry Context Help Pending Device Library Device Definition Find box Locations Allocating and Delocating Devices Wires Lookup Page Wire Lookup Result Status Rack View Frame View Device View Further Development Global Search Command general format Find command Implicit elements Complex entries Use of quotes Implicit quotes Use of asterisk Use of qualifiers Logical Operators Grouping with and without parenthesis For developers Frames implementation

Content

This manual is under construction and consequently incomplete. It will be completed as time permits and the system itself continues to develop.

Green Book is a web-based tool intended to full-document circuits layouts in a Broadcast installation. It takes a tabular approach (as opposite to drawings) to represent circuits, allowing for agile data entry and easy updates.

Ancillary information such as Engineering Notes, History Logs and binary documents (such as PDF) is also supported.

Green Book is about DEVICES placed in LOCATIONS and connected by WIRES.

Locations conforms a hierarchy: BUILDINGS, ROOMS, RACKS or DESKS, FRAMES, SLOTS. Devices reside in racks, desks or frame slots.

You don't create devices directly. First, you create a "device definition" (for example, a UTAH DA) in the Device Library; then you place an "instance" of that definition on the intended location. Definitions are sort of templates from which you create devices. They are reusable; as you create more and more definitions, you will find your self reusing more and expending less time in creating new ones.

Once you have devices in place, you can interconnect them with wires. To do that, you just enter the wire number in the device's port you want to "connect". If the wire does not exist in the database, it is automatically created; if it exists already, it is found and "connected" for you.

The point of having devices interconnected this way is that now you can navigate the GUI from device to device just by clicking at the wires. In each stage of your navigation you will have a complete view of the device (device type, manufacturer, model, etc, all its inputs and outputs), all wires connected to it and an indication of its location. You will also have access to ancillary data associated to that device such as manuals, engineering notes and a history log.

FRAME is a special case. Because it contains SLOTS, it is treated as a Location. However, frames have certain attributes that make them look like devices. For example, they have Manufacturer, Model Number, Serial Number, and, more importantly, some frames have ports on their own (such as Ethernet and Black Burst) to which wires can be connected.

That is why Green Book treats FRAMES with duality: they are Locations and Devices at the same time. As a location, it fits into the Locations Hierarchy and contain SLOTS. As devices, they are created in the Device Library and instances are placed on Racks or Desks, same as with other devices.

Devices and Wires have a number of user definable attributes. Some of those attributes reside in the object record and are unique to that object, for example, a wire number. But others comes from a list previously populated; that is the case of Manufacturers, Signal Types, Connector Types, Wire Types, Device Types and Status.

We collectively call these lists: Entities, and you, the user, are responsible for filling them out. To do that, you click the Entities button in the Toolbar and edit the desired list.

Until now, we have seen devices in isolation. We are missing the "big picture" and that is exactly what Circuits View provides.

In its Circuit View, the circuit layout is presented as a list of devices one on top of another, with all connected ports properly labeled and wire numbers also indicated. This Circuit View contains only the devices composing a certain circuit, such as "LiveU", or "Light TV", that you have defined.

You define a Circuit by indicating both the "departure" and the "arrival" devices. Green Book builds the circuit automatically by departing from your Departure devices, following all the connections and listing all devices as they are encountered. This process repeats recursively until no more connections are found or Arrival devices are reached.

The final result is presented to the user and, at the same time, data is statically stored into a CACHE structure in the database. Once cached, you have the opportunity to make changes such as altering the order in which device appear in the list or even removing devices that you consider irrelevant to that circuit.

The Find Box, located in the Tool Bar, is intended for quick navigation and wire lookup.

You can enter things like:

    wire c123
    rack 27
    rack liveu
    frame 31
    room 237
    room color video
    device skype
    device 7700da7

The first word is called "qualifier" and indicates the kind of object you are looking for. The default qualifier is "wire", meaning that you can omit it so that "wire c123" is equivalent to just "c123".

The following qualifiers are recognized:

   bulding
   bld
   room
   rm
   rack
   rk
   desk
   frame
   fr
   device
   dev
   equipment
   eq
   wire

Notice that 'rk' is an abreviation for 'rack', and so on. Qualifiers 'device', 'dev', 'equipment' and 'eq' referres to the same type of object.

For wires, you can enter a simplified, non standard, version of the wire number; for example,"c2" instead of "C-002". You can also enter keywords that seem related to the wires you are seeking; for example, "roof cam" will find all wires related to the roof cam.

The result (for wires) is a table having one row per wire, which columns describe wire attributes such as last updated date, signal type, color, etc, and also links to the devices they connect to. The table first appears sort by wire number, but you can re-order by any column by just clicking at that column.

In the case of locations (rooms, racks, desks or frames), you will be taken directly to that location. In the case of multiple matching, a list with links is presented from which you pick the desired one.

You can enter the location number or some keyword (sub string) you know is in the description field of that location. For example, to go to the "Color Video" room, which is RM-237, you can enter either "room 237" or "room color video".

In the case of devices, the keyword you enter must match a device type, manufacturer, model, description, designation, etc expected in the device(s) you are seeking. For example, you can enter "evertz" or "7700da7".

Your entry is memorized in a session variable. You can continue to navigate the system, then return to the same result by just pressing the [Go] button again.

Now you are ready to start experimenting with the system. To do that, point you web browser to the following URL:

    http://melixa.wsvn.com/greenbook/

This will only work if you have access to our internal 191 network. Don't try this at home.

No login is required unless you intent to make changes to the data, in which case you'll need to login using Melixa credentials that you probably already have.

This Quick Guide have explained the very basics but Green Book is much more than that. The rest of the Online Manual will explain the system in full details. This Online Manuals are in the following URL:

    http://melixa.wsvn.com/man/

[ ... to be continued ... ]

Point your web browser to the following URL:

    http://melixa.wsvn.com/greenbook/

Your device must be connected to the WSVN Local Area Network.

The system is read-only until you Login. To login, click the [Login] button located to the right-must up corner of the window and enter your Melixa credentials.

If you don't have credentials in Melixa, visit melixa.wsvn.com and subscribe to Melixa by pressing the [Register] button. Once you have registered to Melixa, you can login in Circuit Tables using the same credentials.

Green Book is hosted in two separated sites: the "Production Site" mentioned in previous section, and a "Test Site" located at:

    http://melixa.wsvn.com/test/

It is recommended that you start practicing data entry in the Test Site until you find your self comfortable with the system.

Software in the Test site is usually more up-to-date since updates are first tested there before deploying to Production. Data is periodically replicated from Production to Test so they are usually very similar but not necessarily the same.

The first step in Green Book is to place a device in a rack. Say for instance you want to place an AJA FS1 frame sync on rack RK-27.

You need to navigate the GUI to RK-27. The easiest way of doing that is via the Find box located in the Tool Bar: type "rack 27" in the box and press Enter (or click the [Go] button). You will be taken directly to the rack view of RK-27.

Now you have a list of all devices present at that rack. To add yours, press the [Add Device] button located at the bottom of the list.

In the next window, press the [Browse] button. This will take you to the Device Library where device definitions reside. Remember that you create devices by placing "instances" (copies) of device definitions on racks or desks.

Now you navigate the Library to find your device definition (AJA FS1 frame sync in this case). Click in the "Dev Type" list box, select "FS" (for "Frame Sync"). You will get a list of existing frame sync definitions. Select "AJA FS1".

You will notice that a new white banner appears on top, just below the Tool Bar, prompting you to "Add this Device to: RK-27". Hit the [Proceed] button to make it so.

Now you are taken back to RK-27. You will see your new AJA FS1 added to the list.

Notice the second column, "Designation", it is empty for your new devices. Thought no mandatory, it is highly recommended to fill this field for easy identification. Hit the "Edit" link in the last column ("Do") and enter something relevant in the "Designation" field (for example, "test").

This completes the placement (and creation) of a new device on a Location.

When you click a device in the Devices Lists, you get into "Device View" screen. In this view you have a complete representation of the device with all input and output ports.

To connect wires, you just click the "+" link in the CABLE column of the desired port and enter the wire number into the box that there appears.

Say for instance you want to connect wire number A-001 to the SDI-1 Output of the FS1 you created in the previous section.

Once in the Device View of your device, locate the desired output and click the "+" link in its CABLE column. In the little box appearing there, enter the wire number: you can enter "a1", "a-1", "a 1", "A-01", etc. The system will automatically convert your entry to standard format: "A-001".

Now the view shows wire A-001 connected to SDI-1 Output port. A question mark (?) in the "Connected To" column indicates that the other end of the wire is not connected yet.

Let's connect the other end to another device, for instance a new VDA.

Proceed as explained in previous section to add a new VDA to rack 7. You can navigate to the rack directly by clicking in the "RK-7" button of the Navigator located at the top of the view.

Once you have your new VDA in place, navigate to its Device View.

Locate one of its inputs and click the "+" link of its CABLE column. Enter the wire number: "a1". Now you have the two devices connected with wire number A-001.

Notice that the "Connected To" column now contains a reference to the port connected at the other end of the wire. Clicking that column will take you to the device view of the AJA FS1 you created previously. Notice that the "Connected To" column not longer contains a question mark but a reference to the VDA, also clickable.

If you click the CABLE column of a connected wire in Device View, you will be taken to a "Wire Info" screen with more information about that wire: Label, Color, Type, Multiconductor, Status, Connection Reference and Hash number.

We will cover the last four in section "Advanced Data Entry".

Clicking the [Edit] button will take you to an "Edit Cable" form where you will be able to add or change optional information. Notice that the actual wire number (fields Prefix and Number) can not be changed.

Label refers to an optional label (apart from the wire number itself) the wire could bear, for example "Roof CAM".

Color is the physical wire color. For instance, most AES wires in our facility are color orange.

The Type is picked from a list box. It could be "Coax", "Ethernet", etc.

Again, this information is optional, but it may prove useful if present.

You may want to disconnect a wire from a port, either to reflect wires that have been disconnected in real life or because you committed a mistake when entering the data.

To disconnect a wire, go to its "Cable Info" view by clicking its CABLE column in Device View and click the [Disconnect] button. Press [Proceed] in the prompt screen to confirm your action.

Now you are taken back to Device View. The wire have been disconnected from that port and marked as "Dangling at (this location)". If you navigate to the Device View of where the other end of the wire is connected, you will see the Dangling message in the corresponding "Connected To" column.

You can also delete the wire all together. To do this, navigate to the "Edit Cable" view and click the [Delete] button.

When you delete a wire, its record is removed from the Database so all associated information is gone.

The system will prevent you from connecting a wire between two inputs or two outputs. If you try to do that, you will get an error.

There is an exception to this constrain: the case of "Bidirectional signals" such as Ethernet and Serial. We will cover that in section "Advanced Data Entry".

In Device View, hit the [Edit] button to enter the "Edit Device Info" screen.

Notice that some fields can be changed, others do not. You can change the Status, Designation and Serial Number, but you cannot change the Type, Manufacturer, Model and Definition.

This reveals the very nature of Devices and Device Definitions. Remember that Devices are created by instantiating Device Definitions.

Those fields that you cannot change in this view belong the the Device Definition from which this device has been created, they are only references to that information. You can still change it, but not in this view but in the Library, and doing so will impact all devices coming from that definition.

Those fields you can change, belong to this device in particular. Specially useful is the "Designation" field which should reflect the actual use of this device in practice, for example "LiveU-5 FS".

When a device is created, ports are copied from the definition to separated records that truly belong to the device, not the definition. Most of the time you will use those port unchanged. Some other times, however, you may need to alter some ports. For example, some Tandberg IRDs have configurable outputs that can be either ASI or SDI, and most Device Managers have configurable serial ports that can be either RS232 or RS422.

To change a port, click the corresponding "Label" column. You will be taken to a "Edit Port" screen where you can make any change you want.

There is a restriction: you cannot alter the port direction (input/output) if it has a wire connected to it. If you are in this situation, simply disconnect it momentarily, change the port direction and then connect the wire again.

You can also Delete a port by clicking the [Delete] button in "Edit Port" view or add other ports is needed.

Changes you make in device ports won't affect those in its definition.

You create FRAMES the same way you create any other device, only that, once created, selecting it from the list will take you to a SLOTS list. Remember that Green Book treats FRAMES as dual objects: Device/Location.

To add a card device to a frame SLOT, navigate to the Slots View and click the "+" link in the "Do" column. Then pick a device definition the same way you do for other devices. Notice that near the "+" sign is a "@" sign. That is for device "Relocation", a concept that we will cover in section "Advanced Data Entry".

If the frame happens to have ports, the Slots View will have a link at the bottom reading: "--This frame has direct connections--". Clicking that link will take you to a Device View in which you will be able to connect wires to the frame's ports.

As the locations they are, frames have a system-defined prefix (FR-) and a location number, for example "FR-1".

When you create a frame, you must manually enter its Number so it can be properly referred in the presentation.

Some frames, however, do not have official numbers in our facility. If you leave the Number empty (zero), Green Book will display its name as "FRAME", not "FR-0", unless you fill in the "Designation" field in which case, the designation will be displayed instead.

It is unlikely that you need to add new Locations to the system because those was imported from Blue Book in Mars 2020 with the help of Mark. Already in the system are all Rooms with corresponding Racks per location as defined in Blue Book since decades ago.

Nevertheless, you can add new locations to Green Book if needed, specially new buildings. To do that, proceed as following:

Hit the [Locations] button in the Tool Bar. If you need to add a new building, hit the [Add] button; if not, select the building you want to work out. Once there, hit the [Add] button to add a new room or select the existing room you want to work out.

Proceed that way digging down the hierarchy. In each stage you can either add new items or edit existing information.

We have assumed that the Device Library is full of definitions ready to use to create devices, but  this is far from truth. On the contrary, there is a need for definitions and here you have a great opportunity to contribute in terms of data entry.

Before creating the new definition, make sure it does not exist already.

Hit the [Library] button in the Toolbar. Select your device type in the "Dev Type" list box (for example, "FS" for Frame Sync). Examine the list to see if your device is already there. If not, proceed as following to create it:

Hit the [Add] button to get to the "Add New device to the Library" form. Fill in the form as appropriate and hit [Save]. This will take you back to the list where the new definition should be now.

Select your just created definition from the list to get into the "Device Definition" View. This is the most important task: adding ports, which we will explain in details next.

Once in the Device Definition View, hit the [Add Ports] button to get to the "Add Port" form.

A ports can be either Input or Output. You establish this by selecting the proper value from the "Port Type" list box. Continue to fill in the up to the "QTY" field; if you are adding just one port, leave it with the default value (1). Press the [Add] button to save. You will be taken back to the "Device Definition" view, now showing the newly added port.

You can add multiple ports at once; this is useful in many cases, for example, DA outputs. To do that, fill in the form as described but now set the "QTY" field to the desired number of ports.

Optionally, multiple ports can be enumerated automatically. For example, to get outputs labeled "OT-1" to "OT-8", fill in the form as following:

    Label       : OT-
    QTY         : 8
    Append Enum : (checked)
    Starting at : 1

If you commit a mistake, or change your mind, you can always Edit a port to make the necessary corrections, even converting an Input to Output or vice versa.

It is not entirely true that a port can only be Input or Output. Some ports are "bidirectional" (duplex) which is the case of Ethernet, RS-232 and others. Green Book concerns about "Bidirectional Signals"; ports are kept into the Inputs/Outputs set.

When you add a port which Signal Type is bidirectional, you are free to define that port type as Input or Output. As a convention, we suggest to define Ethernet Switches ports as Outputs and computers NIC ports as Inputs.

It is very common in real-life devices to use multi-pins connectors such as DB25 to deliver linear signals like Analog Audio, usually via breakout panels or cumbersome hanging cables.

The problem with this is that, in Green Book, you cannot connect multiple wires to a single port, because the same is represented with a single table row.

The solution to this situation is the following:

A single multi-pins connector is represented by multiple rows in the Definition: as many rows as wires can be connected. For example, if you have a DB25 connector exposing 8 input audio channels, you define it with 8 Input Ports which connector type is "DB25".

When you define a device of type FRAME, you get an extra field in the form: "Slots Count". Fill this with the appropriate value.

That will suffice in most cases, but some frames present ports that belong to the frame itself. In those rare cases, you hit the [Add Ports] button and proceed as explained previously.

Remember that a Definition is a template from which devices will be created. This implies that the definition must be complete, it must contain all ports available in the real-life device including those of little or rare use in practice.

This fact encourage us to make our device definitions based on trust able data. Our recommendation is to always make device definitions from the device manual or datasheet.

Until now, we have assumed that those attributes that you need to pick from existing lists are already there for you to pick. Though this could be true in most cases, chances are for some, for example a manufacturer or a connector type, to be missing in the corresponding list. If that is the case, you will need to add it.

Hit the [Entities] button in the Tool Bar. A second toolbar will appear providing access to the different Entity Lists: Manufacturers, Signal Types, Connector Types, Wire Types, Device Types and Status.

Hit the button corresponding to the Entity you want to work out, for example, "Connector Types". This will take you to the associated Entity List.

The "Do" column contains an "Edit" links that will take you to a Edit form in which you will able to change entity Name and Description.

In the case of Signal Types, there are additional fields: Bidirectional and Color. The later refers to the background color used in Circuit View to highlight different signal types; you change that by choosing a color from the colors box. The "Bidirectional" field will be covered in section "Advance Data Entry".

In the case of the Status list, there is a Color field too. This refers to the font color used in the GUI to highlight wires and device status. We will cover this too en section "Advanced Data Entry".

If you need add a new entry to any of the lists, hit the [Add] button in the corresponding Edit form.

You can also delete an entity. When you do so, all objects having that entity value will be updated automatically to "Undefined". Notice that each Entity list has its own "Undefined" entry.

Some entries are "build-in" and can not be deleted. That is the case of "Undefined" and the device type FRAME. If you try to delete a build-in entity you will get an error.

One of the greatest virtues of Green Book is that you don't need to know much about the circuit you are documenting. You can start connecting wires to devices in no particular order and the system will build the circuit for you sooner or later.

For example, you can go to rack RK-T28 (the physical one) and make and inventory of all frames located there as well as all the cards placed into those frames. Then you turn to Green Book and place frame devices in location "RK-T28", and card devices into the corresponding slots.

If a certain device does not exist in the Library, you simply create it (possibly from the manual or datasheet) at that moment.

At a later time you can get back to the physical rack and take note of all wires connected to those cards. Then, start documenting that in Green Book in no particular order.

Green Book will reflect the interconnection between devices that happen to be interconnected by the wires you entered when both ends gets "connected" in Green Book. You don't have to enter both ends in a single session; you can enter one end today and the other, next month.

This method may prove an effective way for entering data into Green Book.

In this section we will take you further into Green Book features such as the use of Hash numbers and Multiconductor Wires.

[... to be continued ... ]

Most pages in Green Book offer a link labeled [Help] that takes to context-related topics in this manual. This section contains those topics, not suitable for casual reading. They are listed in the order they was written.

Sorry, this topic has not been written yet.

The Device Library contains device definitions, templates from which you create actual devices. They are grouped by Dev Types.

Use the Dev Type list box to select the device type (for example, VDA). A list of relevant definitions will be shown. If your type is not listed, press the [...] button near the list box to go to the Device Types entity list where you will have the opportunity to add it; then go back to this view.

Pick the desired item from the table (by clicking the corresponding row) to see information about that device definition. If you plan to make changes in that information, click the Edit link instead.

For adding a new definition of that type, press the [Add] button.

Keep present that you won't be able to change data if you are not logged in.

A Device Definition is a template from which you create actual devices. In this view you have all the information available for the definition being presented.

The Dev Type value is a link you can use as a shortcut to get back to the Device Library. The Hash Number is a unique identifier you will use in certain operations, optionally some times. In the case of frames, there is also a Slots Count field. If you plan to change this info, press the [Edit] button located at the bottom of the page.

The [Existing Devices] button will take you to a list of all devices that have been created from this definition.

It follows the Inputs/Outputs table listing all of the ports showing: Label, Signal Type and Connector Type. Label refers to that bared in the physical equipment. You can change a port information by clicking in the Edit link located in the corresponding row.

In the case of type FRAME, there is usually no ports. Some frames, however, have ports such as Black Burst, Serial and Ethernet.

To add new ports (either input or output), click the [Add Ports] button.

Buttons [Remove Inputs] and [Remove Outputs] will remove all input or output ports respectively. You will be prompted for confirmation before proceeding.

Keep present that you won't be able to make any change if you are not logged in.

----
If you plan to create a device from this definition, you need to navigate to the location (Rack, Desk or Frame Slot) where the device will reside and press the [Add Device] button on that view.
----

It is recommended that you create device definitions as complete as possible. The recommended practice is to use the manufacturer's manual or datasheet as a direct reference. Nevertheless, if the definition is some how incomplete, you will be able to add/modify/delete ports in the actual device created from this definition later on. Changes you make in that device will not impact the definition in any manner.

The Find Box is intended for quick navigation and wire lookup. You can enter things like:

    wire c123
    rack 27
    rack liveu
    frame 31
    room 237
    room color video
    device skype
    device 7700da7
    definition vda

The first word is called "qualifier" and indicates the kind of object you are looking for. The default qualifier is "wire", meaning that you can omit it so that "wire c123" is equivalent to just "c123".

The following qualifiers are recognized:

   bulding
   bld
   room
   rm
   rack
   rk
   desk
   frame
   fr
   device
   dev
   equipment
   eq
   definition
   def
   wire

For wires, you can enter a simplified, non standard, version of the wire number; for example,"c2" instead of "C-002". You can also enter keywords that seem related to the wires you are seeking, for example, "roof cam".

Your entry is memorized in a session variable. You can continue to navigate the system, then return to the same result by just pressing the [Go] button again.

Locations are organized into a hierarchy:

   Buildings
     Rooms
       Racks or Desks
         Frames
           Slots

This hierarchy can be navigated up and down starting at Buildings.

To add a new location to the present list, press the [Add] button. You need be logged in in order to be able to do that.

If delocated devices exists, those will listed at the bottom in this view. See Allocating and Delocating Devices for more info.

A device can not be deleted from the circuit. It must rather be "delocated", using the Delocate button.

The Delocate operation mimics the physical removal of the equipment from the rack. This could be the case, for example, in which you are sending that equipment to the factory for repair.

When delocated, the equipment loses its reference to the location where it belonged, but it keeps all other information such as Serial Number, Designation and History Log. Later on, you will be able to "re-allocate" that device to the location it was in, or maybe a different one.

When you delocate a device, all wires connected to it are disconnected automatically and marked as "dangling" at that location.

Delocated devices are listed at the bottom of the Locations root. You get there by pressing the Locations button in the Toolbar. They can be "re-allocated" to a rack or desk by pressing the [Relloc Device] button in the Rack View, or the "@" link in the Frame View.

------
If you plan to actually DELETE a device, proceed as following:

* Delocate the device as explained.
* Press the Locations button in the Toolbar.
* Select your device from the list of Delocated devices.
* In the Device View, press the Edit button.
* In the Edit Device view, press the [Delete] button.

This page allows for quick wire lookup.

Press the [Dangling] button for a list of wires that are connected in one end only.
Press the [Disconnected] button for a list of wires that are disconnected in both ends.
Press the [Available] button for a list of wire numbers that are not in the database, so available for you to add.

Picking an item from the By Status list will take you to a list of wires presenting the selected status.

----
See Status for more information on what "status" means.

This table lists wires matching your search criteria. The table first appears sort by wire number, but you can re-order by any column by just clicking at that column.

Columns "Connected From" and "Connected To" may contain links to devices this wire connects to. Click on those link to go to the Device View of that device. If not a link, the column content is a textual indication of the referred equipment; that text is in the connection reference string of the wire record.

-----
Note:

If you see a weird date in the "Updated" column (12/31/1969) it means that the wire record has not an updated date at all. In terms of implementation (if you are curious), this database field is a UNIX timestamp; value zero means: just before the "UNIX epoch" (1/1/1970), hence the value 12/31/1969.

Status is an attribute of Wires and Devices representing the current situation of that wire or equipment in real life.

Status values come from a user defined list accessible from button [Entities] then [Status] in the Toolbar. This list contains values such as: Installed, Preliminary, Obsolete, etc. Status are color-coded for easy reference. Colors are user definable as well.

Default Status
--------------

When you add a new wire or device to the system, it comes with a default status (you can change the status later on by editing that device or wire).

The System Default Status is set in the configuration file, but you can change it temporarily for the duration of your session. This is useful, for example, when you are adding multiple wires with status different from the default (for example, "Preliminary").

To set the session Default Status, proceed as following:

* Login.
* Go to [Entities], then [Status].
  Notice that one list element is presented in bold. That is the current Default Status.

* Click the list element for the status you want as default.
  Notice that now your new status is in bold.

The new Default Status will remain until you logout and it is only valid for you, that is, other users accessing the system from other hosts won't be impacted.

This view shows all devices mounted in the rack. Click on the desired row to get the Device (or Frame) View of that device.

On top is the "Loc Navigator" indicating in what Building and Room this rack is located. You can use this tool to navigate back in locations.

Buttons at the bottom act as following:

[Fav +]    Adds this device to "Favorite Devices" in the Home Page.
           If the device is already a favorite, the button will read "Fav--" instead
           in which case, pressing it will remove the device from the list.

[Add Device] Will add a new device to the rack from a Definition you pick from the Library.

[Reloc Device]  Will re-allocate a device that was previously de-allocated.
               (See Allocating and Delocating Devices).

[Edit]  Will take you to the Device Edit form.

Know that you will not be able to use any of these buttons if you are not logged in.

This view represents a Frame, each row representing a Slot.

Empty rows correspond to empty slots while non-empty ones give you a brief description of the device (card) inserted in that slot. Click on it to get its Device View.

The "Do" column reads "Edit" for installed devices, "@ +" for empty slots. Click in the "+" for adding a device to that slot from the Library. Click "@" to relocate a device instead. (See Allocating and Delocating Devices).

If the frame has ports (such as Ethernet or Black Burst), a link appears at the bottom, labeled: "This frame has direct connections". Click on it to get a device view of the frame where those connections are shown.

-----
The [Fav +] button will add this frame to "Favorite Devices" in the Home Page. If the frame is already a favorite, the button will read "Fav--" instead, in which case, pressing it will remove the device from the list.

The [Edit] button will take you the the Frame Edit form you will use to change information to the frame as a whole.

This view represents a device and its connections.

On top is the "Loc Navigator" you can use to navigate back in locations: Building, Room, Rack, Frame.

It follows device information such as Brand and Model. To note here is the "Designation" field; this identifies the role this equipment in particular is playing in the facility. Also interesting is the "Definition"; this is the template from which this device was created (clicking the field value will take you to the Definition view in the Library). And also the "Hash Number"; this is an internal unique identifier you will use occasionally for certain operations.

The IP field shows the IP of that device, if any. Clicking on it will take you to the Web Interface of the equipment, if it exists and is accessible from your computer.

It follows three buttons: [Show All Ports], [History Log] and [Goto Circuit]. We will talk about that later.

-------------------------------------------
Finally is the Inputs/Outputs table.

Each row in the table represents a device port (input or output) to which a wire can be connected. For connected ports, information about the connected wire is also shown. Columns "Connected To" may content either a link to the other end of the wire (another Device View) or just a textual reference in case the wire is not "connected" in Green Book.

You can click in the "CABLE" column to get more information about that wire.

----> You can click in either of the "Connect To" columns to navigate to the other Device (if the cell contains a link), effectively following the circuit path.

Initially, only connected ports are displayed. Hit the [Show All Ports] button to view all ports both connected and disconnected. Now the button reads [Hide discon. Ports] so pressing it again will take you back to the connected-only view.

Button History Log will display the History Log for this device. That place is intended to maintenance notes. The button will present a white background if the log is not empty.

Button Goto Circuit will take you to the circuit in which this device is in (or a list of various if it participates in more than one). It can also lead to nowhere if the device is not in any circuit. If it is, the button will present an orange background. (See: Circuits).

------
Multi-conductor connectors are represented with multiple rows: one per connection. That is the case, for example, of various GPIO or Analog Audio signals exposed in a single DB25 connector.

------
Button Add Ports will allow you to add ports (inputs or outputs) to this device in particular. That will not affect the device definition from which this device was created.

This section has been written ahead of implementation, serving as "spec" rather than actual "manual".

The Search Box is located in the main Tool Bar, accessible all the time. What you enter in that box is basically a command with arguments. Even a sole wire number is a form of command only that most of its elements have been omitted. In the box, you can enter something as simple as this:

    c-123

or as complex as this:

    find (device frame with VDA, wire blue) preliminary at room "Tech Center", MO

Learning the search command format will allow you to obtain more accurate returns in your search results or even to accomplish other tasks such as login and getting help.

A legal command has the following format:

    COMMAND ARGUMENTS

COMMAND is one of the following words:

    find
    set
    login
    logout
    help

'find' is the default command. If no command is given, command 'find' will be assumed.

ARGUMENTS is a sequence of none or more words separate by white spaces. Its format varies depending on the command.

The 'find' command has the following format:

    find OBJECT ARGS JOIN EXPRESSION

as for example:

--> find wire orange at rack RK-27

OBJECT is the kind of element we want in the result. It can be one of the following:

   location
   device
   wire

In the example above, 'wire' is an OBJECT.

ARGS is a list of attributes this object possesses. In the above example 'orange' is an argument referring the wire's color.

The arguments list can be longer, for example:

--> find wire AES orange at rack RK-27

where the second argument, AES, refers to the signal type carried by resulting wires. The Search Engine knows in advance what wire colors, signal types etc. are available, hence it will not get confused.

OBJECT ARGS as a whole comprises what we call an "expression". JOIN is a keyword connecting EXPRESSIONS. Hence, a more generic definition of the find command format is:

   find EXPRESSION JOIN EXPRESSION

In the above example, 'at' is a JOIN connecting the expressions 'wire AES orange' and 'rack RK-27'.

JOIN is one of the following keywords:

    at
    with

The right hand EXPRESSION expresses more specific conditions about the left hand EXPRESSION.

The following examples illustrates the use of the JOIN 'with'.

--> find device frame with VDA 7700ADA
--> find location room with desk

In the first example, we try to find devices of type frame containing devices type VDA model 7700ADA. Again, the Search Engine has knowledge of these words ("frame", "VDA", "7700ADA") and what they mean.

In the second example, we look for rooms having desks inside.

Both, 'at' and 'with', express inclusion but in opposite directions:

    EXP1 at EXP2

means that objects in EXP1 are contained into those of EXP2, while

    EXP1 with EXP2

means that objects in EXP2 are contained into those of EXP1.

We mentioned that 'find' is the default command. This means that we don't actually need to write that word in the Search Box. The following expression is equivalent to our last example:

--> device frame with VDA 7700ADA

Likewise, object names can be omitted if the arguments are not ambiguous. In this example, 'frame' is clearly a device. The following expression yields to the same result:

--> frame with VDA 7700ADA

In general we can always omit the command 'find' and we can also omit the OBJECT in cases when it can be implied from the argument's list. If the omitted object can not be implied, objects of all kinds (location, device, wire) will be returned.

Objects can also be implied by the expression's pattern. That is the case of wire numbers and location numbers.

The following entry:

--> C-123

Is equivalent to this:

--> find wire C-123

because the object 'wire' is directly implied from the argument's format.

Similarly, the following two entries are equivalent:

--> RK-27
--> find location rack RK-27

The following expression,

--> obsolete at rack RK-27

will return all devices and wires with status 'obsolete' found in rack RK-27. This is a case when the object has been omitted and can not be implied from the arguments list.

It follows from the previous discussion that expressions can be reduced to a list of objects (location, device, wire) since, ultimately, they describe nothing but objects. At this point we will add that EXPRESSION JOIN EXPRESSION is also an EXPRESSION. We call this a joint expression.

Joint expressions permits to construct more complex entries, recursively, as, for example:

--> wire orange at frame with device ADA at rack RK-27

This joint expression attempts to find orange wires in all frames located in rack RK-27 that happens to have ADA devices inside.

Notice that the first JOIN (at) defines two expressions, but the one to the right is a joint expression (frame with device...) which is turn contains another joint expression (device ADA at rack RK-27).

We can extend this recursion indefinitely to obtain more accurate results, as long as the expression as a whole makes sense to the user.

Some elements have textual descriptions (strings) we may want to search for, such as "Final DA" or "Roof CAM". By surrounding those strings with quotes, we make clear those are strings proper, not keywords.

Here is an example:

--> FS1 "Roof CAM"

This expression is asking for a device model FS1 which description field is exactly "Roof CAM".

We can omit the quotes, but that may yield to a different result because 'CAM' will be interpreted a as a type of device.

We can also use quotes around keywords such as command or object names to mean they are not keywords but strings. For example,

--> "wire" at RK-27

is asking for any object at RK-27 which description string is exactly "wire". Without quotes, 'wire' would be the wire object.

--> device "preliminary"

will look for a device having the string "preliminary" in its description field, and not for devices which status is 'preliminary'.

If a keyword if found in the "wrong" place, it will be assumed as a single-word quoted string. For example,

--> wire find

will look for wires with the word "find" in its label field, same as:

--> wire "find"

This rule applies to any keyword found in non expected places.

Strings within quotes ask for exact matches. Some times, however, we want to give only a substring of the intended match. The asterisk if employed in these cases, as illustrated in the following example:

--> find device "roof*"

The asterisk (*) represents any possible string placed in its position. In the example, the string "roof cam" will match the inquiry.

Asterisks can be used with or without quotes. The following examples are equivalent to the previous one.

--> find device "roof"*
--> find device roof*

The use of quotes and asterisk together is better justified in cases where the substring contains more that one word, as for example:

--> find device "digital video *"

possibly intended to match "digital video HD" and "digital video SD".

We can place more that one asterisk in the string. For example,

--> find device "*-SDI *PUT"

will match any of the following values:

   SD-SDI INPUT
   SD-SDI OUTPUT
   HD-SDI INPUT
   HD-SDI OUTPUT

Any attribute is of certain "type". For example, a wire argument 'orange' if of type color. In all of the examples seen so far, we have implied the attribute type from its value. However we can write this type explicitly in front of the intended attribute. For example,

--> find wire color orange

This can be useful to disambiguate argument values. Say for instance, we have expressed our status in terms of colors instead of descriptive words. Under this circumstances, the expression

--> wire orange

could express either cables of color 'orange' or with status 'orange'. To disambiguate, we need to preceed the argument with a keyword expressing its type.

--> wire color orange

or

--> wire status orange

The keyword expressing the attribute's type (color, status in the example) is called a qualifier.

Argument types are directly related to the database fields holding the information we look for. Therefor, pertinent qualifiers depends on the object type.

Qualifiers for locations are:

... pending ...

Qualifiers for devices are:

... pending ...

Qualifiers for wires are:

... pending ...

Logical operations AND, OR, NOT apply to elements in any arguments list. For example, we may want to look for wires which status is 'preliminary' and its color is 'orange' (logical AND), or we may want to find wires that are either 'preliminary' or 'orange' (logical OR').

AND is assumed if no other operator is present, meaning that arguments separated just by white spaces are and-ed together. For example,

--> wire AES blue

means objects wire that are both color 'blue' and signal type AES.

The OR operator is denoted with a comma. For example,

--> wire AES, blue

will return all wires that are either color blue or carry AES signals.

The NOT operator is denoted by the keyword 'not' preceding the word. For example,

--> wire AES not orange

means any wire carrying AES signal which color is any but 'orange'.

Logical operators can also appear preceding JOINs in which case they will affect the whole right hand EXPRESSION.

Examples:

--> wire AES not at RK-27

will return all AES wires placed elsewhere except in RK-27.

--> wire AES , at RK-27

will return all AES wires as well as wires of any kind located in RK-27,

--> device frame not with VDA at RK-27 obsolete

will return all frame devices except those marked as obsolete and containing VDA cards.

This section is intended to developers in charge of maintaining the Green Book source code, and it is aimed to help in the understanding of certain implementation concepts.

Notice that, starting on version 0.87, the project was rebranded "Green Book". However, "Circuit Tables" is still the code name for this project, so you will see that name in the source code and internal documentation.

Frames have dual existence: they are locations as well as devices. "Locations", because they hold other locations (slots) so they are including in the locations tree. They are also "devices" because, unlike pure locations, they have device attributes such as: Manufacturer, Model, Serial Number and Ports.

This duality is implemented with separate records: one in the devices table and the other in the locations table. When a frame is created, the two records are created at the same time. They relate to each other by the mean of the field devices.locfr which points to the corresponding locations.locid.

FRAMES is also a built-in Device Type (pre-populated in the devtypes table) which devtyp ID is referred in code by the constant DEVTYP_FRAME defined in script lib_class.php, currently with value 2.

Care is taken in code to prevent the user from deleting that dev type from Entities. In general, built-in database values (those which primary key is less than SEED_ID, currently 101) are restricted from general use.