API

adafruit_io

A CircuitPython library for communicating with Adafruit IO.

  • Author(s): Brent Rubell for Adafruit Industries

Implementation Notes

Software and Dependencies:

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

param str adafruit_io_username:
 Adafruit IO Username
param str adafruit_io_key:
 Adafruit IO Key
param requests:A passed adafruit_requests module.
add_feed_to_group(group_key, feed_key)

Adds an existing feed to a group :param str group_key: Group :param str feed_key: Feed to add to the group

create_feed_in_group(group_key, feed_name)

Creates a new feed in an existing group. :param str group_key: Group name. :param str feed_name: Name of new feed.

create_new_feed(feed_key, feed_desc=None, feed_license=None)

Creates a new Adafruit IO feed. :param str feed_key: Adafruit IO Feed Key :param str feed_desc: Optional description of feed :param str feed_license: Optional feed license

create_new_group(group_key, group_description)

Creates a new Adafruit IO Group. :param str group_key: Adafruit IO Group Key :param str group_description: Brief summary about the group

delete_data(feed_key, data_id)

Deletes an existing Data point from a feed. :param string feed: Adafruit IO feed key :param string data_id: Data point to delete from the feed

delete_feed(feed_key)

Deletes an existing feed. :param str feed_key: Valid feed key

delete_group(group_key)

Deletes an existing group. :param str group_key: Adafruit IO Group Key

get_feed(feed_key, detailed=False)

Returns an Adafruit IO feed based on the feed key :param str feed_key: Adafruit IO Feed Key :param bool detailed: Returns a more verbose feed record

get_group(group_key)

Returns Group based on Group Key :param str group_key: Adafruit IO Group Key

receive_all_data(feed_key)

Get all data values from a specified Adafruit IO feed. Data is returned in reverse order. :param str feed_key: Adafruit IO feed key

receive_data(feed_key)

Return the most recent value for the specified feed. :param string feed_key: Adafruit IO feed key

receive_random_data(generator_id)

Get data from the Adafruit IO Random Data Stream Service :param int generator_id: Specified randomizer record

receive_time()

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

receive_weather(weather_id)

Get data from the Adafruit IO Weather Forecast Service NOTE: This service is avaliable to Adafruit IO Plus subscribers only. :param int weather_id: ID for retrieving a specified weather record.

send_batch_data(feed_key, data_list)

Sends a batch array of data to a specified Adafruit IO feed :param str feed_key: Adafruit IO feed key :param list Data: Data list to send

send_data(feed_key, data, metadata=None, precision=None)

Sends value data to a specified Adafruit IO feed. :param str feed_key: Adafruit IO feed key :param str data: Data to send to the Adafruit IO feed :param dict metadata: Optional metadata associated with the data :param int precision: Optional amount of precision points to send with floating point data

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, callback_method)

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(). :param str feed_key: Adafruit IO feed key. :param str callback_method: 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)

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 :param str feed_key: Adafruit IO Feed key.

Example of obtaining a recently published value on a feed: ..code-block:: python

io.get(‘temperature’)
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. :param int timeout: Socket timeout, in seconds.

Example usage of polling the message queue using loop.

..code-block:: python

while True:
io.loop()
publish(feed_key, data, metadata=None, shared_user=None, is_group=False)

Publishes to an 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’. ..code-block:: python

client.publish(‘temperature’, 30)

Example of publishing a floating point value to feed ‘temperature’. ..code-block:: python

client.publish(‘temperature’, 3.14)

Example of publishing a string to feed ‘temperature’. ..code-block:: python

client.publish(‘temperature, ‘thirty degrees’)

Example of publishing an integer to group ‘weatherstation’. ..code-block:: python

client.publish(‘weatherstation’, 12, is_group=True)

Example of publishing to a shared feed. ..code-block:: python

client.publish(‘temperature’, shared_user=’myfriend’)

Example of publishing a value along with locational metadata to a feed. ..code-block:: python

data = 42 # format: “lat, lon, ele” metadata = “40.726190, -74.005334, -6” io.publish(“location-feed”, data, metadata)
publish_multiple(feeds_and_data, timeout=3, is_group=False)

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

Parameters:
  • feeds_and_data (str) – 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: ..code-block:: python

client.publish_multiple([(‘humidity’, 24.5), (‘temperature’, 54)])
reconnect()

Attempts to reconnect to the Adafruit IO MQTT Broker.

remove_feed_callback(feed_key)

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. :param str feed_key: Adafruit IO feed key.

subscribe(feed_key=None, group_key=None, shared_user=None)

Subscribes to your Adafruit IO feed or group. Can also subscribe to someone else’s feed. :param str feed_key: Adafruit IO Feed key. :param str group_key: Adafruit IO Group key. :param str shared_user: Owner of the Adafruit IO feed, required for shared feeds.

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

client.subscribe('temperature')

Example of subscribing to two Adafruit IO feeds: ‘temperature’ and ‘humidity’.

client.subscribe([('temperature'), ('humidity')])
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)

Subscribes to a random data stream created by the Adafruit IO Words service. :param int randomizer_id: 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)

Adafruit IO provides some built-in MQTT topics for getting the current server time. :param str time_type: 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, forecast)

Subscribes to a weather forecast using the Adafruit IO PLUS weather service. This feature is only avaliable to Adafruit IO PLUS subscribers. :param int weather_record: Weather record you want data for. :param str forecast: Forecast data you’d like to recieve.

unsubscribe(feed_key=None, group_key=None, shared_user=None)

Unsubscribes from an Adafruit IO feed or group. Can also subscribe to someone else’s feed. :param str feed_key: Adafruit IO Feed key. :param str group_key: Adafruit IO Group key. :param str shared_user: Owner of the Adafruit IO feed, required for shared feeds.

Example of unsubscribing from a feed.

client.unsubscribe('temperature')

Example of unsubscribing from two feeds: ‘temperature’ and ‘humidity’

client.unsubscribe([('temperature'), ('humidity')])

Example of unsubscribing from a shared feed.

client.unsubscribe('temperature', shared_user='adabot')
adafruit_io.adafruit_io.validate_feed_key(feed_key)

Validates a provided feed key against Adafruit IO’s system rules. https://learn.adafruit.com/naming-things-in-adafruit-io/the-two-feed-identifiers