Tag Archive: getting started

The Outputs on the JNIOR can be controlled via the JnrWebsocket protocol.  These commands are sent using the Control Message.

Each “Control” message must contain a “Command” member which may be one of the following valid values:

• “Toggle”
• “Close”
• “Open”
• “Reset Latch”
• “Reset Counter”
• “Reset Usage”

Each “Control” Message must contain a numeric “Channel” member specifying the input/output channel. This parameter is 1-based where the number ‘1’ specifies either the first Digital Input or first Relay Output. This depends on the specific “Command”.

There is no formal response to these command messages although a “Monitor” message will invariably follow some for obvious reasons.

Toggle Command

Close Command

Open Command

The built-in functions are great, but sometimes you want to have custom logic running on the JNIOR.  This is a huge benefit of the JNIOR and being able to communicate directly with those applications from a web interface is uniquely powerful.  To take advantage of this feature we must have a unique ID assigned to the application we wish to communicate with.  The web application must make the first communication attempt to that application ID using the Post Message command.  Once that command has been sent, JANOS will subscribe this connection to receive further Reply Message messages from the Java application.  Application IDs must be greater than 1024 and must be unique.

Post Message

We use Post Message to send data from the Web Application to the Java Application.  JANOS will place the Content of the message on the internal Message Pump.  Each Java Application running on the JNIOR will examine the application ID associated with the message.  If the application owns the ID then the application will process the message.

    var message = { Message: 'status.get' };
    jnrwbsocket.postMessage(2010, message);

The above is an example of getting the status from the application when the web application first launches.  Again, this message will cause JANOS to subscribe the WebSocket connection to receive future Reply Messages from this application ID.

Note: You will receive all Reply Message messages from this application.  Even if it is a reply to another WebSocket connections message.  care must be given if you don’t want this to happen.

{{ctrl.getFunctions()}}

Functions

Here is an overview of the available Registry Functions:

• readRegistryKey (keyName, callback) – Executes the callback when the given registry key’s value is retrieved from the JNIOR
• value = readRegistryKeyAsync (keyName) – Gets the value of a registry key.  Since this function is a async function, it will wait for the result before returning.
• readRegistryKeys ([keyArray], callback) – Executes the callback when the given registry key’s values are retrieved from the JNIOR
• registrySubscription (key, callback) – Executes the callback when the given registry key’s value is retrieved from the JNIOR. The callback is also executed any time there is an update to that registry key value

Read Registry Key

Reading a Registry Key is an asynchronous operation.  We don’t want our page to wait for the response, even though it will be quick.  So again, we need to supply a callback.  Our method syntax is readRegistry(keyName, callback);

This may cause you to structure your application differently if you are waiting for one key’s value before executing another code.

Syntax

// With Callback Function
readRegistryKey (keyName, callbackFn)

// With Inline Callback 
readRegistryKey (keyName, function(keyName, value){ /* ... */ })

Parameters

keyName – string – The name of the registry key that we want the value of

callbackFn – function – The function to execute when the value is returned. This can be a reference to a function or an inline anonymous function.

        keyName – string – The name of the registry key being returned

        value – string – The value of the registry key being returned

Return Value

None

Example

    jnrWebsocket.readRegistry( '$SerialNumber', function (keyName, value) {
        this.serialNumber = value;
        alert('The Serial Number is: ' + this.serialNumber);
    });

Read Registry Key Async

It would be easier if we could wait for the response without supplying a callback.  Well, now we can for a single key request.  We will call the readRegistryKeyAsync() method.  But it does involve a little more care.  The use of async / await will help us do that.  The await operator must be used in a async method.  It cannot be used in a normal method.  Here is how we would do that.

Syntax

value = readRegistryKeyAsync (keyName)

Parameters

keyName – string – The name of the registry key that we want the value of

Return Value

value – string – The value of the registry key being returned.  Applies to the Async version only.

Example

        var getJniorInfo = async function () {
            console.log('serial: ' + await jnrwebsocket.readRegistryKeyAsync('$serialnumber'));
            console.log('model: ' + await jnrwebsocket.readRegistryKeyAsync('$model'));
            console.log('boot time: ' + await jnrwebsocket.readRegistryKeyAsync('$boottime'));
        };

        jnrwebsocket.addOnLoggedInListener(getJniorInfo);

Read Registry Keys

More than likely you will need to read more than one key.  Currently, we have the following code where an array of registry keys is supplied.  The callback is then executed for each key and value returned. 

    var registryKeys = ['$serialnumber', '$model', '$boottime'];
    jnrwebsocket.readRegistryKeys(registryKeys, function (key, value) {
        if ('$serialnumber' == key) SerialNumber = value;
        else if ('$model' == key) Model = value;
        else if ('$boottime' == key) BootTime = value;
    });

In this case, the callback gives you the value but you have work to do to assign or use it correctly.  The real benefit comes in when thought is given to the jnior and the amount of communication that goes on.  It is better to send one request and get one response.  The savings go up with the number of keys requested.

Can this be handled better on the client side?  I’m sure it can.  But how?

What if the callback returned an object of key : value pairs?

    var registryKeys = ['$serialnumber', '$model', '$boottime'];
    jnrwebsocket.readRegistryKeys(registryKeys, function (keys) {
        SerialNumber = keys['$serialnumber'];
        Model = keys['$model'];
        BootTime = keys['$boottime'];
    });

Registry Subscription

Hey, a registry key may change sometime in the future.  I want to know when that happens.  Do I have to keep asking to find out if this happens?

No, you don’t.  You need to only subscribe to the registry key.  Let JANOS and the JNIOR do the rest.  JANOS will keep track of the connection that cares about the registry update and alert it accordingly.

The method declaration and use mimic that of the readRegistryKey() method with the only change being that the callback will get called any time that the registry key changes.

Example HTML File

<html>

<head>
    <script src="Integ/comm.js"></script>
    <script src="Integ/md5.js"></script>
    <script src="Integ/base64.js"></script>
    <script src="Integ/jnrWebsocket.js"></script>

    <script>
        var jnrwebsocket = new JnrWebsocket();
        jnrwebsocket.connect('ws://10.0.0.155');
        jnrwebsocket.enableCommLogging();
        jnrwebsocket.addOnLoggedInListener(function () {

            /** Below is an example of using a callback function called readRegistryKey that gets
            executed when the result of the registry is read from the JNIOR. The parameter for this
            function is the name of the registry key you wish to read. The value returned is the
            value of the registry key. This example reads the registry key $SerialNumber from the
            JNIOR. */
            jnrwebsocket.readRegistryKey('$SerialNumber', function (keyName, value) {
                var serialNumber = value;
                console.log(serialNumber);
            });

            /** Below is an example of using a callback function called readRegistryKeys that gets
            executed when the result of mulitple registry keys are read from the JNIOR. The parameter
            for this function is and array of registry keys you wish to read. The values returned are
            the values of the registry keys. This example reads the registry keys $SerialNumber,
            $Model, and $BootTime from the JNIOR. */
            var registryKeys = ['$SerialNumber', '$Model', '$BootTime'];
            jnrwebsocket.readRegistryKeys(registryKeys, function (keys) {
                console.log(keys['$serialnumber']);
                console.log(keys['$model']);
                console.log(keys['$boottime']);
            });

            /** Below is an example of using a Async function called readRegistryKeyAsync that blocks
            and waits to execute until the result of mulitple registry keys are read from the JNIOR. 
            The parameter for this function is and array of registry keys you wish to read. The values
            returned are the values of the registry keys. This example reads the registry keys 
            $SerialNumber, $Model, and $BootTime from the JNIOR. */
            (async function () {
                console.log('serial: ' + await jnrwebsocket.readRegistryKeyAsync('$SerialNumber'));
                console.log('model: ' + await jnrwebsocket.readRegistryKeyAsync('$Model'));
                console.log('boot time: ' + await jnrwebsocket.readRegistryKeyAsync('$BootTime'));
            });

        });
    </script>
</head>

</html>

All WebSocket connections must be authenticated. The Web Server has a login as part of its functionality. The WebSockets use that login state since the WebSockets is part of the web server. If the login was handled separately we would see a double login. One login to load the html and another to access the websocket connection.

So, if a WebSocket connection is initialized from a page that was fetched from the protected area in the web server and the user logged in, then the WebSocket GET response will contain an AUTH cookie

If an additional login is required then the WebSocket connection will return a 401 Unauthorized response. The JnrWebsocket library will attempt to log in with the default credentials. If you do not want that to happen then please change the default credentials. That is strongly recommended anyway.  You can also remove the default credentials from the javascript library by issuing the setCredentials(username, password) method.  Calling this method and providing undefined for either or both arguments with disable the use of the default login.

    jnrwebsocket.setCredentials(undefined, undefined);

The OnLoggedIn listener is where you should do any initial work that you want to get done when the connection is established. For example, if you want to read some registry keys when the page loads, you will do it when the JnrWebsocket gets authenticated. The reads would fail if you tried to perform them before the connection has authenticated.

The web browser helps make a WebSocket connection easy.

Built-in WebSocket Service

Once a connection to a configured Web Server port (default 80 and 443) is made and upgraded from the default HTTP Protocol to the WebSocket Protocol, traffic must conform to the WebSocket specification. Except in the case discussed in Section 3.2 the JANOS Web Server uses a built-in server to handle all WebSocket messages then received. These must use the JSON format and the connection must be authenticated.

To initialize communications the client should send a blank or empty message. The following is acceptable.

{
  "Message":"" 
}

The connection will proceed depending on the authentication requirements established by the JNIOR configuration and the environment making the connection (browser, application, etc.).

Default Permissions

The Series 3 JNIOR (Models 310, 312, and 314) were shipped where by default web pages were not protected by login. The login requirement encountered when running the applets was the result of security in the JNIOR Protocol. Access to web pages could be controlled by permissions set on individual files or folders. For instance, removing the read attribute (R) from the /flash/www folder would force the browser to ask for login credentials and thus protect the pages. Unfortunately, a second login would then be required by the JNIOR Protocol which has to be separately protected since control and configuration were possible through it. Modifying folder permissions involved a console command (CHMOD) which tended to be unfamiliar to everyone.

The Series 4 JNIOR (Models 410, 412, and 414) use a new Registry key WebServer/Login to control web page access. This key by default is set to TRUE. The dynamic configuration pages therefore also request login credentials but a second login is not required due to the Websocket Protocol implementation which will be discussed in a moment. The WebSocket Protocol replaces the JNIOR Protocol just as the dynamic configuration pages replace the applets that have been dropped. You may still control access to areas of the JANOS website using file and folder permissions if desired. That would only be necessary should you disable the WebServer/Login requirement.

WebServer Login Enabled

With the Web Server Login requirement enabled any access to the JANOS website is challenged using the standard 401 Unauthorized response. The JANOS Web Server provides the necessary parameters so the browser can request the user’s login credentials. If the proper credentials are entered and verified by JANOS the page is promptly served. A session ID is assigned.

Subsequently, the Authorization information is supplied with requests for other pages required from the website. The JANOS Web Server recognizes the association between those credentials and the original login and therefore doesn’t challenge every page. When the browser then moves to open a WebSocket connection it uses the temporary session ID for authentication. A second is not required. This can be done because all of these connections are handled by the Web Server. This is unlike the JNIOR Protocol which is a separate server entirely and cannot be passed shared authentication information.

Once you have authenticated for the website, you can create WebSocket connections in the browser session without an additional login step. Immediately after opening the WebSocket connection, you will receive a “Monitor” message and you are good to go.

WebServer Login Disabled

If you set the WebServer/Login key to FALSE and assuming that permissions on files and folders have not been modified retaining the default Read Access flag, the browser will not need to request your login credentials. When a WebSocket is then made there are no preauthorized credentials. The login handshake in the WebSocket connection will be required before you may proceed using the WebSocket. This behavior assumes that the Websocket/Anonymous registry key has not been defined or is set to 0.

Upon opening the connection a “monitor” message will not be provided. The application needs to send a blank message and will receive the 401 Unauthorized error. The application will then need to request the user’s credentials and calculate the Auth-Digest response on its own. This is the same procedure performed by the browser. The dynamic configuration pages supplied with the JNIOR provide for this requirement. The Javascript can be used for reference.

Once the user credentials are processed the handshake can be completed and will proceed as follows.

{
  "Message":"" 
}

{
  "Message":"Error",
  "Text":"401 Unauthorized",
  "Nonce":"5d894efb48e1c3bc074fe78e7a5f" 
}

{
  "Auth-Digest":"jnior:65f2d1cb66ef63f7d17a764f3a2f2508" 
}

{
  "Message":"Authenticated",
  "Administrator":true,
  "Control":true
}

A “Monitor” message will likely immediately follow. This might even be received before the “Authenticated” message. That is the asynchronous nature of the connection. Please feel free to contact INTEG for assistance in implementing the digest calculation.

Anonymous Operation

If the Websocket/Anonymous registry key is set to a valid user ID (1 is generally the JNIOR Administrator’s ID), then no login will be required. The USERS console command can be used to determine the available user IDs. This, however, is extremely dangerous. Any application can then make a fully functional WebSocket connection. This gives anyone access to the unit with the ability to raise havoc with controls and to modify JNIOR configuration. This is not recommended. If there is physical security, meaning that access is only available to personnel on the local network and all those can be trusted, then this setting may be of use. Otherwise, you are allowing anonymous access to this connection at your own risk.

It is important to note that even if you have WebServer/Login set to TRUE and have to enter a username and password to bring up the website, the WebSocket interface is not secure if anonymous access is enabled. A separate application or copy of the website can get full control of your JNIOR.

With the anonymous key set to a valid user ID, the WebSocket connection will not require login. Immediately after making the connection you will receive the “Monitor” message. The connection is then available for full use.

Easily create your own Web Apps to interact with the JNIOR! The JNIOR WebSockets JavaScript Library is just what the name suggests. It is a library written in Javascript that will aid you in interacting with the JNIOR’s WebSocket Server. The WebSocket server provides access to all of the internal features on the JNIOR including access to the I/O, registry, and file system. You can even pump messages directly to Java applications running on the JNIOR.

The JANOS Web Server listens for connections from clients that are running one of the many popular browser programs. Typically ports 80 and 443 (for secure TLS/SSL communications) are open for connection although those are configurable through the JNIOR Registry. In addition to the default HTTP Protocol a connection may also utilize the Websocket Protocol as described in this document. The Web Server ports are shared by these two protocols. This provides for access to status information and control commands that previously were only available through the JNIOR Protocol. While the JNIOR Protocol remains a viable option for these functions the Websocket approach offers seamless integration into the dynamic web page environment. This capability is new to the Series 4 JNIOR products (Models 410, 412, and 414).

The library discussed below is designed to help you interact with the JNIOR WebSocket server more easily and at a higher level. You can write the web-socket code yourself if you like.

Background

To remotely control the JNIOR you need the ability to obtain I/O status and to affect changes in I/O condition. In the earlier Series 3 JNIOR, this was accomplished through the JNIOR Protocol made available through a TCP/IP connection typically on port 9200. This is a documented binary protocol that requires special programming external to the JNIOR for its use. Care is also required to allow access to the specific port through routers and firewalls. Once successfully implemented the JNIOR Protocol not only provided I/O status and control mechanisms. It also opened access to the JNIOR Registry and thereby the ability to configure and manage the product.

In addition to the JNIOR Protocol, it was also necessary to access the JNIOR Command Line through Telnet. Care again is required to allow access to the Telnet port (Port 23) through routers and firewalls. The Command Line is also accessible using a serial connection to the RS-232 port on the JNIOR. This Console connection provides tools for monitoring I/O status and affecting I/O conditions as well as the use of various kinds of diagnostics. Furthermore, in this environment, the product can be fully configured in all aspects including the network parameters. In addition, this is where application programs can be executed which extend the functionality of the JNIOR product.

Management of the JNIOR also requires the manipulation of files in the local file system. While files may be manipulated through a Console connection transfer to/from an external system is done using FTP. Again care must be taken to allow access to the FTP command port (Port 21) through routers and firewalls. FTP typically opens/accepts data connections which must also be accommodated by the network.

With the introduction of the Series 4 JNIOR running the JANOS operating system, the various I/O and management requirements covered by these other protocols can be additionally handled through a single Web Server connection. Access to the Web Server is typically through ports 80 and 443. The latter connection provides for TLS/SSL up to 256-bit security. While these ports would also need to be accommodated by routers and firewalls this is a much more standard requirement and often routine request for IT personnel. This consolidation of functionality is accomplished using the WebSocket Protocol as specified by the Internet Engineering Task Force (IETF) in combination with JANOS server-side scripting. This can result in a fully functional browser-based dynamic website providing JNIOR monitoring and control. The example is the configuration pages provided with the product. These Javascript[TM] based dynamic web pages have replaced the Java-based applets used by the Series 3 JNIOR products.

Protocol Overview

Most computer languages today accommodate programmatic connection to Web Servers in one fashion or another. It makes sense since the majority of applications developed today involve networking and therefore access to the vast range of data available through the Internet. These web applications needed some form of bi-directional communication between the client and server. For a time programmers attempted to get the job done through an abuse of the HTTP Protocol. A simpler solution has been provided in the form of a WebSocket API which has been quickly accommodated. As a result, most web-based programming environments support Websocket connections and the programmer can utilize them as easily as any other web protocol.

Briefly, the client makes a connection to a JANOS Web Server port. This port expects a valid HTTP connection but is also shared by the WebSocket protocol. Transparently behind the scenes, the connection issues the appropriate HTTP headers requesting an ‘upgrade’ to the WebSocket protocol. When the handshake is complete the connection will be ready to handle bi-directional WebSocket messaging. The JANOS Web Server supports a built-in WebSocket service with messaging that can be used to monitor, control, and manage the Series 4 JNIOR. The built-in service employs JSON message formatting.

To provide additional flexibility the JANOS WebSocket connection can, through a parameter in the URL, be redirected to an application running on the JNIOR. In this case, WebSocket messages are routed through the JANOS inter-process messaging mechanism to the application program. The program uses the same messaging system to provide replies and messages outward through the WebSocket connection. In this fashion, a completely custom messaging system can be implemented.

Security

Any protocol providing control and management functions must employ some form of security preventing unauthorized access and disturbance. In addition to being available through a TLS/SSL secure connection, the built-in JANOS Websocket implementation requires authentication. The authentication handshake must be completed before any operations for monitoring, control, and management will be allowed. This login uses active JANOS user accounts and subsequent operations adhere to the account permissions assigned by the administrator.

To facilitate the seamless use of the WebSocket protocol in the implementation of dynamic web pages a mechanism is provided that utilizes any website authentication completed by the browser to pre-authorize the WebSocket connection. This ensures that only a single entry of login credentials is required to bring up a fully functional and secure dynamic website served by the JNIOR. Note that custom applications running on the JNIOR that serve WebSocket connections are free to implement or ignore any kind of authentication requirement.