JANOS Help System: [Commands] [Topics] [Tech Support] [Printable Manual] [Search]
JMP Protocol REGISTRY COMMANDS The JNIOR is configured by various parameter settings which are stored in the non-volatile Registry. In addition to configuration there are special keys (that start with the dollar sign '$') which record and report dynamic information. The input and output Usage Meter status is reported through a system Registry key named $HourMeter for example. The Registry then plays an important role in monitoring the status of a JNIOR. REGISTRY UPDATE NOTIFICATION The "Registry Update" message is an unsolicited message. It is transmitted through the JMP Server whenever there is a change in the Registry. This notifies the client when new keys are created and when they are removed (content is empty/null). It notifies the client whenever the content of a key is changed. This allows the client to respond to the changing configuration of a connected unit as well as to receive information stored in dynamic system keys. The following is a very typical update for a channel's usage meter. { "Message":"Registry Update", "Keys":{ "IO/Inputs/din1/$HourMeter":"43.68" } } Note that the "Keys" member passes an object which may contain 0 or more name/value pairs where the name is the Registry Key and the value its content. Here the $HourMeter reports 43.68 hours of usage. These update every 100th of an hour. That is the resolution of the Usage Meter. In general, Registry Updates will report only one key per message since changes occur in sequence and each change generates an update message through the inter-process messaging system. The Web Server picks up the internal message and broadcasts the information to all active JMP connections. REGISTRY LIST REQUEST The Registry stores information that from time to time you may need to retrieve. This is easily done if you know precisely what Registry keys to read. A lot of work can be saved if you can determine easily what Registry keys have been defined and that have data available for reading. The "Registry List" command is used to obtain a listing similar to a file directory or folder listing for a node in the Registry. The "Registry List" command summons a "Registry List Response" message. A complete exchange is shown below. The Client sends the request and the server supplies the response message. Note how the "Meta" member might be used to pass information to the routine that eventually (and asynchronously) will receive the response. TRANSMITTED RECEIVED { "Message":"Registry List", "Meta":{"Op":"registry","Node":"/IO/Inputs/din1"}, "Node":"/IO/Inputs/din1" } { "Message":"Registry List Response", "Meta":{"Op":"registry", "Node":"/IO/Inputs/din1"}, "Keys":[ "/IO/Inputs/din1/Enabled", "/IO/Inputs/din1/$HourMeter", "/IO/Inputs/din1/Conditioning", "/IO/Inputs/din1/LatchState", "/IO/Inputs/din1/Desc", "/IO/Inputs/din1/ClosedDesc", "/IO/Inputs/din1/OpenDesc", "/IO/Inputs/din1/Count/", "/IO/Inputs/din1/ShowCount", "/IO/Inputs/din1/ShowUsageMeter", "/IO/Inputs/din1/UsageState", "/IO/Inputs/din1/CountState", "/IO/Inputs/din1/ShowControls" ] } Here we note that a list (or array) of key names is returned in the "Keys" member. Note too that those that end in a forward slash '/' represent sub-nodes which will contain keys or additional nodes which can be retrieved with a subsequent request for that node. There are no empty sub-nodes (subdirectories or subfolders) in the JANOS Registry. Therefore if the node is listed it must have content within its structure somewhere. REGISTRY READ REQUEST The "Registry Read" command request is used to retrieve the content of one or more Registry keys. The request includes the "Keys" member which provides an array of Registry keys for which we want the content. Note that the optional "Meta" member is available for use but not employed in this example. The request solicits a "Registry Response" message which returns the "Keys" member which list time returns an object whose members are name/value pairs reporting each key and its content. TRANSMITTED RECEIVED { "Message":"Registry Read", "Keys":[ "/IO/Inputs/din1/Enabled", "/IO/Inputs/din1/$HourMeter", "/IO/Inputs/din1/Conditioning", "/IO/Inputs/din1/LatchState", "/IO/Inputs/din1/Desc", "/IO/Inputs/din1/ClosedDesc", "/IO/Inputs/din1/OpenDesc", "/IO/Inputs/din1/ShowCount", "/IO/Inputs/din1/ShowUsageMeter", "/IO/Inputs/din1/UsageState", "/IO/Inputs/din1/CountState", "/IO/Inputs/din1/ShowControls" ] } { "Message":"Registry Response", "Keys":{ "/IO/Inputs/din1/Enabled":"true", "/IO/Inputs/din1/$HourMeter":"44.28", "/IO/Inputs/din1/Conditioning":"1", "/IO/Inputs/din1/LatchState":"1", "/IO/Inputs/din1/Desc":"Input 1", "/IO/Inputs/din1/ClosedDesc":"ON", "/IO/Inputs/din1/OpenDesc":"OFF", "/IO/Inputs/din1/ShowCount":"true", "/IO/Inputs/din1/ShowUsageMeter":"true", "/IO/Inputs/din1/UsageState":"0", "/IO/Inputs/din1/CountState":"0", "/IO/Inputs/din1/ShowControls":"true" } } Note that there is a name/value pair corresponding to each requested Registry key even if that key is undefined (does not exist). All of the keys requested here in this example have values. If a key is not present it will return the empty or null string value "". REGISTRY WRITE REQUEST An external application may need to alter the configuration of a JNIOR. In order to do so it is necessary to create or change the content of a Registry key. The "Registry Write" command is used for this purpose. There is no restriction as to what can be written to the Registry. Specific keys have specific purposes and some are recognized internally by the JANOS operating system. Others pertain to the formatting of the dynamic pages. Still others may be specific to custom applications and programs running on the JNIOR. The "Keys" member of the "Registry Write" command message provides an object containing 1 or more name/value pairs. Each element represents a write request where the name is the Registry key and the value its intended content. Note that the JANOS Registry stores strings. Only strings can be written however they may encode practically anything. The "Registry Write" request solicits a "Registry Response" returning the keys successfully written. If there is an error in writing a key, the key will be returned either with an empty or null string ("") or the prior and still valid content. Here is an example changing the description displayed by the configuration pages for Digital Input 2. The write was successful. TRANSMITTED RECEIVED { "Message":"Registry Write", "Keys":{ "IO/Inputs/din2/Desc":"Part Produced" } } { "Message":"Registry Response", "Keys":{ "IO/Inputs/din2/Desc":"Part Produced" } } Not surprisingly this exchange is immediately followed by a "Registry Update" message. This signals to all who are listening that the key has been altered. { "Message":"Registry Update", "Keys":{ "IO/Inputs/din2/Desc":"Part Produced" } } REGISTRY WRITE ENCRYPTED The Registry may store user names and passwords for configured email accounts for example. The user's and administrator's account credentials defined in JANOS are stored very securely internal the processor chip itself. Passwords for other purposes are configured in the Registry and should not be stored in plain text. Note the result of the following "Registry Read" request. TRANSMITTED RECEIVED { "Message":"Registry Read", "Keys":[ "/IpConfig/Password" ] } { "Message":"Registry Response", "Keys":{ "/IpConfig/Password":"Qrq5CQ/rYBPfye..." } } This password for the default email account is not readable. This is not just obfuscated from view but securely encrypted by a secret key known only to the JANOS operating system and one that is unique to the unit. Nevertheless an external application (including the configuration pages) needs to be able to set a new password. This cannot be done without special handling as the encryption secret is not externally known and cannot be determined. To make this possible, the "Registry Write Encrypted" command is available. This is used to write new password credentials for the default email account and indeed any other such account where JANOS later requires access to the plain text password. JANOS needs to be able to decrypt the content. If an application wants to store data securely it can encrypt the data using its own procedures and write the encrypted result using the normal "Registry Write" command. Later the content can be read and decrypted. The special form of write command is used only for information that JANOS stores with its own secure encryption. Data that only JANOS can then decrypt and use. The "Registry Write Encrypted" command works exactly as does the "Registry Write" command. It also summons a "Registry Response" but one that shows only the encrypted password content. The password is provided in the request in combination with the username and in plain text. It is highly recommended that passwords not be configured through this protocol unless the connection used is secured by TLS/SSL. The procedure for setting a new password can be gleamed from the dynamic web pages supplied with the unit. The steps to handle it are in the Javascript. You can also contact INTEG Process Group, Inc. for assistance if you have trouble. Typically this password is set using the IPCONFIG command in the Console. [/flash/manpages/protocol.hlp:1018]