`adafruit_io`

A CircuitPython library for communicating with Adafruit IO.

Author(s): Brent Rubell for Adafruit Industries

Implementation Notes

Software and Dependencies:

Adafruit CircuitPython firmware for the supported boards:
https://github.com/adafruit/circuitpython/releases

class adafruit_io.adafruit_io.IO_HTTP(adafruit_io_username, adafruit_io_key, requests)

Client for interacting with the Adafruit IO HTTP API. https://io.adafruit.com/api/docs/#adafruit-io-http-api

Parameters:

adafruit_io_username (str) – Adafruit IO Username
adafruit_io_key (str) – Adafruit IO Key
requests – A passed adafruit_requests module.

add_feed_to_group(group_key: str, feed_key: str)

Adds an existing feed to a group

Parameters:

group_key (str) – Group
feed_key (str) – Feed to add to the group

create_and_get_feed(feed_key: str, detailed: bool = False, feed_desc: str | None = None, feed_license: str | None = None)

Attempts to return a feed; if the feed does not exist, it is created, and then returned.

Parameters:

feed_key (str) – Adafruit IO Feed Key
detailed (bool) – Returns a more verbose existing feed record
feed_desc (str) – Optional description of feed to be created
feed_license (str) – Optional feed license to be created

create_feed_in_group(group_key: str, feed_name: str)

Creates a new feed in an existing group.

Parameters:

group_key (str) – Group name.
feed_name (str) – Name of new feed.

create_new_feed(feed_key: str, feed_desc: str | None = None, feed_license: str | None = None)

Creates a new Adafruit IO feed.

Parameters:

feed_key (str) – Adafruit IO Feed Key
feed_desc (str) – Optional description of feed
feed_license (str) – Optional feed license

create_new_group(group_key: str, group_description: str)

Creates a new Adafruit IO Group.

Parameters:

group_key (str) – Adafruit IO Group Key
group_description (str) – Brief summary about the group

delete_data(feed_key: str, data_id: str)

Deletes an existing Data point from a feed.

Parameters:

feed (string) – Adafruit IO feed key
data_id (string) – Data point to delete from the feed

delete_feed(feed_key: str)

Deletes an existing feed.

Parameters:: feed_key (str) – Valid feed key

delete_group(group_key: str)

Deletes an existing group.

Parameters:: group_key (str) – Adafruit IO Group Key

get_current_usage()

Get current rate usage a.k.a “active_data_rate” for the current user.

See https://io.adafruit.com/api/docs/#get-detailed-user-info

get_feed(feed_key: str, detailed: bool = False)

Returns an Adafruit IO feed based on the feed key

Parameters:

feed_key (str) – Adafruit IO Feed Key
detailed (bool) – Returns a more verbose feed record

get_group(group_key: str)

Returns Group based on Group Key

Parameters:: group_key (str) – Adafruit IO Group Key

get_remaining_throttle_limit()

Get the remaining data points allowed before hitting the throttle limit. This retrieves the user rate limit and deducts usage for the current user.

See https://io.adafruit.com/api/docs/#get-detailed-user-info

get_throttle_limit()

Get user throttle limit a.k.a “data_rate_limit” for the current user.

See https://io.adafruit.com/api/docs/#get-detailed-user-info

get_user_info()

Get detailed account information for the current user.

See https://io.adafruit.com/api/docs/#get-user-info

get_user_rate_info()

Get rate limit and usage information for the current user.

See https://io.adafruit.com/api/docs/#get-detailed-user-info

Example output: ` { "data_rate_limit": 30, "active_data_rate": 0, "authentication_rate": 0, "subscribe_authorization_rate": 0, "publish_authorization_rate": 0, "hourly_ban_rate": 0, "mqtt_ban_error_message": null, "active_sms_rate": 0 } `

receive_all_data(feed_key: str)

Get all data values from a specified Adafruit IO feed. Data is returned in reverse order.

Parameters:: feed_key (str) – Adafruit IO feed key

receive_data(feed_key: str)

Return the most recent value for the specified feed.

Parameters:: feed_key (string) – Adafruit IO feed key

receive_n_data(feed_key: str, n_values: int)

Get most recent n data values from a specified feed. Data is returned in reverse order.

Parameters:

feed_key (str) – Adafruit IO feed key
n_values (int) – Number of data values

receive_random_data(generator_id: int)

Get data from the Adafruit IO Random Data Stream Service

Parameters:: generator_id (int) – Specified randomizer record

receive_time(timezone: str = None)

Returns a struct_time from the Adafruit IO Server based on the device’s IP address. https://circuitpython.readthedocs.io/en/latest/shared-bindings/time/__init__.html#time.struct_time The default time returned is based on the device’s IP address being geolocated, falling back to UTC if unable to be geolocated. The timezone can be manually set.

Parameters:: timezone (str) – Timezone to return time in, see https://io.adafruit.com/services/time

receive_weather(weather_id: int)

Get data from the Adafruit IO Weather Forecast Service NOTE: This service is avaliable to Adafruit IO Plus subscribers only.

Parameters:: weather_id (int) – ID for retrieving a specified weather record.

send_batch_data(feed_key: str, data_list: list)

Sends a batch array of data to a specified Adafruit IO feed

Parameters:

feed_key (str) – Adafruit IO feed key
Data (list) – Data list to send (namedtuples or dicts with ‘value’ key)

send_data(feed_key: str, data: str, metadata: dict | None = None, precision: int | None = None)

Sends value data to a specified Adafruit IO feed.

Parameters:

feed_key (str) – Adafruit IO feed key
data (str) – Data to send to the Adafruit IO feed
metadata (dict) – Optional metadata associated with the data
precision (int) – Optional amount of precision points to send with floating point data

send_group_data(group_key: str, feeds_and_data: list, metadata: dict | None = None)

Sends data to specified Adafruit IO feeds in a group

Parameters:

group_key (str) – Adafruit IO feed key
feeds_and_data (list) – A list of dicts, with feed “key” and “value” entries
metadata (dict) – Optional metadata for the data e.g. created_at, lat, lon, ele

class adafruit_io.adafruit_io.IO_MQTT(mqtt_client)

Client for interacting with Adafruit IO MQTT API. https://io.adafruit.com/api/docs/mqtt.html#adafruit-io-mqtt-api

Parameters:: mqtt_client (MiniMQTT) – MiniMQTT Client object.

add_feed_callback(feed_key: str, callback_method: Callable)

Attaches a callback_method to an Adafruit IO feed. The callback_method function is called when a new value is written to the feed.

NOTE: The callback_method registered to this method will only execute during loop().

Parameters:

feed_key (str) – Adafruit IO feed key.
callback_method (str) – Name of callback method.

connect(): Connects to the Adafruit IO MQTT Broker. Must be called before any other API methods are called.

disconnect(): Disconnects from Adafruit IO MQTT Broker.

get(feed_key: str)

Calling this method will make Adafruit IO publish the most recent value on feed_key. https://io.adafruit.com/api/docs/mqtt.html#retained-values

Parameters:: feed_key (str) – Adafruit IO Feed key.

Example of obtaining a recently published value on a feed:

io.get('temperature')

property is_connected: Returns if connected to Adafruit IO MQTT Broker.

loop(timeout=1)

Manually process messages from Adafruit IO. Call this method to check incoming subscription messages.

Parameters:: timeout (int) – Socket timeout, in seconds.

Example usage of polling the message queue using loop.

while True:
    io.loop()

publish(feed_key: str, data: str, metadata: str = None, shared_user: str = None, is_group: bool = False)

Publishes to an Adafruit IO Feed.

Parameters:

feed_key (str) – Adafruit IO Feed key.
data (float) – Data to publish to the feed or group.
data – Data to publish to the feed or group.
data – Data to publish to the feed or group.
metadata (str) – Optional metadata associated with the data.
shared_user (str) – Owner of the Adafruit IO feed, required for feed sharing.
is_group (bool) – Set True if publishing to an Adafruit IO Group.

Example of publishing an integer to Adafruit IO on feed ‘temperature’.

client.publish('temperature', 30)

Example of publishing a floating point value to feed ‘temperature’.

client.publish('temperature', 3.14)

Example of publishing a string to feed ‘temperature’.

client.publish('temperature, 'thirty degrees')

Example of publishing an integer to group ‘weatherstation’.

client.publish('weatherstation', 12, is_group=True)

Example of publishing to a shared feed.

client.publish('temperature', shared_user='myfriend')

Example of publishing a value along with locational metadata to a feed.

data = 42
# format: "lat, lon, ele"
metadata = "40.726190, -74.005334, -6"
io.publish("location-feed", data, metadata)

publish_multiple(feeds_and_data: List, timeout: int = 3, is_group: bool = False)

Publishes multiple data points to multiple feeds or groups with a variable timeout.

Parameters:

feeds_and_data (list) – List of tuples containing topic strings and data values.
timeout (int) – Delay between publishing data points to Adafruit IO, in seconds.
is_group (bool) – Set to True if you’re publishing to a group.

Example of publishing multiple data points on different feeds to Adafruit IO:

client.publish_multiple([('humidity', 24.5), ('temperature', 54)])

reconnect(): Attempts to reconnect to the Adafruit IO MQTT Broker.

remove_feed_callback(feed_key: str)

Removes a previously registered callback method from executing whenever feed_key receives new data.

After this method is called, incoming messages call the shared on_message.

Parameters:: feed_key (str) – Adafruit IO feed key.

subscribe(feed_key: str = None, group_key: str = None, shared_user: str | None = None)

Subscribes to your Adafruit IO feed or group. Can also subscribe to someone else’s feed.

Parameters:

feed_key (str) – Adafruit IO Feed key.
group_key (str) – Adafruit IO Group key.
shared_user (str) – Owner of the Adafruit IO feed, required for shared feeds.

Example of subscribing to an Adafruit IO Feed named ‘temperature’.

client.subscribe('temperature')

subscribe_to_errors(): Subscribes to your personal Adafruit IO /errors topic. Notifies you of errors relating to publish/subscribe calls.

subscribe_to_randomizer(randomizer_id: int)

Subscribes to a random data stream created by the Adafruit IO Words service.

Parameters:: randomizer_id (int) – Random word record you want data for.

subscribe_to_throttling(): Subscribes to your personal Adafruit IO /throttle topic. https://io.adafruit.com/api/docs/mqtt.html#mqtt-api-rate-limiting

subscribe_to_time(time_type: str)

Adafruit IO provides some built-in MQTT topics for getting the current server time.

Parameters:: time_type (str) – Current Adafruit IO server time. Can be ‘seconds’, ‘millis’, or ‘iso’.

Information about these topics can be found on the Adafruit IO MQTT API Docs.: https://io.adafruit.com/api/docs/mqtt.html#time-topics

subscribe_to_weather(weather_record: int, forecast: str)

Subscribes to a weather forecast using the Adafruit IO PLUS weather service. This feature is only avaliable to Adafruit IO PLUS subscribers.

Parameters:

weather_record (int) – Weather record you want data for.
forecast (str) – Forecast data you’d like to recieve.

unsubscribe(feed_key: str = None, group_key: str = None, shared_user: str | None = None)

Unsubscribes from an Adafruit IO feed or group. Can also subscribe to someone else’s feed.

Parameters:

feed_key (str) – Adafruit IO Feed key.
group_key (str) – Adafruit IO Group key.
shared_user (str) – Owner of the Adafruit IO feed, required for shared feeds.

Example of unsubscribing from a feed.

client.unsubscribe('temperature')

Example of unsubscribing from a shared feed.

client.unsubscribe('temperature', shared_user='adabot')

adafruit_io.adafruit_io.validate_feed_key(feed_key: str): Validates a provided feed key against Adafruit IO’s system rules. https://learn.adafruit.com/naming-things-in-adafruit-io/the-two-feed-identifiers

adafruit_io.adafruit_io.validate_n_values(n_values: int)

Validates a provided number of values to retrieve data from Adafruit IO.

Although Adafruit IO will accept values < 1 and > 1000, this avoids two types of issues: n_values < 1 (coding errors) and n_values > 1000 (pagination required for HTTP API)

adafruit_io

Implementation Notes

`adafruit_io`