Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix: Address old api v2 references and other stall items #1107

Merged
merged 1 commit into from
Jun 5, 2023
Merged

fix: Address old api v2 references and other stall items #1107

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 9 additions & 9 deletions docs_src/examples/Ch-CommandingDeviceThroughRulesEngine.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,14 +38,14 @@ curl -X POST \
Since both use case scenario rules will send commands to the `Random-Boolean-Device` virtual device, use the curl request below to get a list of available commands for this device.

``` bash
curl http://127.0.0.1:59882/api/v2/device/name/Random-Boolean-Device | jq
curl http://127.0.0.1:59882/api/v3/device/name/Random-Boolean-Device | jq
```

It should print results like those below.

``` json
{
"apiVersion": "v2",
"apiVersion": "v3",
"statusCode": 200,
"deviceCoreCommand": {
"deviceName": "Random-Boolean-Device",
Expand All @@ -54,7 +54,7 @@ It should print results like those below.
{
"name": "WriteBoolValue",
"set": true,
"path": "/api/v2/device/name/Random-Boolean-Device/WriteBoolValue",
"path": "/api/v3/device/name/Random-Boolean-Device/WriteBoolValue",
"url": "http://edgex-core-command:59882",
"parameters": [
{
Expand All @@ -70,7 +70,7 @@ It should print results like those below.
{
"name": "WriteBoolArrayValue",
"set": true,
"path": "/api/v2/device/name/Random-Boolean-Device/WriteBoolArrayValue",
"path": "/api/v3/device/name/Random-Boolean-Device/WriteBoolArrayValue",
"url": "http://edgex-core-command:59882",
"parameters": [
{
Expand All @@ -87,7 +87,7 @@ It should print results like those below.
"name": "Bool",
"get": true,
"set": true,
"path": "/api/v2/device/name/Random-Boolean-Device/Bool",
"path": "/api/v3/device/name/Random-Boolean-Device/Bool",
"url": "http://edgex-core-command:59882",
"parameters": [
{
Expand All @@ -100,7 +100,7 @@ It should print results like those below.
"name": "BoolArray",
"get": true,
"set": true,
"path": "/api/v2/device/name/Random-Boolean-Device/BoolArray",
"path": "/api/v3/device/name/Random-Boolean-Device/BoolArray",
"url": "http://edgex-core-command:59882",
"parameters": [
{
Expand All @@ -123,7 +123,7 @@ You can test calling this command with its parameters using curl as shown below.

``` bash
curl -X PUT \
http://edgex-core-command:59882/api/v2/device/name/Random-Boolean-Device/WriteBoolValue \
http://edgex-core-command:59882/api/v3/device/name/Random-Boolean-Device/WriteBoolValue \
-H 'Content-Type: application/json' \
-d '{"Bool":"true", "EnableRandomization_Bool": "true"}'
```
Expand All @@ -146,7 +146,7 @@ curl -X POST \
"actions": [
{
"rest": {
"url": "http://edgex-core-command:59882/api/v2/device/name/Random-Boolean-Device/WriteBoolValue",
"url": "http://edgex-core-command:59882/api/v3/device/name/Random-Boolean-Device/WriteBoolValue",
"method": "put",
"dataTemplate": "{\"Bool\":\"true\", \"EnableRandomization_Bool\": \"true\"}",
"sendSingle": true
Expand All @@ -173,7 +173,7 @@ curl -X POST \
"actions": [
{
"rest": {
"url": "http://edgex-core-command:59882/api/v2/device/name/Random-Boolean-Device/WriteBoolValue",
"url": "http://edgex-core-command:59882/api/v3/device/name/Random-Boolean-Device/WriteBoolValue",
"method": "put",
"dataTemplate": "{\"Bool\":\"false\", \"EnableRandomization_Bool\": \"false\"}",
"sendSingle": true
Expand Down
16 changes: 8 additions & 8 deletions docs_src/examples/Ch-ExamplesAddingMQTTDevice.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -308,7 +308,7 @@ Now we're ready to run some commands.
Use the following query to find executable commands:

```json
$ curl http://localhost:59882/api/v2/device/all | json_pp
$ curl http://localhost:59882/api/v3/device/all | json_pp

{
"deviceCoreCommands" : [
Expand All @@ -318,7 +318,7 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp
{
"name" : "values",
"get" : true,
"path" : "/api/v2/device/name/my-custom-device/values",
"path" : "/api/v3/device/name/my-custom-device/values",
"url" : "http://edgex-core-command:59882",
"parameters" : [
{
Expand All @@ -345,14 +345,14 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp
],
"name" : "message",
"get" : true,
"path" : "/api/v2/device/name/my-custom-device/message",
"path" : "/api/v3/device/name/my-custom-device/message",
"set" : true
},
{
"name": "json",
"get": true,
"set": true,
"path": "/api/v2/device/name/MQTT-test-device/json",
"path": "/api/v3/device/name/MQTT-test-device/json",
"url" : "http://edgex-core-command:59882",
"parameters": [
{
Expand All @@ -376,7 +376,7 @@ Execute a SET command according to the url and parameterNames, replacing
\[host\] with the server IP when running the SET command.

```
$ curl http://localhost:59882/api/v2/device/name/my-custom-device/message \
$ curl http://localhost:59882/api/v3/device/name/my-custom-device/message \
-H "Content-Type:application/json" -X PUT \
-d '{"message":"Hello!"}'
```
Expand All @@ -386,7 +386,7 @@ $ curl http://localhost:59882/api/v2/device/name/my-custom-device/message \
Execute a GET command as follows:

```json
$ curl http://localhost:59882/api/v2/device/name/my-custom-device/message | json_pp
$ curl http://localhost:59882/api/v3/device/name/my-custom-device/message | json_pp

{
"apiVersion":"v2",
Expand Down Expand Up @@ -429,7 +429,7 @@ show that the service auto-executes the command every 30 secs, as shown
below:

```json
$ curl http://localhost:59880/api/v2/reading/resourceName/message | json_pp
$ curl http://localhost:59880/api/v3/reading/resourceName/message | json_pp

{
"statusCode" : 200,
Expand Down Expand Up @@ -474,7 +474,7 @@ The following results show that the mock device sent the reading every
15 secs:

```json
$ curl http://localhost:59880/api/v2/reading/resourceName/randnum | json_pp
$ curl http://localhost:59880/api/v3/reading/resourceName/randnum | json_pp

{
"readings" : [
Expand Down
30 changes: 15 additions & 15 deletions docs_src/examples/Ch-ExamplesAddingModbusDevice.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -299,26 +299,26 @@ To add a device after starting the services, complete the following
steps:

1. Upload the device profile above to metadata with a POST to
<http://localhost:59881/api/v2/deviceprofile/uploadfile> and add the
<http://localhost:59881/api/v3/deviceprofile/uploadfile> and add the
file as key "file" to the body in form-data format, and the created
ID will be returned. The following example command uses curl to send the request:

```
$ curl http://localhost:59881/api/v2/deviceprofile/uploadfile \
$ curl http://localhost:59881/api/v3/deviceprofile/uploadfile \
-F "[email protected]"
```

2. Ensure the Modbus device service is running, adjust the service name
below to match if necessary or if using other device services.

4. Add the device with a POST to
<http://localhost:59881/api/v2/device>, the body will look something
<http://localhost:59881/api/v3/device>, the body will look something
like:
```
$ curl http://localhost:59881/api/v2/device -H "Content-Type:application/json" -X POST \
$ curl http://localhost:59881/api/v3/device -H "Content-Type:application/json" -X POST \
-d '[
{
"apiVersion": "v2",
"apiVersion": "v3",
"device": {
"name" :"Modbus-TCP-Temperature-Sensor",
"description":"This device is a product for monitoring the temperature via the ethernet",
Expand Down Expand Up @@ -363,7 +363,7 @@ Now we're ready to run some commands.

Use the following query to find executable commands:
```json
$ curl http://localhost:59882/api/v2/device/all | json_pp
$ curl http://localhost:59882/api/v3/device/all | json_pp

{
"apiVersion" : "v2",
Expand All @@ -387,14 +387,14 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp
"resourceName" : "ThermostatH"
}
],
"path" : "/api/v2/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold"
"path" : "/api/v3/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold"
},
{
"get" : true,
"url" : "http://edgex-core-command:59882",
"name" : "AlarmMode",
"set" : true,
"path" : "/api/v2/device/name/Modbus-TCP-Temperature-Sensor/AlarmMode",
"path" : "/api/v3/device/name/Modbus-TCP-Temperature-Sensor/AlarmMode",
"parameters" : [
{
"resourceName" : "AlarmMode",
Expand All @@ -406,7 +406,7 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp
"get" : true,
"url" : "http://edgex-core-command:59882",
"name" : "Temperature",
"path" : "/api/v2/device/name/Modbus-TCP-Temperature-Sensor/Temperature",
"path" : "/api/v3/device/name/Modbus-TCP-Temperature-Sensor/Temperature",
"parameters" : [
{
"valueType" : "Float32",
Expand All @@ -427,7 +427,7 @@ $ curl http://localhost:59882/api/v2/device/all | json_pp
Execute SET command according to `url` and `parameterNames`, replacing [host] with the server IP when running the SET command.

```
$ curl http://localhost:59882/api/v2/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold \
$ curl http://localhost:59882/api/v3/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold \
-H "Content-Type:application/json" -X PUT \
-d '{"ThermostatL":"15","ThermostatH":"100"}'
```
Expand All @@ -437,7 +437,7 @@ $ curl http://localhost:59882/api/v2/device/name/Modbus-TCP-Temperature-Sensor/A
Replace *\<host\>* with the server IP when running the GET command.

```json
$ curl http://localhost:59882/api/v2/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold | json_pp
$ curl http://localhost:59882/api/v3/device/name/Modbus-TCP-Temperature-Sensor/AlarmThreshold | json_pp

{
"statusCode" : 200,
Expand Down Expand Up @@ -491,7 +491,7 @@ After service startup, query core-data's API. The results show
that the service auto-executes the command every 30 seconds.

```json
$ curl http://localhost:59880/api/v2/event/device/name/Modbus-TCP-Temperature-Sensor | json_pp
$ curl http://localhost:59880/api/v3/event/device/name/Modbus-TCP-Temperature-Sensor | json_pp

{
"events" : [
Expand Down Expand Up @@ -673,17 +673,17 @@ $ docker-compose up -d
```
2. Upload the device profile
```
$ curl http://localhost:59881/api/v2/deviceprofile/uploadfile \
$ curl http://localhost:59881/api/v3/deviceprofile/uploadfile \
-F "[email protected]"
```

3. Create the device entity to the EdgeX.
You can find the Modbus RTU setting on the device or the user manual.
```json
$ curl http://localhost:59881/api/v2/device -H "Content-Type:application/json" -X POST \
$ curl http://localhost:59881/api/v3/device -H "Content-Type:application/json" -X POST \
-d '[
{
"apiVersion": "v2",
"apiVersion": "v3",
"device": {
"name" :"Modbus-RTU-IO-Module",
"description":"The device can be used to monitor the status of the digital input and digital output channels.",
Expand Down
8 changes: 4 additions & 4 deletions docs_src/examples/Ch-ExamplesAddingSNMPDevice.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,7 +111,7 @@ Because setting a light or buzzer requires both of the control state and timer O
You will need to upload this profile into core metadata. Download the [Patlite device profile](patlite-snmp.yml) to a convenient directory. Then, using the following `curl` command, request the profile be uploaded into core metadata.

``` Shell
curl -X 'POST' 'http://localhost:59881/api/v2/deviceprofile/uploadfile' --form 'file=@"/home/yourfilelocationhere/patlite-snmp.yml"'
curl -X 'POST' 'http://localhost:59881/api/v3/deviceprofile/uploadfile' --form 'file=@"/home/yourfilelocationhere/patlite-snmp.yml"'
```

!!! Alert
Expand All @@ -127,7 +127,7 @@ The curl command to POST the new Patlite device (named `patlite1`) into metadata


``` Shell
curl -X 'POST' 'http://localhost:59881/api/v2/device' -d '[{"apiVersion": "v2", "device": {"name": "patlite1","description": "patlite #1","adminState": "UNLOCKED","operatingState": "UP","labels": ["patlite"],"serviceName": "device-snmp","profileName": "patlite-snmp-profile","protocols": {"TCP": {"Address": "10.0.0.14","Port": "161"}}, "AutoEvents":[{"Interval":"10s","OnChange":true,"SourceName":"RedLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"GreenLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"AmberLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"BuzzerCurrentState"}]}}]'
curl -X 'POST' 'http://localhost:59881/api/v3/device' -d '[{"apiVersion": "v3", "device": {"name": "patlite1","description": "patlite #1","adminState": "UNLOCKED","operatingState": "UP","labels": ["patlite"],"serviceName": "device-snmp","profileName": "patlite-snmp-profile","protocols": {"TCP": {"Address": "10.0.0.14","Port": "161"}}, "AutoEvents":[{"Interval":"10s","OnChange":true,"SourceName":"RedLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"GreenLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"AmberLightCurrentState"}, {"Interval":"10s","OnChange":true,"SourceName":"BuzzerCurrentState"}]}}]'
```

!!! Info
Expand All @@ -143,7 +143,7 @@ If the device service is up and running and the profile and device have been add
To get the current state of a light (in the example below the `Green` light), make a curl request like the following of the command service.

``` Shell
curl 'http://localhost:59882/api/v2/device/name/patlite1/GreenLightCurrentState' | json_pp
curl 'http://localhost:59882/api/v3/device/name/patlite1/GreenLightCurrentState' | json_pp
```

!!! Alert
Expand Down Expand Up @@ -193,7 +193,7 @@ The results should look something like that below.
To turn a signal tower light or the buzzer on, you can issue a PUT device command via the core command service. The example below turns on the `Green` light.

``` Shell
curl --location --request PUT 'http://localhost:59882/api/v2/device/name/patlite1/GreenLight' --header 'cont: application/json' --data-raw '{"GreenLightControlState":"2","GreenLightTimer":"0"}'
curl --location --request PUT 'http://localhost:59882/api/v3/device/name/patlite1/GreenLight' --header 'cont: application/json' --data-raw '{"GreenLightControlState":"2","GreenLightTimer":"0"}'
```

![image](EdgeX_Patlite_Green_On.jpg)
Expand Down
2 changes: 1 addition & 1 deletion docs_src/examples/Ch-ExamplesSendingAndConsumingBinary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ if req.DeviceResourceName == "camera_snapshot" {

Querying core-metadata for the Device's Commands and DeviceName provides
the following as the URL to request a reading from the snapshot command:
<http://localhost:59990/api/v2/device/name/camera-device/OnvifSnapshot>
<http://localhost:59990/api/v3/device/name/camera-device/OnvifSnapshot>

Unlike with non-binary Events, making a request to this URL will return
an event in CBOR representation. CBOR is a representation of binary data
Expand Down
12 changes: 6 additions & 6 deletions docs_src/examples/Ch-ExamplesVirtualDeviceService.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,19 +34,19 @@ If you're going to download the source code and run the virtual device service i
The virtual device service is configured to send simulated data to core data every few seconds (from 10-30 seconds depending on device - see the [device configuration file](https://github.com/edgexfoundry/device-virtual-go/blob/{{version}}/cmd/res/devices/devices.yaml) for AutoEvent details). You can exercise the `GET` request on the command service to see the generated value produced by any of the virtual device's simulated devices. Use the curl command below to exercise the virtual device service API (via core command service).

``` bash
curl -X GET localhost:59882/api/v2/device/name/Random-Integer-Device/Int8
curl -X GET localhost:59882/api/v3/device/name/Random-Integer-Device/Int8
```

!!! Warning
The example above assumes your core command service is available on `localhost` at the default service port of 59882. Also, you must replace your device name and command name in the example above with your virtual device service's identifiers. If you are not sure of the identifiers to use, query the command service for the full list of commands and devices at `http://localhost:59882/api/v2/device/all`.
The example above assumes your core command service is available on `localhost` at the default service port of 59882. Also, you must replace your device name and command name in the example above with your virtual device service's identifiers. If you are not sure of the identifiers to use, query the command service for the full list of commands and devices at `http://localhost:59882/api/v3/device/all`.

The virtual device should respond (via the core command service) with event/reading JSON similar to that below.
``` json
{
"apiVersion": "v2",
"apiVersion": "v3",
"statusCode": 200,
"event": {
"apiVersion": "v2",
"apiVersion": "v3",
"id": "3beb5b83-d923-4c8a-b949-c1708b6611c1",
"deviceName": "Random-Integer-Device",
"profileName": "Random-Integer-Device",
Expand Down Expand Up @@ -75,7 +75,7 @@ The virtual devices managed by the virtual device can also be actuated. The vir
Below is example actuation of one of the virtual devices. In this example, it sets the fixed `GET` return value to 123 and turns off random generation.

``` bash
curl -X PUT -d '{"Int8": "123", "EnableRandomization_Int8": "false"}' localhost:59882/api/v2/device/name/Random-Integer-Device/Int8
curl -X PUT -d '{"Int8": "123", "EnableRandomization_Int8": "false"}' localhost:59882/api/v3/device/name/Random-Integer-Device/Int8
```

!!! Note
Expand All @@ -84,7 +84,7 @@ curl -X PUT -d '{"Int8": "123", "EnableRandomization_Int8": "false"}' localhost:
Return the virtual device to randomly generating numbers with another `PUT` call.

``` bash
curl -X PUT -d '{"EnableRandomization_Int8": "true"}' localhost:59882/api/v2/device/name/Random-Integer-Device/Int8
curl -X PUT -d '{"EnableRandomization_Int8": "true"}' localhost:59882/api/v3/device/name/Random-Integer-Device/Int8
```

## Reference
Expand Down
Binary file removed docs_src/examples/commands_MQTT.png
View file
Open in desktop
Binary file not shown.
Binary file removed docs_src/examples/config_changes_MQTT.png
View file
Open in desktop
Binary file not shown.
Binary file removed docs_src/examples/configuration.png
View file
Open in desktop
Binary file not shown.
Binary file removed docs_src/examples/configuration_MQTT.png
View file
Open in desktop
Binary file not shown.
Binary file removed docs_src/examples/connection.png
View file
Open in desktop
Binary file not shown.
Binary file removed docs_src/examples/devicegoSetup.png
View file
Open in desktop
Binary file not shown.
Binary file removed docs_src/examples/deviceprofile.png
View file
Open in desktop
Binary file not shown.
8 changes: 4 additions & 4 deletions docs_src/getting-started/ApplicationFunctionsSDK.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,22 +104,22 @@ Set the Trigger type to `http` in configuration file found here: [res/configurat
Type="http"
```

Using PostMan or curl send the following JSON to `localhost:<port>/api/v2/trigger`
Using PostMan or curl send the following JSON to `localhost:<port>/api/v3/trigger`

```json
{
"requestId": "82eb2e26-0f24-48ba-ae4c-de9dac3fb9bc",
"apiVersion": "v2",
"apiVersion": "v3",
"event": {
"apiVersion": "v2",
"apiVersion": "v3",
"deviceName": "Random-Float-Device",
"profileName": "Random-Float-Device",
"sourceName" : "Float32",
"origin": 1540855006456,
"id": "94eb2e26-0f24-5555-2222-de9dac3fb228",
"readings": [
{
"apiVersion": "v2",
"apiVersion": "v3",
"resourceName": "Float32",
"profileName": "Random-Float-Device",
"deviceName": "Random-Float-Device",
Expand Down
2 changes: 1 addition & 1 deletion docs_src/getting-started/Ch-GettingStartedDTOValidation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,4 +33,4 @@ This validation allows for only the following characters:
- special character: - _ ~ : ; =

!!! edgey "EdgeX 3.0"
In EdgeX 3.0, the character restriction was reduced for the command name and resource name because some protocols may use `/` or `.` in the name. By using URL escaping for the API, device command name and resource name allow various characters. For example, the user can define the command name `line-a/test:value` and use it with URL escaping as `/api/v2/device/name/Modbus-TCP-Device/line-a%2Ftest%3Avalue`.
In EdgeX 3.0, the character restriction was reduced for the command name and resource name because some protocols may use `/` or `.` in the name. By using URL escaping for the API, device command name and resource name allow various characters. For example, the user can define the command name `line-a/test:value` and use it with URL escaping as `/api/v3/device/name/Modbus-TCP-Device/line-a%2Ftest%3Avalue`.
Loading