API Reference

`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_air_quality(location: str, name: str | None = None, provider: str = 'open_meteo')

Create a new air quality integration record. NOTE: This service is available to Adafruit IO Plus subscribers only.

Parameters:

location (str) – Location in latitude,longitude format (e.g., “40.7128,-74.0060”)
name (str) – Optional friendly name for the location
provider (str) – Data provider, either “open_meteo” (default, global coverage) or “airnow” (US only, official EPA data)

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

create_weather(location: str, name: str | None = None, provider: str = 'open_meteo')

Create a new weather integration record. NOTE: This service is available to Adafruit IO Plus subscribers only.

Parameters:

location (str) – Location in latitude,longitude format (e.g., “40.7128,-74.0060”)
name (str) – Optional friendly name for the location
provider (str) – Data provider, default “open_meteo”

delete_air_quality(air_quality_id: int)

Permanently delete the specified air quality integration. NOTE: This service is available to Adafruit IO Plus subscribers only.

Parameters:: air_quality_id (int) – ID of the air quality integration to delete.

delete_data(feed_key: str, data_id: str)

Deletes an existing Data point from a feed.

Parameters:

feed_key (str) – Adafruit IO feed key
data_id (str) – 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

delete_weather(weather_id: int)

Permanently delete the specified weather integration. NOTE: This service is available to Adafruit IO Plus subscribers only.

Parameters:: weather_id (int) – ID of the weather integration to delete.

get_air_quality(): Get all air quality integration records without their current forecast values. NOTE: This service is available to Adafruit IO Plus subscribers only.

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 } `

get_weather(): Get all weather integration records without their current forecast values. NOTE: This service is available to Adafruit IO Plus subscribers only.

receive_air_quality(air_quality_id: int)

Get the specified air quality record with current air quality conditions and hourly forecast data including PM2.5, PM10, ozone, nitrogen dioxide, and other pollutants. NOTE: This service is available to Adafruit IO Plus subscribers only.

Parameters:: air_quality_id (int) – ID for retrieving a specified air quality record.

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 (str) – 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, feed_history_enabled: bool = True)

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.
feed_history_enabled (boolean) – Whether the feed history is enabled or not. If feed history is enabled the message size limit is 1kb, if disabled the message size limit is 100kb. The setting itself is controlled on the AIO web dashboard feed page. This argument just configures the limit locally.

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_air_quality(air_quality_record: int, forecast: str)

Subscribes to air quality updates using the Adafruit IO PLUS air quality service. This feature is only available to Adafruit IO PLUS subscribers.

Parameters:

air_quality_record (int) – Air quality record you want data for.
forecast (str) – Can be “current”, “forecast_today”, or “forecast_tomorrow”.

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 available to Adafruit IO PLUS subscribers.

Parameters:

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

Warning: The properties vary depending on the forecast type. Valid forecast types (different fields for days/mins/hours/current):
- current
- forecast_minutes_5
- forecast_minutes_30
- forecast_hours_1
- forecast_hours_2
- forecast_hours_6
- forecast_hours_24
- forecast_days_1
- forecast_days_2
- forecast_days_5

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')

unsubscribe_from_air_quality(air_quality_record: int, forecast: str)

Unsubscribe from air quality updates using the Adafruit IO PLUS air quality service. This feature is only available to Adafruit IO PLUS subscribers.

Parameters:

air_quality_record (int) – Air quality record you want to stop receiving data for.
forecast (str) – Forecast data you’d like to stop receiving.

unsubscribe_from_randomizer(randomizer_id: int)

Unsubscribe from a random data stream created by the Adafruit IO Words service.

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

unsubscribe_from_time(time_type: str)

Unsubscribe from Adafruit IO MQTT time topics.

Parameters:: time_type (str) – Time type to unsubscribe from, such as ‘seconds’, ‘millis’, ‘hours’, or ‘iso’.

unsubscribe_from_weather(weather_record: int, forecast: str)

Unsubscribe from weather forecast updates using the Adafruit IO PLUS weather service. This feature is only available to Adafruit IO PLUS subscribers.

Parameters:

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

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)

API Reference

adafruit_io

Implementation Notes

`adafruit_io`