Skip to content

SenseCAP WebAPI Server (English)

Jump to bottom
Jancee JX | 王静茜 edited this page Jan 6, 2020 · 1 revision

sensecap-webapi

The sensecap-webapi is a Java based project framework for managing and receiving state and data information of controllers and sensors

Environment

  • JDK1.8+
  • Maven3+
  • Mysql5.7+

Quick start

  1. Please download the source code of the project and extract it to obtain the SQL script for database initialization, and execute it to the database SQL file
  2. Decompress the source code, import the IDE, and compile with Maven
  3. Configure application.properties 
server.port=9001

#database connection string
spring.datasource.url=jdbc:mysql://host:port/dbSenscap4WebApi?useUnicode=true&characterEncoding=utf8&useSSL=false

#database user name
spring.datasource.username=username

#database password
spring.datasource.password=pwd

#database driver
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver


#switches API address
spring.dev.url=https://cn-api.coolkit.cn:8080

#switches API apikey
spring.dev.apikey=0f575df2-e7b5-4db3-b7c8-2f83caf60e81

#switches API authentication
spring.dev.at=481998354c0649219f46f51f86e9f235710551f8


#sensor's API url
spring.sensor.url=https://sensecap-openapi.seeed.cc/1.0

#sensor's MQTT Sever host address
spring.sensor.host=tcp://openstream.api.sensecap.seeed.cc

#sensor's MQTT ClientId
#If you need to deploy two computers for the same organization,
# make sure that this value is different between the two computers,
# you can change it to any random string
#spring.sensor.ClientId=random123
spring.sensor.ClientId=random

#sensor's API user's Organization Id
#Please log in to https://sensecap.seeed.cc/ with your account and get it.
#spring.sensor.OrganizationId=1
spring.sensor.OrganizationId=

#sensor's Access API Keys -> API ID
#Please log in to https://sensecap.seeed.cc/ with your account and get it.
#spring.sensor.APIID= 12345DFxxxxxx
spring.sensor.APIID=

#sensor's Access API Keys -> API key
#Please log in to https://sensecap.seeed.cc/ with your account and get it.
#spring.sensor.APIKey=12345ASDFxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
spring.sensor.APIKey=

API Key

  1. If the above configuration is correct, the project can be compiled, packaged and deployed

API

1. gets the list of controller switches / GET

/dev/list

Request parameters

Parameter Required Type Description
None - - -

Description of response parameter types

Parameter Type Description
id int Switch's unique identification
devId string Device's uniquely identified, usually with four pins per device
openOutlet int Pin number, starting from 0, a switch with only on and off states corresponds to a pin
closeOutlet int Pin number, starting from 0, this pin is required for the three-phase switch (which supports on/off/stop in three states), and the default is -1, which you can currently modify through the database
name string Switch's name
onOff int Switch status, 0: off, 1: on, -1: stop
online boolean Whether online
isuse boolean Whether isuse

The response data

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "id": 5,
            "devId": "10002dfebf",
            "openOutlet": 0,
            "closeOutlet": -1,
            "name": "Irrigation water pump",
            "onOff": 0,
            "online": false,
            "isuse": true
        },
        {
            "id": 6,
            "devId": "10002dfebf",
            "openOutlet": 1,
            "closeOutlet": -1,
            "name": "Ventilation fan",
            "onOff": 0,
            "online": false,
            "isuse": true
        },
        ...
    ]
}

2. Change the sensor name and enabled status / PATCH

/dev/update

Request parameters

Parameter Required Type Description
id Yes int Switch unique identification
name Yes string Change the name of the switch
isuse Yes boolean Whether to enable after modification

Description of response parameter types

Parameter Type Description
None - - 
{
    "code": 0,
    "msg": "success",
    "data": null
}

3. Operating switch / POST

/dev/switch

Request parameters

Parameter Required Type Description
id Yes int Switch unique identification
op Yes int Operation, 0: off, 1: on, -1: stop

Description of response parameter types

Parameter Type Description
None - -

The response data

{
    "code": 0,
    "msg": "success",
    "data": null
}

4. Get the current information of each sensor / GET

/sensor/node/currentvalues

Request parameters

Parameter Required Type Description
None - - -

Description of response parameter types

Parameter Type Description
dev_eui string Device's eui
dev_name string Device's name
measure_id int Measure ID
measure_Name string Measure Name
class_id int Measurement class ID: 1, environment 2, soil
class_Name string Name of measurement class
battery_status int Battery status: 1, sufficient 0, power shortage
online_status int Device online status: 1, online 0, not online
sensor_channel int Not to read
unit string Unit of measurement
value float Measurement reading
minval float The minimum value of the normal range
maxval float The maximum of the normal range
time long The time stamp

The response data

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "dev_eui": "2CF7F12212100097",
            "dev_name": "Equipment2CF7F12212100097",
            "measure_id": 4107,
            "measure_Name": "Luminous flux",
            "class_id": 2,
            "class_Name": "soil",
            "battery_status": 1,
            "online_status": 0,
            "sensor_channel": 1,
            "unit": "umol/㎡s",
            "value": 3.0,
            "minval": 0.0,
            "maxval": 2000.0,
            "time": 1575178701898
        },
        {
            "dev_eui": "2CF7F12210400097",
            "dev_name": "CarbonDioxide-2CF7F12210400097",
            "measure_id": 4100,
            "measure_Name": "Carbon dioxide",
            "class_id": 1,
            "class_Name": "environment",
            "battery_status": 1,
            "online_status": 0,
            "sensor_channel": 1,
            "unit": "ppm",
            "value": 374.0,
            "minval": 400.0,
            "maxval": 10000.0,
            "time": 1575179573201
        },
        ...
    ]
}

5. Obtain the latest n measurements of each sensor. / GET

/sensor/node/recentvalues

Request parameters

Parameter Required Type Description
count Yes int Read record number
Description of response parameter types
Parameter Type Description
dev_eui string Device's eui
dev_name string Device's name
measure_id int Measured ID
measure_name string Measured Name
unit string Unit of measurement
value float Measurement reading
minval float The minimum value of the normal range
maxval float The maximum of the normal range
time long The time stamp

The response data

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "dev_eui": "2CF7F1221210004C",
            "dev_name": "Air temperature and humidity-2CF7F1221210004C",
            "measure_id": 4097,
            "measure_name": "Air temperature",
            "unit": "℃",
            "value": 27.0,
            "minval": -40.0,
            "maxval": 90.0,
            "time": 1575181787444
        },
        {
            "dev_eui": "2CF7F1221210004C",
            "dev_name": "Air temperature and humidity-2CF7F1221210004C",
            "measure_id": 4098,
            "measure_name": "Air humidity",
            "unit": "%RH",
            "value": 47.0,
            "minval": 0.0,
            "maxval": 100.0,
            "time": 1575181787444
        },
        ...
    ]
}

6. Get each sensor warning record / GET

/sensor/node/warnings

Request parameters

Parameter Required Type Description
start Yes long Start timestamp
end Yes long End timestamp

Description of response parameter types

Parameter Type Description
dev_eui string Device's ID
dev_name string Device's Name
measure_id int Measured ID
measure_name string Measured Name
unit string Unit of measurement
value float Measurement reading
minval float The minimum value of the normal range
maxval float The maximum of the normal range
time long The time stamp

The response data

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "dev_eui": "2CF7F12210400097",
            "dev_name": "CarbonDioxide-2CF7F12210400097",
            "measure_id": 4100,
            "measure_name": "Carbon Dioxide",
            "unit": "ppm",
            "value": 399.0,
            "minval": 400.0,
            "maxval": 10000.0,
            "time": 1574092262298
        },
        {
            "dev_eui": "2CF7F12210400097",
            "dev_name": "CarbonDioxide-2CF7F12210400097",
            "measure_id": 4100,
            "measure_name": "Carbon Dioxide",
            "unit": "ppm",
            "value": 395.0,
            "minval": 400.0,
            "maxval": 10000.0,
            "time": 1574095907472
        },
        ...
    ]
}

7. Gets the measurement record of the specified sensor by time period / GET

/sensor/node/values

Request parameters

Parameter Required Type Description
dev_eui Yes string Device's eui
measure_id Yes int Measured ID
start Yes long Begin time stamp
end Yes long End time stamp

Description of response parameter types

Parameter Type Description
id int Recode ID
dev_eui string Device's eui
measure_id int Measured ID
channel int -
value float Measurement reading
time long The time stamp

The response data

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "id": 78,
            "dev_eui": "2CF7F1221210007C",
            "measure_id": 4104,
            "channel": 1,
            "value": 220.0,
            "time": 1574074321802
        },
        {
            "id": 92,
            "dev_eui": "2CF7F1221210007C",
            "measure_id": 4104,
            "channel": 1,
            "value": 220.0,
            "time": 1574077928137
        },
        ...
    ]
}

8. Get the sensors' status / GET

/sensor/node/resume

Request parameters

Parameter Required Type Description
None - - -

Description of response parameter types

Parameter Type Description
classId int Measurement class ID: 1, environment 2, soil
className string Name of measurement class
battery_full int Sufficient number of devices with batteries
battery_poor int The number of devices for power loss
onlineCount int Number of online devices
unlineCount int Number of unline devices

The response data

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "classId": 1,
            "className": "environment",
            "battery_full": 7,
            "battery_poor": 0,
            "onlineCount": 0,
            "unlineCount": 7
        },
        {
            "classId": 2,
            "className": "soil",
            "battery_full": 8,
            "battery_poor": 0,
            "onlineCount": 0,
            "unlineCount": 8
        }
    ]
}

9. Get the normal range of sensor measurements / GET

/sensor/node/normalranges

Request parameters

Parameter Required Type Description
None - - -

Description of response parameter types

Parameter Type Description
measure_id int Measured ID
measure_Name string Measured Name
unit string Unit of measurement
minval float The minimum value of the normal range
maxval float The maximum of the normal range

The response data

{
    "code": 0,
    "msg": "success",
    "data": [
        {
            "measure_id": 4097,
            "measure_Name": "The air temperature",
            "unit": "℃",
            "minval": -40.0,
            "maxval": 90.0
        },
        {
            "measure_id": 4098,
            "measure_Name": "Humidity of the air",
            "unit": "%RH",
            "minval": 0.0,
            "maxval": 100.0
        },
        ...
    ]
}

10. Modify the normal range of sensor measurements / PATCH

/sensor/node/changerange

Request parameters

Parameter Required Type Description
dev_eui Yes string Device's eui
measure_id Yes int Measured ID
minval Yes float The minimum value of the modified normal range
maxval Yes float The maximum value of the modified normal range

Description of response parameter types

Parameter Type Description
None - -

The response data

{
    "code": 0,
    "msg": "success",
    "data": null
}

sensecap-webapi

sensecap-webapi English sensecap-webapi 中文文档

sensecap-demo

sensecap-demo English sensecap-demo 中文文档

Clone this wiki locally