Merge pull request #34 from Cynerd/fixes

Fix and extend multiple parts of the documentation
silicon-heaven · May 15, 2024 · 11a033e · 11a033e
2 parents 6689589 + 738ba91
commit 11a033e
Show file tree

Hide file tree

Showing 14 changed files with 882 additions and 343 deletions.
diff --git a/src/SUMMARY.md b/src/SUMMARY.md
@@ -14,9 +14,13 @@
   - [Broker API](./rpcmethods/broker.md)
   - [Property nodes](./rpcmethods/property.md)
   - [File nodes](./rpcmethods/file.md)
+  - [Bytes Exchange nodes](./rpcmethods/exchange.md)
   - [History](./rpcmethods/history.md)
 - [RPC transport layer](./rpctransportlayer.md)
+  - [Stream transport layers](./rpctransportlayer/stream.md)
+  - [CAN Bus](./rpctransportlayer/can.md)
 - [RPC URL](./rpcurl.md)
+- [RPC RI](./rpcri.md)
 - [SHV types](./shv-types.md)
   - [SHV type info](./shv-types/shv-type-info.md)
   - [SHV journal](./shv-types/shv-journal.md)
@@ -25,4 +29,4 @@
 
 ---
 
-# SHV standard: 3.0
+# SHV standard: 3.0 pre-release
diff --git a/src/rpcmethods/app.md b/src/rpcmethods/app.md
@@ -7,9 +7,9 @@ than just a few requests.
 
 ## `.app:shvVersionMajor`
 
-| Name              | SHV Path | Signature   | Flags  | Access |
-|-------------------|----------|-------------|--------|--------|
-| `shvVersionMajor` | `.app`   | `ret(void)` | Getter | Browse |
+| Name              | SHV Path | Flags  | Access |
+|-------------------|----------|--------|--------|
+| `shvVersionMajor` | `.app`   | Getter | Browse |
 
 This method provides information about implemented SHV standard. Major version
 number signal major changes in the standard and thus you are most likely
@@ -26,9 +26,9 @@ interested just in this number.
 
 ## `.app:shvVersionMinor`
 
-| Name              | SHV Path | Signature   | Flags  | Access |
-|-------------------|----------|-------------|--------|--------|
-| `shvVersionMinor` | `.app`   | `ret(void)` | Getter | Browse |
+| Name              | SHV Path | Flags  | Access |
+|-------------------|----------|--------|--------|
+| `shvVersionMinor` | `.app`   | Getter | Browse |
 
 This method provides information about implemented SHV standard. Minor version
 number signals new features added and thus if you wish to check for support of
@@ -45,9 +45,9 @@ these additions you can use this number.
 
 ## `.app:name`
 
-| Name   | SHV Path | Signature   | Flags  | Access |
-|--------|----------|-------------|--------|--------|
-| `name` | `.app`   | `ret(void)` | Getter | Browse |
+| Name   | SHV Path | Flags  | Access |
+|--------|----------|--------|--------|
+| `name` | `.app`   | Getter | Browse |
 
 This method must provide the name of the application, or at least the SHV
 implementation used in the application.
@@ -63,9 +63,9 @@ implementation used in the application.
 
 ## `.app:version`
 
-| Name      | SHV Path | Signature   | Flags  | Access |
-|-----------|----------|-------------|--------|--------|
-| `version` | `.app`   | `ret(void)` | Getter | Browse |
+| Name      | SHV Path | Flags  | Access |
+|-----------|----------|--------|--------|
+| `version` | `.app`   | Getter | Browse |
 
 This method must provide the application version, or at least the SHV
 implementation used in the application (must be consistent with information in
@@ -82,9 +82,9 @@ implementation used in the application (must be consistent with information in
 
 ## `.app:ping`
 
-| Name   | SHV Path | Signature    | Flags | Access |
-|--------|----------|--------------|-------|--------|
-| `ping` | `.app`   | `void(void)` |       | Browse |
+| Name   | SHV Path | Flags | Access |
+|--------|----------|-------|--------|
+| `ping` | `.app`   |       | Browse |
 
 This method should reliably do nothing and should always be successful. It is
 used to check the connection (if message can be passed to and from client) as
@@ -101,9 +101,9 @@ well as to keep connection in case of SHV Broker.
 
 ## `.app:date`
 
-| Name   | SHV Path | Signature   | Flags | Access |
-|--------|----------|-------------|-------|--------|
-| `date` | `.app`   | `ret(void)` |       | Browse |
+| Name   | SHV Path | Flags | Access |
+|--------|----------|-------|--------|
+| `date` | `.app`   |       | Browse |
 
 This is an optional method that provides access to the date and time this
 application is using (that includes time zone). Applications running on systems

diff --git a/src/rpcmethods/broker.md b/src/rpcmethods/broker.md
@@ -45,9 +45,9 @@ thus unsubscribe must be performed with care to not remove still needed ones.
 
 ### `.broker/currentClient:subscribe`
 
-| Name        | SHV Path                    | Signature     | Flags | Access |
-|-------------|-----------------------------|---------------|-------|--------|
-| `subscribe` | `.broker/currentClient`     | `void(param)` |       | Browse |
+| Name        | SHV Path                    | Flags | Access |
+|-------------|-----------------------------|-------|--------|
+| `subscribe` | `.broker/currentClient`     |       | Browse |
 
 Adds rule that allows receiving of signals (notifications) from shv
 path. The subscription applies to all methods of given name in given path and
@@ -93,9 +93,9 @@ such subscription.
 
 ### `.broker/currentClient:unsubscribe`
 
-| Name          | SHV Path                    | Signature    | Flags | Access |
-|---------------|-----------------------------|--------------|-------|--------|
-| `unsubscribe` | `.broker/currentClient`     | `ret(param)` |       | Browse |
+| Name          | SHV Path                    | Flags | Access |
+|---------------|-----------------------------|-------|--------|
+| `unsubscribe` | `.broker/currentClient`     |       | Browse |
 
 Reverts an operation of `.broker/currentClient:subscribe`.
 
@@ -119,9 +119,9 @@ and `false` if it couldn't have been found.
 
 ### `.broker/currentClient:subscriptions`
 
-| Name            | SHV Path                    | Signature   | Flags  | Access |
-|-----------------|-----------------------------|-------------|--------|--------|
-| `subscriptions` | `.broker/currentClient`     | `ret(void)` | Getter | Browse |
+| Name            | SHV Path                    | Flags  | Access |
+|-----------------|-----------------------------|--------|--------|
+| `subscriptions` | `.broker/currentClient`     | Getter | Browse |
 
 This method allows you to list all existing subscriptions for the current
 client.
@@ -152,9 +152,9 @@ network.
 
 ### `.broker:clientInfo`
 
-| Name         | SHV Path      | Signature    | Flags | Access       |
-|--------------|---------------|--------------|-------|--------------|
-| `clientInfo` | `.broker` | `ret(param)`     |       | SuperService |
+| Name         | SHV Path  | Flags | Access       |
+|--------------|-----------|-------|--------------|
+| `clientInfo` | `.broker` |       | SuperService |
 
 Information the broker has on the client.
 
@@ -171,7 +171,8 @@ The *Map* containing at least these fields:
 
 * `"clientId"` with *Int* containing ID assigned to this client.
 * `"userName"` with *String* user name used during the login sequence. This is
-  optional because login might not be always required.
+  optional because broker can have clients it established itself and thus won't
+  perform any login.
 * `"mountPoint"` with *String* SHV path where device is mounted. This can be
   *Null* in case this is not a device.
 * `"subscriptions"` is a list of active subscriptions of this client.
@@ -190,9 +191,9 @@ required nor standardized at the moment.
 
 ### `.broker:mountedClientInfo`
 
-| Name                | SHV Path      | Signature    | Flags | Access       |
-|---------------------|---------------|--------------|-------|--------------|
-| `mountedClientInfo` | `.broker` | `ret(param)`     |       | SuperService |
+| Name                | SHV Path  | Flags | Access       |
+|---------------------|-----------|-------|--------------|
+| `mountedClientInfo` | `.broker` |       | SuperService |
 
 Information the broker has on the client that is mounted on the given SHV path.
 
@@ -223,9 +224,9 @@ The provided *Map* must contain the same fields as `.broker:clientInfo` does.
 
 ### `.broker/currentClient:info`
 
-| Name   | SHV Path                    | Signature   | Flags  | Access |
-|--------|-----------------------------|-------------|--------|--------|
-| `info` | `.broker/currentClient`     | `ret(void)` | Getter | Browse |
+| Name   | SHV Path                |  Flags  | Access |
+|--------|-------------------------|---------|--------|
+| `info` | `.broker/currentClient` |  Getter | Browse |
 
 Access to the information broker has for the current client. The result is
 client specific.
@@ -246,9 +247,9 @@ users.
 
 ### `.broker:clients`
 
-| Name      | SHV Path      | Signature   | Flags | Access       |
-|-----------|---------------|-------------|-------|--------------|
-| `clients` | `.broker` | `ret(void)`     |       | SuperService |
+| Name      | SHV Path  | Flags | Access       |
+|-----------|-----------|-------|--------------|
+| `clients` | `.broker` |       | SuperService |
 
 This method allows you get list of all clients connected to the broker. This
 is an administration task.
@@ -271,9 +272,9 @@ connected clients.
 ```
 ### `.broker:mounts`
 
-| Name     | SHV Path      | Signature   | Flags | Access       |
-|----------|---------------|-------------|-------|--------------|
-| `mounts` | `.broker` | `ret(void)`     |       | SuperService |
+| Name     | SHV Path  | Flags | Access       |
+|----------|-----------|-------|--------------|
+| `mounts` | `.broker` |       | SuperService |
 
 This method allows you get list of all mount paths of devices connected to the broker. This
 is an administration task.
@@ -291,9 +292,9 @@ The *List* of *Strings*s is provided where strings are mount paths of all curren
 
 ### `.broker:disconnectClient`
 
-| Name               | SHV Path      | Signature     | Flags | Access       |
-|--------------------|---------------|---------------|-------|--------------|
-| `disconnectClient` | `.broker` | `void(param)`     |       | SuperService |
+| Name               | SHV Path  | Flags | Access       |
+|--------------------|-----------|-------|--------------|
+| `disconnectClient` | `.broker` |       | SuperService |
 
 Forces some specific client to be immediately disconnected from the SHV broker.
 You need to provide client's ID as an argument. Based on the link layer client

diff --git a/src/rpcmethods/device.md b/src/rpcmethods/device.md
@@ -5,14 +5,14 @@ benefical to see the difference between random application and application that
 runs in dedicated device and controls such device. This allows generic
 identification of such devices in the SHV tree.
 
-The call to `.app:ls("device")` can be used to identify application as being a
+The call to `:ls(".app")` can be used to identify application as being a
 device.
 
 ## `.device:name`
 
-| Name   | SHV Path      | Signature   | Flags  | Access |
-|--------|---------------|-------------|--------|--------|
-| `name` | `.device`     | `ret(void)` | Getter | Browse |
+| Name   | SHV Path      | Flags  | Access |
+|--------|---------------|--------|--------|
+| `name` | `.device`     | Getter | Browse |
 
 This method must provide the device name. This is a specific generic name of the
 device.
@@ -28,9 +28,9 @@ device.
 
 ## `.device:version`
 
-| Name      | SHV Path      | Signature   | Flags  | Access |
-|-----------|---------------|-------------|--------|--------|
-| `version` | `.device`     | `ret(void)` | Getter | Browse |
+| Name      | SHV Path      | Flags  | Access |
+|-----------|---------------|--------|--------|
+| `version` | `.device`     | Getter | Browse |
 
 This method must provide version (revision) of the device.
 
@@ -45,9 +45,9 @@ This method must provide version (revision) of the device.
 
 ## `.device:serialNumber`
 
-| Name           | SHV Path      | Signature   | Flags  | Access |
-|----------------|---------------|-------------|--------|--------|
-| `serialNumber` | `.device`     | `ret(void)` | Getter | Browse |
+| Name           | SHV Path      | Flags  | Access |
+|----------------|---------------|--------|--------|
+| `serialNumber` | `.device`     | Getter | Browse |
 
 This method can provide serial number of the device if that is something the
 device has. It is allowed to provide *Null* in case there is no serial number
@@ -61,3 +61,39 @@ assigned to this device.
 => <id:42, method:"serialNumber", path:".device">i{}
 <= <id:42>i{2:"12590"}
 ```
+
+## `.device:uptime`
+
+| Name     | SHV Path  | Flags  | Access |
+|----------|-----------|--------|--------|
+| `uptime` | `.device` | Getter | Read   |
+
+This provide current device's uptime in seconds. It is allowed to provide *Null*
+in case device doesn't track its uptime.
+
+| Parameter | Result       |
+|-----------|--------------|
+| Null      | UInt \| Null |
+
+```
+=> <id:42, method:"uptime", path:".device">i{}
+<= <id:42>i{2:3842}
+```
+
+## `.device:reset`
+
+| Name    | SHV Path  | Flags | Access  |
+|---------|-----------|-------|---------|
+| `reset` | `.device` |       | Command |
+
+Initiate the device's reset. This might not be implemented and in such case
+`NotImplemented` error should be provided.
+
+| Parameter | Result       |
+|-----------|--------------|
+| Null      |  Null |
+
+```
+=> <id:42, method:"reset", path:".device">i{}
+<= <id:42>i{}
+```
diff --git a/src/rpcmethods/discovery.md b/src/rpcmethods/discovery.md
@@ -5,9 +5,9 @@ associated with it.
 
 ## `*:dir`
 
-| Name  | SHV Path | Signature    | Flags | Access |
-|-------|----------|--------------|-------|--------|
-| `dir` | Any      | `ret(param)` |       | Browse |
+| Name  | SHV Path | Flags | Access |
+|-------|----------|-------|--------|
+| `dir` | Any      |       | Browse |
 
 This method needs to be implemented for every node (that is every valid SHV
 path). It provides a way to list all available methods and signals of the node.
@@ -108,9 +108,9 @@ The compatibility mapping between *IMap* keys and historical *Map* is:
 
 ## `*:ls`
 
-| Name | SHV Path | Signature    | Flags | Signal  | Access |
-|------|----------|--------------|-------|---------|--------|
-| `ls` | Any      | `ret(param)` |       | `lsmod` | Browse |
+| Name | SHV Path | Flags | Signal  | Access |
+|------|----------|-------|---------|--------|
+| `ls` | Any      |       | `lsmod` | Browse |
 
 This method needs to be implemented for every valid SHV path. It provides a way
 to list all children nodes of the node.