Code Review / apps / low-level-can-service.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | review | tree
raw | inline | side by side
add new C5 commands to JSON. Added ToC for this file.
[apps/low-level-can-service.git] / JSON.mkd
diff --git a/JSON.mkd b/JSON.mkd
index 804efa4..d320aad 100644 (file)
--- a/JSON.mkd
+++ b/JSON.mkd
@@ -2,23 +2,18 @@
 
 Each JSON message published by a VI is delimited with a `\0 ` character.
 
 
 Each JSON message published by a VI is delimited with a `\0 ` character.
 
-## Extra Values
+## Table of Contents
+1. [Vehicle Messages](#vehicle-messages)
+2. [CAN Message](#can-message)
+3. [Diagnostic Message](#diagnostic-message)
+4. [Commands](#commands)
+5. [Extra Values](#extra-values)
 
 
-Any of the following JSON objects may optionally include an `extras`
-field. The value may be any valid JSON object or array. The client libraries
-will do their best to parse this information into a generic format and pass it
-to your application. For example:
+## Vehicle Messages
 
 
-    {"name": "steering_wheel_angle",
-        "value": 45,
-        "extras": {
-            "calibrated": false
-        }
-    }
-
-## Single Valued
+### Simple Vehicle Message
 
 
-There may not be a 1:1 relationship between input and output signals - i.e. raw
+There may not be a 1:1 relationship between input and output signals - i.e.
 engine timing CAN signals may be summarized in an "engine performance" metric on
 the abstract side of the interface.
 
 engine timing CAN signals may be summarized in an "engine performance" metric on
 the abstract side of the interface.
 
@@ -26,7 +21,7 @@ The expected format of a single valued message is:
 
     {"name": "steering_wheel_angle", "value": 45}
 
 
     {"name": "steering_wheel_angle", "value": 45}
 
-## Evented
+### Evented Simple Vehicle Message
 
 The expected format of an event message is:
 
 
 The expected format of an event message is:
 
@@ -35,9 +30,9 @@ The expected format of an event message is:
 This format is good for something like a button event, where there are two
 discrete pieces of information in the measurement.
 
 This format is good for something like a button event, where there are two
 discrete pieces of information in the measurement.
 
-## Raw CAN Message format
+## CAN Message
 
 
-The format for a raw CAN message:
+The format for a plain CAN message:
 
     {"bus": 1, "id": 1234, "data": "0x12345678"}
 
 
     {"bus": 1, "id": 1234, "data": "0x12345678"}
 
@@ -57,7 +52,7 @@ The format for a raw CAN message:
   of `standard` or `extended`. If the `id` is greater than `0x7ff`, the extended
   frame format will be selected automatically.
 
   of `standard` or `extended`. If the `id` is greater than `0x7ff`, the extended
   frame format will be selected automatically.
 
-## Diagnostic Messages
+## Diagnostic Message
 
 ### Requests
 
 
 ### Requests
 
@@ -65,9 +60,9 @@ A diagnostic request is added or cancelled with a JSON object like this example:
 
     { "command": "diagnostic_request",
       "action": "add",
 
     { "command": "diagnostic_request",
       "action": "add",
-      "request": {
+      "diagnostic_request": {
           "bus": 1,
           "bus": 1,
-          "id": 1234,
+          "message_id": 1234,
           "mode": 1,
           "pid": 5,
           "payload": "0x1234",
           "mode": 1,
           "pid": 5,
           "payload": "0x1234",
@@ -92,9 +87,9 @@ simple one-time diagnostic request:
 
     { "command": "diagnostic_request",
       "action": "add",
 
     { "command": "diagnostic_request",
       "action": "add",
-      "request": {
+      "diagnostic_request": {
           "bus": 1,
           "bus": 1,
-          "id": 1234,
+          "message_id": 1234,
           "mode": 1,
           "pid": 5
         }
           "mode": 1,
           "pid": 5
         }
@@ -111,9 +106,9 @@ previous example as a recurring request at 1Hz:
 
     { "command": "diagnostic_request",
       "action": "add",
 
     { "command": "diagnostic_request",
       "action": "add",
-      "request": {
+      "diagnostic_request": {
           "bus": 1,
           "bus": 1,
-          "id": 1234,
+          "message_id": 1234,
           "mode": 1,
           "pid": 5,
           "frequency": 1
           "mode": 1,
           "pid": 5,
           "frequency": 1
@@ -125,9 +120,9 @@ To cancel a recurring request, send a `cancel` action with the same key, e.g.:
 
     { "command": "diagnostic_request",
       "action": "cancel",
 
     { "command": "diagnostic_request",
       "action": "cancel",
-      "request": {
+      "diagnostic_request": {
           "bus": 1,
           "bus": 1,
-          "id": 1234,
+          "message_id": 1234,
           "mode": 1,
           "pid": 5
         }
           "mode": 1,
           "pid": 5
         }
@@ -141,7 +136,7 @@ exist in parallel with a recurring request for the same key.
 **bus** - the numerical identifier of the CAN bus where this request should be
     sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
 
 **bus** - the numerical identifier of the CAN bus where this request should be
     sent, most likely 1 or 2 (for a vehicle interface with 2 CAN controllers).
 
-**id** - the CAN arbitration ID for the request.
+**message_id** - the CAN message ID for the request.
 
 **mode** - the OBD-II mode of the request - 0x1 through 0xff (1 through 9 are the
     standardized modes and 0x22 is a common proprietary mode).
 
 **mode** - the OBD-II mode of the request - 0x1 through 0xff (1 through 9 are the
     standardized modes and 0x22 is a common proprietary mode).
@@ -157,12 +152,12 @@ exist in parallel with a recurring request for the same key.
 
 **name** - (optional, defaults to nothing) A human readable, string name for
   this request. If provided, the response will have a `name` field (much like a
 
 **name** - (optional, defaults to nothing) A human readable, string name for
   this request. If provided, the response will have a `name` field (much like a
-  normal translated message) with this value in place of `bus`, `id`, `mode` and
+  simple vehicle message) with this value in place of `bus`, `id`, `mode` and
   `pid`.
 
 **multiple_responses** - (optional, false by default) if true, request will stay
   active for a full 100ms, even after receiving a diagnostic response message.
   `pid`.
 
 **multiple_responses** - (optional, false by default) if true, request will stay
   active for a full 100ms, even after receiving a diagnostic response message.
-  This is useful for requests to the functional broadcast arbitration ID
+  This is useful for requests to the functional broadcast message ID
   (`0x7df`) when you need to get responses from multiple modules. It's possible
   to set this to `true` for non-broadcast requests, but in practice you won't
   see any additional responses after the first and it will just take up memory
   (`0x7df`) when you need to get responses from multiple modules. It's possible
   to set this to `true` for non-broadcast requests, but in practice you won't
   see any additional responses after the first and it will just take up memory
@@ -179,10 +174,19 @@ manually override the OBD-II decoding feature for a known PID.
 
 ### Responses
 
 
 ### Responses
 
-The response to a successful request:
+Requests to add or cancel a diagnostic request are first acknowledged by the VI,
+before any responses to the request are returned. The response uses the standard
+command response format:
+
+    { "command_response": "diagnostic_request", "status": true}
+
+**status** - true if the request was successfully created or cancelled.
+
+When a node on the network response to the request and the result is published
+by the VI, the result looks like:
 
     {"bus": 1,
 
     {"bus": 1,
-      "id": 1234,
+      "message_id": 1234,
       "mode": 1,
       "pid": 5,
       "success": true,
       "mode": 1,
       "pid": 5,
       "success": true,
@@ -193,7 +197,7 @@ and to an unsuccessful request, with the `negative_response_code` and no `pid`
 echo:
 
     {"bus": 1,
 echo:
 
     {"bus": 1,
-      "id": 1234,
+      "message_id": 1234,
       "mode": 1,
       "success": false,
       "negative_response_code": 17}
       "mode": 1,
       "success": false,
       "negative_response_code": 17}
@@ -201,7 +205,7 @@ echo:
 **bus** - the numerical identifier of the CAN bus where this response was
     received.
 
 **bus** - the numerical identifier of the CAN bus where this response was
     received.
 
-**id** - the CAN arbitration ID for this response.
+**message_id** - the CAN message ID for this response.
 
 **mode** - the OBD-II mode of the original diagnostic request.
 
 
 **mode** - the OBD-II mode of the original diagnostic request.
 
@@ -226,13 +230,24 @@ Finally, the `payload` and `value` fields are mutually exclusive:
 
 The response to a simple PID request would look like this:
 
 
 The response to a simple PID request would look like this:
 
-    {"success": true, "bus": 1, "id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
+    {"success": true, "bus": 1, "message_id": 1234, "mode": 1, "pid": 5, "payload": "0x2"}
 
 ## Commands
 
 In addition to the `diagnostic_request` command described earlier, there are
 other possible values for the `command` field.
 
 
 ## Commands
 
 In addition to the `diagnostic_request` command described earlier, there are
 other possible values for the `command` field.
 
+All commands immediately return a `command_response`, e.g.:
+
+    { "command_response": "version", "message": "v6.0-dev (default)", "status": true}
+
+**command_response** - an echo of the command this is a ACKing.
+
+**status** - true if the command was understood and performed succesfully.
+
+**message** - (optional) a string message from the VI, e.g. to return a version
+    descriptor or error message.
+
 ### Version Query
 
 The `version` command triggers the VI to inject a firmware version identifier
 ### Version Query
 
 The `version` command triggers the VI to inject a firmware version identifier
@@ -244,20 +259,22 @@ response into the outgoing data stream.
 
 **Response**
 
 
 **Response**
 
-    { "command_response": "version", "message": "v6.0-dev (default)"}
+    { "command_response": "version", "message": "v6.0-dev (default)", "status": true}
 
 ### Device ID Query
 
 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
 MAC address of an included Bluetooth module) into into the outgoing data stream.
 
 
 ### Device ID Query
 
 The `device_id` command triggers the VI to inject a unique device ID (e.g. the
 MAC address of an included Bluetooth module) into into the outgoing data stream.
 
+If no device ID is available, the response message will be "Unknown".
+
 **Request**
 
     { "command": "device_id"}
 
 **Response**
 
 **Request**
 
     { "command": "device_id"}
 
 **Response**
 
-    { "command_response": "device_id", "message": "0012345678"}
+    { "command_response": "device_id", "message": "0012345678", "status": true}
 
 ### Passthrough CAN Mode
 
 
 ### Passthrough CAN Mode
 
@@ -346,8 +363,73 @@ the "Signals Defined from Diagnostic Messages" section below.
 
 **Response**
 
 
 **Response**
 
-f the predefined requests were enabled or disabled successfully, the `status` in
+If the predefined requests were enabled or disabled successfully, the `status` in
 the response will be `true`.
 
     { "command_response": "predefined_obd2", "status": true}
 
 the response will be `true`.
 
     { "command_response": "predefined_obd2", "status": true}
 
+### C5 Cellular Configuration
+
+The ModemConfigurationCommand message allows users to change certain aspects of modem operation on-the-fly (at runtime). The modem configuration settings are stored in flash memory and are untouched by the bootloader during a software update (assuming the correct cellular_c5 linker file is used during compilation of vi-firmware). Thus, new modem settings persistent across power cycles.
+
+The ModemConfigurationCommand message provides three sub-messages for particular groups of modem settings. These are NetworkOperatorSettings, NetworkDataSettings, and ServerConnectSettings. These configuration messages are described in great detail within the [c5_cellular_config](https://github.com/openxc/vi-firmware/docs/advanced/c5_cell_config.html) documentation. 
+
+Currently, only the ServerConnectSettings sub-message is supported in the vi-firmware's command interpreter. All other settings are currently compile-time only.
+
+The ServerConnectSettings part of ModemConfigurationCommand allows the user to set the host server name and port that the device will use when opening a TCP socket to upload data. This destination must be running an HTTP server similar to [OpenXCWebServer](https://github.com/openxc/openxc-azure-webserver), which defines a set of supported HTTP transactions where the body is comprised of data in the familiar OpenXC Message Format.
+
+**Request**
+
+    { "command": "modem_configuration",
+      "server": {
+               "host": "www.myhost.com",
+               "port": 10000
+         }
+    }
+
+**Response**
+
+       { "command_response": "modem_configuration", "status": true}
+
+## C5 SD Card Status
+
+In order to check the status of the SD card, the following command is available:
+
+    { "command": "sd_mount_status"}
+    
+Command response if the SD card is mounted correctly:
+
+    { "command_response": "sd_mount_status", "status": true}
+    
+If the SD card is full, not enabled, or connected as a MSD, the device will respond with:
+
+    { "command_response": "sd_mount_status", "status": false}
+    
+For more info see [c5_msd](https://github.com/openxc/vi-firmware/docs/advanced/msd.html).
+
+## C5 RTC Configuration
+
+To set the current time of the RTC, the following
+
+    { "command": "rtc_configuration", "unix_time": "1448551563"}
+    
+The response is
+
+    { "command_response": "rtc_configuration", "status": true}
+
+For more info see [c5_rtc](https://github.com/openxc/vi-firmware/docs/advanced/rtc.html).
+
+## Extra Values
+
+Any of the following JSON objects may optionally include an `extras`
+field. The value may be any valid JSON object or array. The client libraries
+will do their best to parse this information into a generic format and pass it
+to your application. For example:
+
+    {"name": "steering_wheel_angle",
+        "value": 45,
+        "extras": {
+            "calibrated": false
+        }
+    }
+