summary | shortlog | log | commit | commitdiff | tree
raw | patch | inline | side by side (parent: bcf2c02)
raw | patch | inline | side by side (parent: bcf2c02)
author | Thomas Potthast <tpotthast@ti.com> | |
Wed, 3 Aug 2011 20:13:48 +0000 (15:13 -0500) | ||
committer | Thomas Potthast <tpotthast@ti.com> | |
Wed, 3 Aug 2011 20:13:48 +0000 (15:13 -0500) |
Signed-off-by: Thomas Potthast <tpotthast@ti.com>
README | patch | blob | history |
index 3ee643e3e7c2588eaedf2ffabe9f3891fc85270f..3335512935ce0363ddf6c0294c3219ee001c1491 100644 (file)
--- a/README
+++ b/README
-//******************************************************************************
-//+--------------------------------------------------------------------------+**
-//| **** |**
-//| **** |**
-//| ******o*** |**
-//| ********_///_**** |**
-//| ***** /_//_/ **** |**
-//| ** ** (__/ **** |**
-//| ********* |**
-//| **** |**
-//| *** |**
-//| |**
-//| Matrix GUI v2 |**
-//| OVERVIEW |**
-//| Matrix GUI v2 is a replacement for the original Matrix GUI that |**
-//| shipped with the TI SDK. Whereas the previous version was written in C |**
-//| and built on Qt, Matrix GUI v2 is written almost entirely in javascript. |**
-//| It also offers several improvements over its predecessor: |**
-//| 1) Remote Access. Matrix Gui v2 may be remotely accessed from any |**
-//| computer on the same network as the board on which it is running. |**
-//| When remotely accessed, Matrix GUI may be used to launch apps, |**
-//| view their descriptions, and stream text output back to the |**
-//| remote user. |**
-//| 2) Simplicity of adding apps. Adding an app to Matrix GUI v2 is as |**
-//| simple as dragging and dropping a file into a directory. Matrix |**
-//| GUI v2 scans the apps directory and dynamically builds app lists, |**
-//| eliminating the need for human maintained lists. |**
-//| 3) Portability. Matrix GUI v2 is written in Javascript and built on |**
-//| nodejs. Thus, it will run on any platform that supports nodejs |**
-//| without needing to be modified or compiled. Its client portion |**
-//| will run in nearly any modern browser supporting HTML5 and |**
-//| Javascript. |**
-//| |**
-//| ARCHITECTURE |**
-//| Matrix GUI v2 is designed around a client-server model more commonly |**
-//| associated with a web site. This is what allows remote access from web |**
-//| browsers using the same code that it uses when it is running locally. |**
-//| |**
-//| SERVER |**
-//| The server portion of matrix is made up of server.js and the files |**
-//| in the lib/ folder in matrix root. It is responsible for: |**
-//| 1) Parsing manifest files. Manifest files are based on the desktop |**
-//| entry standard maintained by freedesktop.org. The spec may be |**
-//| http://standards.freedesktop.org/desktop-entry-spec/latest/ |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
-//| |**
+ ****
+ ****
+ ******o***
+ ********_///_****
+ ***** /_//_/ ****
+ ** ** (__/ ****
+ *********
+ ****
+ ***
+
+ __ __ _ _ _____ _ _ _____ ___
+ | \/ | | | (_) / ____| | | |_ _| |__ \
+ | \ / | __ _| |_ _ __ ___ __ | | __| | | | | | __ __ ) |
+ | |\/| |/ _` | __| '__| \ \/ / | | |_ | | | | | | \ \ / // /
+ | | | | (_| | |_| | | |> < | |__| | |__| |_| |_ \ V // /_
+ |_| |_|\__,_|\__|_| |_/_/\_\ \_____|\____/|_____| \_/|____|
+ ___ _
+ | |_ _ __ _ _ |_) _ _|__|_|_ _ _ _|_
+ | | |(_)|||(_|_> | (_) |_ |_| |(_|_> |_
+
+
+OVERVIEW
+ Matrix GUI v2 is a replacement for the original Matrix GUI that
+shipped with the TI SDK. Whereas the previous version was written in C
+and built on Qt, Matrix GUI v2 is written almost entirely in javascript.
+It also offers several improvements over its predecessor:
+ 1) Remote Access. Matrix Gui v2 may be remotely accessed from any
+ computer on the same network as the board on which it is running.
+ When remotely accessed, Matrix GUI may be used to launch apps,
+ view their descriptions, and stream text output back to the
+ remote user.
+ 2) Simplicity of adding apps. Adding an app to Matrix GUI v2 is as
+ simple as dragging and dropping a file into a directory. Matrix
+ GUI v2 scans the apps directory and dynamically builds app lists,
+ eliminating the need for human maintained lists.
+ 3) Portability. Matrix GUI v2 is written in Javascript and built on
+ nodejs. Thus, it will run on any platform that supports nodejs
+ without needing to be modified or compiled. Its client portion
+ will run in nearly any modern browser supporting HTML5 and
+ Javascript.
+
+ARCHITECTURE
+ Matrix GUI v2 is designed around a client-server model more commonly
+associated with a web site. This is what allows remote access from web
+browsers using the same code that it uses when it is running locally.
+
+SERVER RESPONSIBILITIES
+ The server portion of matrix is made up of server.js and the files
+in the lib/ folder in matrix root. It is responsible for:
+ 1) Parsing manifest files. Manifest files are based on the desktop
+ entry standard maintained by freedesktop.org. The spec may be
+ found at http://standards.freedesktop.org/desktop-entry-spec/latest/,
+ and a full description of Matrix's implementation may be found
+ later in this document.
+ 2) Generating application description pages. Each application may
+ specify a html file that contains a description of the application.
+ The contents of that file will be displayed to the user before the
+ application is run. The server is responsible for fetching this file
+ and optionally formatting it when it is requested by the client.
+ 3) Launching applications. The server will launch an application when
+ it recieves a request that includes a proper application ID in the
+ URL. An application ID is simply the Base64 encoded path to the
+ application's manifest. If the ID decodes and points to a proper
+ manifest, it will be parsed and the executable to which it points
+ launched. A run ID will then be generated and returned to the client
+ in JSON format.
+ 4) Capturing application output. When an application is started, its
+ output to stdout and stderr are captured and placed into a text file.
+ The contents of the text file and the application's status (running/
+ not running) may be requested by the client and will be provided by
+ the server.
+ 5) Cacheing. The Server will store generated app lists, description lists,
+ and individual description pages in a folder in the filesystem once
+ they are generated. This is done because many actions involve
+ significant I/O, and it is far more efficient to read one cache file
+ then to reread all manifests for each run. This is done transparently
+ to the client.
+ 6) Loading static files. The server will fetch static resources as neeed
+ by the client. These resources include images, icons, static HTML, and
+ JavaScript. This is necessary to load the client to the user's web
+ browser and for application images to display.
+SERVER USAGE
+ Interacting with the server is done via http requests. It recognizes
+several URLs as being special, and maps its responsibilities to them. If
+the URL has no special action associated with it, it is assumed to be a
+request for a static file from the root of the matrix directory. A table of
+special URLs is below. If a url requires a parameter, it is stated.
+ _____________________________________________________________________________
+ | URL | Parameter | Description |
+ |-------------------|-------------|-------------------------------------------|
+ | /applist/ | Submenu | Will generate a JSON list of all |
+ | | | applications, filtered by the submenu. |
+ | | | Usage: /applist/ , /applist/${SUBMENU} |
+ |-------------------|-------------|-------------------------------------------|
+ | /appdescriptions/ | None | Generates a list of all application |
+ | | | descriptions, JSON formatted and indexed |
+ | | | by application name. |
+ | | | Usage: /appdescriptions/ |
+ |-------------------|-------------|-------------------------------------------|
+ | /app/ | App ID | Generates the app description page for a |
+ | | | single app. This is done by combining |
+ | | | the HTML of the app page with a header. |
+ | | | App ID is the Base64 encoded path to the |
+ | | | application's manifest. |
+ | | | Usage: /app/${BASE64_ENCODED_PATH} |
+ |-------------------|-------------|-------------------------------------------|
+ | /launch/ | App ID | Launches an application with the given |
+ | | | app ID. It then returns a JSON object |
+ | | | containing the run id, the location of |
+ | | | the running file (a file that only exists |
+ | | | while the application is running), and |
+ | | | the location of the application's output |
+ | | | file (a text file with the contents of |
+ | | | stdout and stderr). |
+ | | | Usage: /launch/${BASE_64_ENCODED_PATH} |
+ |-------------------|-------------|-------------------------------------------|
+ | /output/ | Run ID | This gives the plain text contents of the |
+ | | | output file for the application run. Note |
+ | | | that App IDs and Run IDs are completely |
+ | | | different. Run IDs are randomly generated |
+ | | | 20 character alphanumeric strings that |
+ | | | have no other meaning. |
+ | | | Usage: /output/${RUN_ID} |
+ |-------------------|-------------|-------------------------------------------|
+ | /appstatus/ | Run ID | Determines whether or not an application |
+ | | | is running and gets its output. This is |
+ | | | then JSON encoded and returned. The run |
+ | | | ID is the same as above. |
+ | | | USAGE: /appstatus/${RUN_ID} |
+ |-------------------|-------------|-------------------------------------------|
+ | /icons/ | Icon Path | Fetches and loads an icon from the |
+ | | | filesystem. It first checks the matrix |
+ | | | directory to see if the icon path is |
+ | | | there, and if not treats the path as |
+ | | | from the root of the filesystem. It is |
+ | | | not base64 encoded. Note that it will |
+ | | | only serve up an icon with a valid |
+ | | | extension: .png, .jpg, or .svg. |
+ | | | Usage: /icons/path/to/icon.png |
+ |-------------------|-------------|-------------------------------------------|
+ | /clearcache/ | None | Deletes the on disk cache used by Matrix. |
+ | | | This means that everything will be |
+ | | | regenerated the next time it is |
+ | | | requested. |
+ | | | Usage: /clearcache/ |
+ |___________________|_____________|___________________________________________|
+CLIENT RESPONSIBILITIES
+ The client is responsible for sending requests to the server and handling
+user input. Unlike the server, which is designed to be a singleton, many
+instances of the client may exist. The client requests the app list from the
+server when it is loaded, processes it and shows the icons to the user (icons
+which it requests from the server) and waits for user interaction. If the user
+clicks a