API Users Guide

This guide provides examples of how to combine Ayla APIs to complete tasks. Many of the examples refer to the devices in the table below, but the examples are generally applicable to many different types of devices:

product_name dsn model oem_model
Device 1 AC000W000000001 AY008ESP1 ledevb
Device 2 AC000W000000002 AY008ESP1 ledevb

See Ayla ESP32 Solution to set up an ESP32 development environment, build an application consisting of an Ayla agent and an example host application, flash it to your devices, configure the devices, and connect them to the Ayla Cloud.

Receive DSS events

The following steps shows you how to listen for datapoint and location events using DSS.

Get started

  1. Open the API Browser in a dedicated browser tab. Click the Accounts tab. Select a region. Input your email, password, app_id, app_secret. Click Get Tokens. Click the Accounts tab again to close it.
  2. Open the Ayla ESP32 Solution page in another dedicated tab, and follow the instructions on the page to establish an ESP32 development environment, and to connect one or more devices to the Ayla Cloud.

Create access rules

  1. Go to API Browser > Datastream Service > createAccessRule.
  2. Copy the following object into the Request Data box:
     {
       "role": "OEM::Admin",
       "oem_model": "*",
       "property_name": "*",
       "client_type": "cloud",
       "subscription_type": "datapoint"
     }
    
  3. Click Run, and then click Show. The response data provides the new access rule id:
     {
       "OemAccessRule": {
         "id": 123,
         "role": "OEM::Admin",
         "oem": "1234abcd",
         "property_name": "*",
         "oem_model": "*",
         "client_type": "cloud",
         "subscription_type": "datapoint",
         "access_grant": true,
         "created_at": "2020-01-01T17:09:13Z",
         "updated_at": "2020-01-01T17:09:13Z"
       }
     }
    
    This access rule allows OEM admins to subscribe to datapoint events.
  4. Create another rule allowing OEM admins to subscribe to location events.

Create subscriptions

  1. Go to API Browser > Datastream Service > createSubscription.
  2. Copy the following object into the Request Data box:
     {
       "name": "Datapoint Subscription",
       "description": "This subscription allows reception of datapoint events.",
       "dsn": "*",
       "oem_model": "ledevb",
       "property_name": "*",
       "client_type": "cloud",
       "subscription_type": "datapoint"
     }
    
  3. Click Run, and then click Show. The response data provides the new subscription key:
     {
       "subscription": {
         "id": 12345,
         "oem": "1234abcd",
         "dsn": "*",
         "name": "Datapoint Subscription",
         "description": "This subscription allows reception of datapoint events.",
         "property_name": "*",
         "connection_status": "Offline",
         "batch_size": 1,
         "is_suspended": false,
         "created_at": "2020-01-01T17:50:55Z",
         "updated_at": "2020-01-01T17:50:55Z",
         "date_suspended": null,
         "user_uuid": "b1234567-1234-1234-1234-a1234567890a",
         "oem_model": "ledevb",
         "stream_key": "ab12cd34ef56ab12cd34ef56ab12cd01",
         "client_type": "cloud",
         "subscription_type": "datapoint"
       }
     }
    
    This subscription allows the reception of datapoint events.
  4. Create another subscription allowing the reception of location events. Be sure to modify the name, description, and subscription_type of the request data.

Create events streams

  1. Click API Browser > Streams to open the Streams panel.
  2. Enter a stream name and a stream key (from the appropriate subscription). Leave start and end blank:
  3. Click Create:
    ES stands for Event Stream. The API Browser automatically numbers event streams. The Events column represents the number of events received by the stream. HBs stands for heartbeats. The Ayla Datastream Service sends heartbeats to listening WebSockets every 30 seconds. The HBs column represents the number of heartbeats received.
  4. Create a Location Stream:
  5. Close the Streams panel.

Monitor datapoint events

  1. Open the Devices and Events panels, and select Device 1 and Green_LED:
  2. Toggle the Green_LED property value several times to generate and receive several datapoint events:
  3. Click a datapoint row to see details:
  4. Change the values of other properties, and receive additional datapoint events.

Monitor location events

  1. Go to API Browser > Device Service > updateDeviceLocation.
  2. Enter an appropriate devId path parameter.
  3. Copy coordinates (e.g. Paris, France) into the Request Data box:
     {
       "location": {
         "lat": "48.864716",
         "long": "2.349014"
       }
     }
    
  4. Click Run.
  5. Check the Events panel:

Delete event streams

  1. Open the Streams panel, and select both streams:
  2. Click Delete.

Perform OTA update

The following steps show you how (over-the-air) to upgrade the Ayla agent and/or host app running on your devices.

  1. Open the API Browser in a dedicated browser tab. Click the Accounts tab. Select a region. Input your email, password, app_id, app_secret. Click Get Tokens. Click the Accounts tab again to close it.
  2. Open the Ayla ESP32 Solution page in another dedicated tab, and follow the instructions on the page to establish an ESP32 development environment, and connect one or more devices to the Ayla Cloud.
  3. In your Docker shell, cd /root/esp/esp-idf-v3.3.1/examples/ayla_demo/.
  4. Open main/demo_ledevb.c, and set the following constants to values of your choice like this:
     #define BUILD_PROGNAME "esp32"
     #define BUILD_VERSION "1.00"
    
  5. Run make and make flash to update the firmware on your device.
  6. Use the API Browser's Device Tab to verify your device's version property value in the cloud. Example:
     esp32 1.00 Mar 26 2020 16:38:39
    
  7. Increment BUILD_VERSION in demo_ledevb.c. Example:
     #define BUILD_VERSION "1.01"
    
  8. Run make, but do not flash the image to the device. Here is the location of the new image file:
     /root/esp/esp-idf-v3.3.1/examples/ayla_demo/build/ayla_demo.bin
    
  9. In a host terminal, copy the image file from the docker container to your host computer:
     $ docker cp ada16:/root/esp/esp-idf-v3.3.1/examples/ayla_demo/build/ayla_demo.bin .
    
  10. Rename the image file to indicate the version:
     $ mv ayla_demo.bin esp32_101.bin
    
  11. In the API Browser, click the IoT Command Center tile to reveal the IoT APIs.
  12. Run createImageRecord to create an image record using a request data object similar to the following:
     {
       "description": "esp32_101",
       "model": "ledevb",
       "version": "esp32_101"
     }
    
    Note the model and version values in the response data:
     {
       ...
       "model": "ledevb",
       "version": "esp32_101",
       ...
     }
    
  13. Run uploadImage to upload your image file, and associate it with the image record.
  14. Run getImageRecord to verify your work. The response data object reflects the size of the uploaded file.
     {
       ...
       "file_size": 1205232,
       "model": "ledevb",
       "version": "esp32_101",
       ...
     }
    
  15. Run createFilter to target the ESP32 device(s) you want to upgrade. ICC filters provide various ways of selecting device sets. The following request data object is one example:
     {
       "name": "My ESP32 Devices",
       "dsns": {
         "match": [
           "AC000W000000001",
           "AC000W000000002"
         ]
       },
       "oem_model": "ledevb"
     }
    
    Note the value of the filter id field (e.g. 6899) in the response data object.
  16. Run getFilter to verify that the filter was created.
  17. Run createJob with a request data object similar to the following:
     {
       "name": "Upgrade ESP32 devices to esp32_101",
       "type_id": "OTA",
       "filter_id": 6899,
       "exec_method": "ONE_TIME",
       "retries": 0
     }
    
    Note the value of the job id field (e.g. 5416) in the response data object.
  18. Run getJob to verify job information. Note status = CREATED.
  19. Run setOtaAction with a request data object similar to the following to associate an OTA action with the job:
     {
       "type": "host",
       "ayla_model": "ledevb",
       "version": "esp32_101"
     }
    
  20. Run startJob.

Update property values

The following steps show you how to set property values for groups of devices.

Get started

  1. Open the API Browser in a dedicated browser tab. Click the Accounts tab. Select a region. Input your email, password, app_id, app_secret. Click Get Tokens. Click the Accounts tab again to close it.
  2. Open the Ayla ESP32 Solution page in another dedicated tab, and follow the instructions on the page to establish an ESP32 development environment, and to connect one or more devices to the Ayla Cloud.

Initialize devices

  1. Go to API Browser > Devices.
  2. Select Device = Device 1, Property = Green_LED, and set to "on" (i.e. 1).
  3. Select Device = Device 2, Property = Green_LED, and set to "on" (i.e. 1).

Create a filter

  1. Go to API Browser > IoT Command Center > previewFilter.
  2. Copy the following filter request object into the Request Data box:
     {
       "name": "AY008ESP1 devices where Green_LED = 1",
       "description": "This filter uses an attribute array and a property array.",
       "attributes": [
         {
           "key": "model",
           "value": "AY008ESP1",
           "op": "="
         }
       ],
       "properties": [
         {
           "key": "Green_LED",
           "op": "=",
           "value": "1"
         }
       ],
       "oem_model": "ledevb"
     }
    
  3. Click Run, and then click Show. The response data is an array of filtered devices:
     {
       "total": 2,
       "oem_model": "ledevb",
       "devices": [
         {
           "lifecycle": "registered",
           "connection_status": "Online",
           "connected_at": "2019-12-23 00:00:00",
           "dsn": "AC000W000000001"
         },
         {
           "lifecycle": "registered",
           "connection_status": "Online",
           "connected_at": "2019-12-23 00:00:00",
           "dsn": "AC000W000000002"
         }
       ]
     }
    
  4. Go to API Browser > IoT Command Center > createFilter.
  5. Copy the same filter request object into the Request Data box:
  6. Click Run, and then click Show. The response data is a Filter Object. It should resemble the following:
     {
       "id": 2250,
       "name": "AY008ESP1 devices where Green_LED = 1",
       "description": "This filter uses an attribute array and a property array.",
       "attributes": [
         {
           "key": "model",
           "value": "AY008ESP1",
           "op": "="
         }
       ],
       "dsns": null,
       "properties": [
         {
           "key": "Green_LED",
           "value": "1",
           "metadata": null,
           "op": "="
         }
       ],
       "status": null,
       "oem_model": "ledevb",
       "device_metadata": null,
       "created_at": "2019-12-24T10:03:28+0000",
       "updated_at": "2019-12-24T10:03:28+0000",
       "filter_metadata": [],
       "oem_version": null,
       "match_oem_version": true
     }
    

Create a job

  1. Go to API Browser > IoT Command Center > createJob.
  2. Copy the following object into the Request Data box:
     {
       "name": "Set cmd and input",
       "description": "Set cmd and input for AY008ESP1 devices if Green_LED = 1",
       "type_id": "SET_PROPERTY",
       "filter_id": 2250,
       "exec_method": "ONE_TIME",
       "delivery_option": "SYSTEM_PUSH",
       "retries": 0
     }
    
  3. Click Run, and then click Show. The response data is a Job Object. It should resemble the following:
     {
       "id": 2444,
       "name": "Set cmd and input",
       "description": "Set cmd and input for AY008ESP1 devices if Green_LED = 1",
       "status": "CREATED",
       "payload": null,
       "type_id": 1,
       "filter": {
         "id": 2250,
         "name": "AY008ESP1 devices where Green_LED = 1",
         "description": "This filter uses an attribute array and a property array.",
         "attributes": [
           {
             "key": "model",
             "value": "AY008ESP1",
             "op": "="
           }
         ],
         "dsns": null,
         "properties": [
           {
             "key": "Green_LED",
             "value": "1",
             "metadata": null,
             "op": "="
           }
         ],
         "status": null,
         "oem_model": "ledevb",
         "device_metadata": null,
         "created_at": "2019-12-24T10:03:28+0000",
         "updated_at": "2019-12-24T10:03:28+0000",
         "filter_metadata": [],
         "oem_version": null,
         "match_oem_version": true
       },
       "filter_name": "AY008ESP1 devices where Green_LED = 1",
       "schedule_type": "IMMEDIATE",
       "started_at": null,
       "stopped_at": null,
       "created_at": "2019-12-24T10:16:12+0000",
       "updated_at": "2019-12-24T10:16:12+0000",
       "device_total": 0,
       "devices_processing": 0,
       "devices_succeed": 0,
       "devices_failed": 0,
       "job_metadata": [],
       "exec_method": "ONE_TIME",
       "delivery_option": "SYSTEM_PUSH",
       "job_type": "Set property"
     }
    

Configure the job

  1. Go to API Browser > IoT Command Center > setPropertiesForJob.
  2. For Path Parameters > jobId, enter your jobId.
  3. Copy the following object into the Request Data box:
     {
       "properties": [
         {
           "key": "cmd",
           "value": "CMD_1"
         },
         {
           "key": "input",
           "value": "1"
         }
       ]
     }
    
  4. Click Run, and then click Show. The response data should be the same as the request data.

Run the job

  1. Go to API Browser > IoT Command Center > startJob.
  2. For Path Parameters > jobId, enter your jobId.
  3. Click Run, and verify that the returned status code = 200.
  4. Go to API Browser > Devices.
  5. Select Device = Device 1, Property = cmd, and verify that value = CMD_1.
  6. Select Device = Device 1, Property = input, and verify that value = 1.
  7. Select Device = Device 2, and repeat for both properties.
  8. The log and output properties for both devices should be CMD_1 and 1, respectively, too.

Test the filter

  1. Go to API Browser > Devices.
  2. Select Device = Device 2, Property = Green_LED, and set to "off" (i.e. 0).
  3. Go to API Browser > IoT Command Center > setPropertiesForJob.
  4. Configure the job to set cmd = CMD_2 and input = 2.
  5. Go to API Browser > IoT Command Center > startJob, and run the job.
  6. Verify that the job targeted Device 1, but not Device 2.
  7. Reset Green_LED = 1 for Device 2.

Inspect job devices

  1. Go to API Browser > IoT Command Center > getDevicesSnapshot.
  2. For Path Parameters > jobId, enter your jobId.
  3. Click Run, and then click Show. The response data is an array of devices affected by the most recent job execution:
     {
       "total": 1,
       "oem_model": "ledevb",
       "devices": [
         {
           "lifecycle": "registered",
           "connection_status": "Online",
           "connected_at": "2019-12-23 00:00:00",
           "dsn": "AC000W000000001"
         }
       ],
       "previous_page": null,
       "next_page": null,
       "current_page_number": 1,
       "start_count_on_page": 1,
       "end_count_on_page": 1
     }
    
  4. Go to API Browser > IoT Command Center > setPropertiesForJob.
  5. Configure the job to set cmd = CMD_3 and input = 3.
  6. Go to API Browser > IoT Command Center > startJob, and run the job.
  7. Run getDevicesSnapshot again. The response data should resemble the following:
     {
       "total": 2,
       "oem_model": "ledevb",
       "devices": [
         {
           "lifecycle": "registered",
           "connection_status": "Online",
           "connected_at": "2019-12-23 00:00:00",
           "dsn": "AC000W000000001"
         },
         {
           "lifecycle": "registered",
           "connection_status": "Online",
           "connected_at": "2019-12-23 00:00:00",
           "dsn": "AC000W000000002"
         }
       ],
       "previous_page": null,
       "next_page": null,
       "current_page_number": 1,
       "start_count_on_page": 1,
       "end_count_on_page": 2
     }