Skip to main content
  1. Wiliot
  2. Technical Resources
  3. New Cloud Platform

PyWiliot-api

Nir Drabkin
  • Updated

PyWiliot-api is a Python library allowing users to use Wiliot's APIs. This guide provides PyWiliot usage information.

Content

Installation

To install PyWiliot run

pip install wiliot-api

Usage

Authentication

PyWiliot handles the authentication and authorization required by Wiliot APIs. The user must provide PyWiliot with their Wiliot account credentials

Owner ID (Account)

Wiliot IoT pixels and other online assets are managed under owners (accounts). PyWiliot must be given an owner ID when instantiated. See examples below

Platform API

Create a client for the Platform API - you'll need to provide an API key. One can be generated following the instructions in this guide

from wiliot_api.platform.platform import *

my_api_key = "your API key copied from the platform"
owner = "my_company"

platform = PlatformClient(api_key=my_api_key, owner_id=owner)

Following are examples of common usages of Wiliot's Platform API

Pixels

Get a list of all an owner's (account's) pixels. 

platform.get_pixels()

Called like that the API will return a tuple containing two values: 

  • A list of the first 50 pixels
  • The ID of the next pixel (the 51st one)

To get a list of all pixel IDs under an account (not recommended for accounts with a large number of pixels), use this code

pixels = []
next_p = None
while True:
    p, next_p = platform.get_pixels(next=next_p)
    pixels += [p1['id'] for p1 in p]
    if next_p is None:
        break

Categories

See more information about categories here

Get a list of all categories

platform.get_categories()

Each category is based on an asset type, which dictates the minimum number of pixels that need to be applied to assets belonging to the category and the events generated for those assets. To get a list of all asset types, use this code

platform.get_asset_types()

To create a category, provide:

  • A base asset type ID
  • A category name
  • A category ID (optional - if none is provided an ID will be created automatically. This can be used to record SKU, for example)
  • Description (optional - visible in the platform Web UI)

The following code will create a new category

platform.create_category(name="Brown_folding_crate",
                         asset_type_id="Default",
                         category_id="brown-folding-crate",
                         description="A folding brown crate")

Assets

Assets represent any item with one or more pixels attached. Read more about assets here.

Get a list of all assets - warning, this call could take a long time to complete on accounts with a large number of assets.

platform.get_assets()

Get one asset using its ID.

platform.get_asset("some-asset-id")

Create an asset and assign one or more pixels to it. For each pixel, provide an ID and a role (for tracked assets, the role is DEFAULT)

platform.create_asset(name="brown_folding_crate_116872", 
                      category_id="brown-folding-crate",
                      asset_id="brown-folding-crate-116872",
                      pixels=[{"tagId": "pixel-1-id", "role": TagRole.DEFAULT},
                              {"tagId": "pixel-2-id", "role": TagRole.DEFAULT}])

Associate a pixel to an existing asset

platform.associate_pixel_to_asset(asset_id)

Asset Labels

Assets can have one or more labels associated with them. Each label is limited to 12 alphanumeric characters (no symbols). The following code adds a label to an asset

platform.create_asset_label(asset_id="my-asset-id", label="myassetlabel")

Note: All asset label function calls include a "project_id" parameter, which defaults to "Default". To ensure compatibility with future API versions, it is recommended to use this default value, so there is no need to pass it to any asset label function.

To get all asset labels, use the following code:

platform.get_asset_labels(asset_id="my-asset-id")

The following code will delete one asset label

platform.delete_asset_label(asset_id="my-asset-id", label="myassetlabel")

To delete all asset labels, use the following code

platform.delete_asset_labels(asset_id="my-asset-id")

Locations and Zones

For more information about locations and zones, see this guide.

To get a list of all locations defined under the account, use the following example

platform.get_locations()

Details about a single location can be retrieved using the following example

platform.get_location(location_id)

To create a new location, provide:

  • Location type - one of:
    • LocationType.SITE - for fixed locations (for example, warehouse)
    • LocationType.TRANSPORTER - for mobile locations (for example, truck)
  • Location name - a humanly readable name for the location (optional)
  • Latitude - optional, for fixed locations
  • Longitude - optional, for fixed locations
  • Address - optional, for fixed locations
  • City - optional, for fixed locations
  • Country - optional, for fixed locations

Note: It's possible to provide a location ID as well. If one is not provided, the location will be given an automatically generated ID. The following code will create a new location

platform.create_location(location_type=LocationType.SITE,
                         location_name="My new location",
                         lat=32.4854738,
                         lng=30.46452)

Zones are used to designate a smaller area within a location, for example, a room in a warehouse. Therefore, every operation on zones requires a location ID. To get a list of all zones under a location, use the following code:

platform.get_zones(location_id="some-location-id")

To create a new zone provide:

  • A location ID - An ID the zone will belong to
  • Name - A humanly readable name for the zone

Note: It's possible to provide a zone ID as well. If one is not provided, the zone will be given an automatically generated ID. The following code creates a new zone under an existing location:

platform.create_zone(name="Room 1",
                     location_id="warehouse-1-location-id")

Location and Zone Associations

Associations indicate to the Wiliot cloud where bridges/gateways are located. 

Locations support the following associations:

  • Bridges can be associated to a location
  • Gateways can be associated to a location

Zones support the following associations:

  • Bridges can be associated to a zone
  • Tags can be associated to a zone (to support reference tag-based location)

To list all of the associations for a location, use the following code:

platform.get_location_associations(zone_id="warehouse-location-id")

To list all of the associations for a zone, use the following code:

platform.get_zone_associations(zone_id="room-1-zone-id")

To create a new location association, provide:

  • Location ID
  • Association Type ( One of LocationAssociationType enums )
  • Association Value - the bridge ID or gateway ID
platform.create_location_association(location_id="warehouse-1-location-id",
                                     association_type=LocationAssociationType.BRIDGE,
                                     association_value"bridge-id")

To create a new zone association, provide:

  • Location ID
  • Zone ID
  • Association Type - ( One of ZoneAssociationType enums )
  • Association Value - The Bridge ID
platform.create_zone_association(location_id="warehouse-1-location-id",
                                 zone_id="room-1-zone-id",
                                 association_type=ZoneAssociationType.BRIDGE,
                                 association_value"bridge-id")

Delete a single location association using the following code:

platform.delete_location_association(location_id="warehouse-1-location-id",
                                     association_value="bridge-id")

Delete a single zone association using the following code:

platform.delete_zone_association(location_id="warehouse-1-location-id",
                                 zone_id="room-1-zone-id",
                                 association_value="bridge-id")

Delete all location associations for a single location (this is required before deleting a zone):

platform.delete_location_associations(location_id="warehouse-1-location-id")

Delete all zone associations for a single zone (this is required before deleting a zone):

platform.delete_zone_associations(location_id="warehouse-1-location-id",
                                  zone_id="room-1-zone-id")

Edge API

The Edge API allows access to all edge-device (bridges and gateways) related operations. Create a client using the following code

from wiliot_api.edge.edge import *

my_api_key = "your Edge API key copied from the platform"
owner = "my_company"

edge = EdgeClient(api_key=my_api_key, owner_id=owner)

Gateways

Get a list of owner's (account's) gateways

edge.get_gateways()

Get detailed information about one gateway

edge.get_gateway("gateway_id")

Register one or more Wiliot gateways

edge.register_gateway(["gateway_id"])

Approve a Wiliot gateway

edge.approve_gateway("gateway_id")

Update a gateway's configuration - requires providing a configuration dictionary as well as a list of gateway IDs to update. Refer to this guide for details about available configuration options. The following code demonstrates a common update sequence

existing_conf = w.get_gateway_details("gateway_id")
desired_conf = existing_conf["desiredConf"]

# Update one setting - in this case, the pacer interval
desired_conf["additional"]["pacerInterval"] = 60

edge.update_gateway_configuration(["gateway_id"], desired_conf)

Bridges

Get a list of bridges owned (claimed) by the account

edge.get_bridges()

Get information about a specific bridge

edge.get_bridge("bridge_id")

Claim a bridge

edge.claim_bridge("bridge_id")

Unclaim a bridge 

edge.unclaim_bridge("bridge_id")

Request an update of a bridge's configuration

# Get the bridge's current configuration
config = wiliot.get_bridge("bridge_id")["config"]
# Make the desired configuration change
config["pacerInterval"] = 60
# Request configuration update
wiliot.update_bridge_configuration("bridge_id", config)

Send an action to a bridge. Two actions are supported:

  • Reboot
  • Blink LED

Note: The bridge must be online for the call to succeed

from wiliot_api.edge.edge import BridgeAction

# Make a bridge blink its LED
edge.send_action_to_bridge(bridge_id="my-bridge-id", action=BridgeAction.BLINK_LED)

# Reboot a bridge
edge.send_action_to_bridge(bridge_id="my-bridge-id", action=BridgeAction.REBOOT)

 

Was this article helpful?
2 out of 2 found this helpful
Return to top

Comments

0 comments

Article is closed for comments.