Merge pull request #24 from CiscoDevNet/dstaudt-macros

Dstaudt macros

Author: dstaudt

labs/collab-xapi-branding/collab-xapi-branding.json

@@ -1,6 +1,6 @@
 {
   "labId": "collab-xapi-branding",
-  "title": "Customizing Collaboration Devices from Code",
+  "title": "Customizing collaboration devices from code",
   "slug": "Learn to customize display logos, signage and custom messages for Cisco Collaboration Devices via SSH, HTTP and Node.js/JavaScript.",
   "time": 20,
   "byod": true,
@@ -37,11 +37,15 @@
   "related": [
     {
       "labId": "collab-xapi-controls",
-      "title": "Creating Custom In-Room Controls and Macros"
+      "title": "Creating custom in-room controls for Cisco collaboration devices"
     },
     {
       "labId": "collab-xapi-intro",
       "title": "Introduction to xAPI for Cisco Collaboration Devices"
+    },
+    {
+      "labId": "collab-xapi-macros",
+      "title": "Exploring xAPI Macros for Cisco collaboration devices"
     }
   ],
   "authors": [

labs/collab-xapi-controls/8.md

@@ -1,18 +1,18 @@
-# Step 8: Creating on-board JavaScript Macros
+# Step 8: Running JavaScript on-device with macros
 
 >Note that this step requires that you can connect to your CE device with an 'administrator' role; 'integrator' role is not authorized to run Macros.
 
 In the previous steps, we brought interactivity to a custom in-room control panel by leveraging the xAPI via a script running on your PC.  Of course, keeping your PC powered on and connected to the local network continuously is not going to work in production!  You could deploy an application server on-site with your device to host the script, however there may be a better option...
 
-CE v9.2.1+ gives you the possibility to deploy custom code to the device itself via the Macro feature.  Essentially, this feature allows JavaScript code to be uploaded and run directly on the collaboration device (hosted in a secure 'sandbox' environment).  This custom code can interact with the device using the exposed `xapi` JavaScript object, just as we experienced earlier with the jsxapi module.  
+CE v9.2.1+ gives you the possibility to deploy custom code to the device itself via the 'macro' feature.  Essentially, this feature allows JavaScript code to be uploaded and run directly on the collaboration device (hosted in a secure 'sandbox' environment).  This custom code can interact with the device using the exposed `xapi` JavaScript object, just as we experienced earlier with the jsxapi module.  
 
 Ideally, code developed on an external app server using jsxapi could be uploaded to run directly on a collaboration device without requiring an external server.  Though, note the macro JavaScript environment has some limitations, including the lack of local file storage, the inability to install additional JavaScript packages via NPM, and restrictions on establishing network connections.
 
 You can learn more about macros in [Part 4 of CE’s Customization Guide](https://www.cisco.com/c/dam/en/us/td/docs/telepresence/endpoint/ce96/sx-mx-dx-room-kit-customization-guide-ce96.pdf)
 
 **Let's see how we can run our previously developed script on-board our device using a macro**
 
-1. Sign in to your device's web interface (as a user with 'administrator' role) and navigate to the **Integration** > **Macro Editor** menu
+1. Sign in to your device's web interface _(as a user with 'administrator' role)_ and navigate to the **Integration** > **Macro Editor** menu
 
 2. The first time the Macro Editor is launched, you are asked to authorize the use of macros
 
@@ -44,16 +44,11 @@ Interact once more with your custom ultrasound panel to confirm everything is wo
 
 ## Going Further
 
-Take some time to explore the various resources provided in the Macro Editor towards the right.
+There is much more to learn about the possibilities of JavaScript macros!  We definitely recommend you try the [Exploring xAPI Macros for Cisco collaboration devices](https://learninglabs.cisco.com/lab/collab-xapi-macros/step/1) lab if your're interested...
 
-You’ll find several tabs with useful links:
-
-- **Introduction**: this tab contains handy code snippets demonstrating how to invoke commands, listen to events and update configuration settings
-- **Examples**: these scripts are organized by use-case, are fully operational, and can be experimented by clicking the **Load Example** button
-- **Tutorial**: this guide is an excellent walk-through to help you in your first steps with the macro framework (the guide is also available online here [CE 9.2.1+ Macros Tutorial](https://github.com/ObjectIsAdvantag/xapi-samples/blob/master/macros/pdf/macro-tutorial.pdf).
 
 To inspire you, we’ve assembled a collection of custom in-room control definition files, macros and Node.js example scripts in this [xAPI samples repo](https://github.com/ObjectIsAdvantag/xapi-samples).
 
 For fun, you might like trying out the xAPI-based [Maze game](https://github.com/ObjectIsAdvantag/xapi-samples/tree/master/controls/maze_levels)
 
-![Maze Game](assets/images/step8-maze-game.png)
+![Maze Game](assets/images/step8-maze-game.png)

labs/collab-xapi-controls/collab-xapi-controls.json

@@ -1,28 +1,28 @@
 {
   "labId": "collab-xapi-controls",
-  "title": "Creating Custom In-Room Controls and Macros",
-  "slug": "Learn how to create custom controls for Cisco Collaboration Devices, using the on-board control simulator tool and the in-room control editor. Then make those controls interactive via a server-based Node.js script, or an on-board JavaScript macro.",
+  "title": "Creating custom in-room controls for Cisco collaboration devices",
+  "slug": "Learn how to create custom in-room controls for Cisco collaboration devices, using the on-board control simulator tool and the in-room control editor. Then make those controls interactive via a PC-based Node.js script.",
   "time": 30,
   "byod": true,
   "files": [
     {
-      "title": "Introduction to In-Room Controls",
+      "title": "Introduction to in-room controls",
       "file": "1.md"
     },
     {
-      "title": "Experience the Simulator",
+      "title": "Experience the simulator",
       "file": "2.md"
     },
     {
-      "title": "Creating Custom In-Room Controls",
+      "title": "Creating custom in-room controls",
       "file": "3.md"
     },
     {
-      "title": "Interacting with Controls from Code",
+      "title": "Interacting with controls from code",
       "file": "4.md"
     },
     {
-      "title": "Updating your device's Configuration",
+      "title": "Updating your device's configuration",
       "file": "5.md"
     },
     {
@@ -34,7 +34,7 @@
       "file": "7.md"
     },
     {
-      "title": "Creating Macros",
+      "title": "Running JavaScript on-device with macros",
       "file": "8.md"
     }
   ],
@@ -49,11 +49,15 @@
   "related": [
     {
       "labId": "collab-xapi-branding",
-      "title": "Customizing Collaboration Devices from Code"
+      "title": "Customizing collaboration devices from code"
     },
     {
       "labId": "collab-xapi-intro",
-      "title": "Introduction to xAPI for Cisco Collaboration Devices"
+      "title": "Introduction to xAPI for Cisco collaboration devices"
+    },
+    {
+      "labId": "collab-xapi-macros",
+      "title": "Exploring xAPI Macros for Cisco collaboration devices"
     }
   ],
   "authors": [

labs/collab-xapi-intro/1.md

@@ -46,7 +46,7 @@ In January 2017, CE9.2 introduced customizable **in-room controls**. In-room con
 
 In November 2017, CE9.2.1 took the customization possibilities further, with the introduction of **branding** and **halfwake** display features, while also introducing a powerful **macro** engine. Macros provide a JavaScript run-time environment on board the collaboration device itself, where code that can automate or change parts of the video endpoint behavior can run - avoiding the need to deploy a separate application server. Since both the device itself and any connected peripherals can be controlled from the Touch10 or DX series user interface, users get a consistent experience throughout the meeting room.
 
-In-room controls and macros are explored in the [Creating custom In-Room Controls](https://learninglabs.cisco.com/lab/collab-xapi-controls/step/1) and [On-device macros for room devices](TBD) learning labs.
+In-room controls and macros are explored in the [Creating custom in-room controls and xAPI apps](https://learninglabs.cisco.com/lab/collab-xapi-controls/step/1) and [Exploring on-board xAPI Macros for Cisco collaboration devices](https://learninglabs.cisco.com/lab/collab-xapi-macros/step/1) learning labs.
 
 ### Node.js xAPI library for JavaScript: jsxapi
 

labs/collab-xapi-intro/5.md

@@ -149,6 +149,28 @@ The scope of events you receive can be narrowed or widened depending on the 'pat
 
 Try entering `xfeedback register /Status` to listen to all status changes, or simply `xfeedback register /` to listen to every type of event, systemwide. Then perform various interactions with your device such as turning up or down the volume, or initiating a call. As the xfeedback events can get pretty numerous/verbose, make sure to type `xfeedback deregisterall` to turn off all event registrations when you're finished.
 
+### USB device events
+
+If your system is running CE 9.6+, you can plug a USB keyboard into the device's base (Room and DX series) and receive events corresponding to key press/release activity:
+
+1. Enable USB device event detection by logging into your device via SSH and running the following command:
+
+    ```shell
+    xConfiguration Peripherals InputDevice Mode: On
+    ```
+
+2. Type a few keys on the connected keyboard and you should see 'Key' (key identifier), 'Code' (numerical key code), and 'Type' (pressed or released) events appearing in the terminal:
+
+    ```shell
+    *e UserInterface InputDevice Key Action Key: KEY_O
+    *e UserInterface InputDevice Key Action Code: 24
+    *e UserInterface InputDevice Key Action Type: Pressed
+    ** end
+    *e UserInterface InputDevice Key Action Key: KEY_O
+    *e UserInterface InputDevice Key ActionCode: 24
+    *e UserInterface InputDevice Key Action Type: Released    
+    ** end
+    ```
 **Congrats, you've just learned about Cisco collaboration device programmability!**
 
 In essence, the xAPI is a bi-directional interface that lets you check your device state, modify configuration settings, register for real-time events, and take actions by sending commands.

labs/collab-xapi-intro/collab-xapi-intro.json

@@ -49,11 +49,15 @@
   "related": [
     {
       "labId": "collab-xapi-branding",
-      "title": "Customizing Collaboration Devices from Code"
+      "title": "Customizing Cisco collaboration devices from code"
     },
     {
       "labId": "collab-xapi-controls",
-      "title": "Creating Custom In-Room Controls and Macros"
+      "title": "Creating Custom in-room controls for Cisco collaboration devices"
+    },
+    {
+      "labId": "collab-xapi-macros",
+      "title": "Exploring xAPI Macros for Cisco collaboration devices"
     }
   ],
   "authors": [

labs/collab-xapi-macros/1.md

@@ -0,0 +1,84 @@
+# Exploring on-board xAPI Macros for Cisco collaboration devices
+
+## Objectives
+
+Learn about the JavaScript 'macro' capabilities for running custom code onboard Cisco CE collaboration devices.
+
+In this lab you will learn about the use-cases, capabilities and limitations of macros, including hands-on deploying and coding a few simple sample macro applications:
+
+* Deploy and run a simple macro app
+* Experiment with a macro application interacting with CE device custom in-room controls
+* Make external HTTP API requests from macro code
+
+## Prerequisites
+
+* A Cisco collaboration device with the following requirements:
+  - Cisco DX, SX (except SX10), MX, RoomKit, or Webex Board
+  - Running the _Cisco Collaboration Endpoint CE v9.6+_ version of software
+  - Registered to the Cisco Webex cloud platform, or to an on-premise Cisco Unified Communications Manager (CUCM) or Cisco Video Control Server (VCS) 
+
+  Alternatively, you can use one of the [RoomKit Sandboxes](https://github.com/CiscoDevNet/awesome-xapi#sandboxes) offered to DevNet community members free of charge.
+
+* Admin credentials to your device, if it's on-premise registered. If cloud-registered, you need admin access to the [Control Hub](https://admin.webex.com/login) of the organization to which your device blongs.
+
+* Laptop with local or VPN IP connectivity to your device, and the following software tools, recommended:
+  - SSH: Mac/Linux (built-in); Windows - [PuTTY](https://www.putty.org/)
+
+**We recommend that you complete the following labs prior to attempting this one:**
+
+* [Introduction to xAPI for Cisco collaboration devices](https://learninglabs.cisco.com/lab/collab-xapi-intro/step/1)
+* [Customizing collaboration devices from code](https://learninglabs.cisco.com/lab/collab-xapi-branding/step/1)
+* [Creating custom in-room controls and xAPI apps](https://learninglabs.cisco.com/lab/collab-xapi-controls/step/1)
+
+## Step 1: About CE customization with xAPI
+
+If you’re new to CE device customization and xAPI, here are a few starting points:
+
+- Your Cisco collaboration device includes an API - known as **xAPI** - that allows bi-directional communication with third-party applications and control systems, such as those from AMX or Crestron
+- There are multiple ways to access xAPI: Telnet/SSH, HTTP, RS-232 serial connection, and via JavaScript using the jsxapi package. Regardless of the method you choose, xAPI has the same general format and behaves similarly
+- In this lab, we’ll focus on running jsxapi based applications using macros
+
+![Big picture](assets/images/step1-macroarchitecture.png)
+
+>Note: the exact set of customization and xAPI features and supported devices vary depending on the model and version of CE. Please check the [Cisco TelePresence CE software Release Notes](https://www.cisco.com/c/dam/en/us/td/docs/telepresence/endpoint/software/ce9/release-notes/ce-software-release-notes-ce9.pdf) for the complete list of supported devices.
+
+### Macro overview
+
+In November 2017, CE 9.2.1 introduced a powerful **macro** engine for on-premise devices. Macros provide a JavaScript run-time environment on board the collaboration device itself, where code that can automate or change parts of the video endpoint behavior can run - avoiding the need to deploy a separate application server or have users interact with a separate control system or UI beyond the collaboration devices standard (extensible) interface (Touch10 or DX on-screen.)
+
+CE 9.6 extended macro functionality to cloud-registered devices, as well as adding HttpClient capabilities for interacting with external REST-like APIs.
+
+![Macro in action](assets/images/step1-macro-deployed.png)
+
+### Node.js xAPI library for JavaScript: jsxapi
+
+In January 2018, the 'jsxapi' Node.js package was [released on npm](https://www.npmjs.com/package/jsxapi), and via an [opensource project on GitHub](https://github.com/cisco-ce/jsxapi). This library wraps xAPI functionality in an easy-to-use Node.js package for server-side JavaScript developers.
+
+The on-board JavaScript runtime environment for macros provides and exposes this jsxapi package for use by scripts, with functionality identical to the NPM package.  Apps written for server-side Node.js using jsxapi should be easily portable to the macro environment with minimal changes (notwithstanding the caveats below...)
+
+### Macro environment limitations
+
+While collabation devices have powerful onboard CPU processing capabilities, it is important that these devices protect resources needed to run the high-quality video and collaboration functions they were designed for.  As a result, the macro runtime environment for onboard JavaScript apps has some important limitations for security and performance assurance:
+
+* No access to local storage or file systems
+* No ability to install external packages into the JavaScript environment (e.g. via NPM)
+* Certain limitations on the number of macros configurable, memory available, and CPU usage
+* No access to native JavaScript networking capabilities, with the exception of:
+* HttpClient functionality, which is limited to POST/PUT and response status code only (more on this in a bit)
+
+>Interesting fact: the macro runtime environment is based on the [Duktape](https://duktape.org/) embeddable JavaScript engine
+
+### xAPI documentation
+
+For more details about installation, configuration and extensibility via xAPI, refer to these guides:
+
+- [Docs for DX70 and DX80](http://www.cisco.com/go/dx-docs)
+- [Docs for MX Series](http://www.cisco.com/go/mx-docs)
+- [Docs for SX Series](http://www.cisco.com/go/sx-docs)
+- [Docs for Room Series (RoomKit and Codec Plus)](http://www.cisco.com/go/roomkit-docs)
+- [Docs for Webex Boards](https://www.cisco.com/c/en/us/support/collaboration-endpoints/spark-board/tsd-products-support-series-home.html)
+- [Getting Started Guide](https://www.cisco.com/c/dam/en/us/td/docs/telepresence/endpoint/ce95/dx70-dx80-sx10-sx20-sx80-mx200g2-mx300g2-mx700-mx800-room-kit-getting-started-guide-ce95.pdf) for DX, MX, SX, and Room Series
+
+Note that these guides primarily apply to on-premise registered devices - cloud registered devices may support a more limited set of features depending on model CE version. We’ll cover some of these differences in the next sections. For now, note that you’ll find additional documentation for cloud-registered devices at [Collaboration Help](https://collaborationhelp.cisco.com/article/en-us/jkhs20).
+
+To keep up to date with CE and xAPI developments, you may want to check the [Cisco Collaboration Endpoint software - CE9 release notes](https://www.cisco.com/c/dam/en/us/td/docs/telepresence/endpoint/software/ce9/release-notes/ce-software-release-notes-ce9.pdf) on a regular basis.