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:1020]