@@ -146,6 +146,7 @@ def _on_disconnect_mqtt(self, client, userdata, return_code):
146
146
def _on_message_mqtt (self , client , topic , payload ):
147
147
"""Runs when the client calls on_message. Parses and returns
148
148
incoming data from Adafruit IO feeds.
149
+
149
150
:param MQTT client: A MQTT Client Instance.
150
151
:param str topic: MQTT topic response from Adafruit IO.
151
152
:param str payload: MQTT payload data response from Adafruit IO.
@@ -201,9 +202,9 @@ def add_feed_callback(self, feed_key, callback_method):
201
202
202
203
NOTE: The callback_method registered to this method
203
204
will only execute during loop().
205
+
204
206
:param str feed_key: Adafruit IO feed key.
205
207
:param str callback_method: Name of callback method.
206
-
207
208
"""
208
209
validate_feed_key (feed_key )
209
210
self ._client .add_topic_callback (
@@ -216,20 +217,21 @@ def remove_feed_callback(self, feed_key):
216
217
217
218
After this method is called, incoming messages
218
219
call the shared on_message.
219
- :param str feed_key: Adafruit IO feed key.
220
220
221
+ :param str feed_key: Adafruit IO feed key.
221
222
"""
222
223
validate_feed_key (feed_key )
223
224
self ._client .remove_topic_callback ("{0}/f/{1}" .format (self ._user , feed_key ))
224
225
225
226
def loop (self , timeout = 1 ):
226
227
"""Manually process messages from Adafruit IO.
227
228
Call this method to check incoming subscription messages.
229
+
228
230
:param int timeout: Socket timeout, in seconds.
229
231
230
232
Example usage of polling the message queue using loop.
231
233
232
- ..code-block:: python
234
+ .. code-block:: python
233
235
234
236
while True:
235
237
io.loop()
@@ -240,6 +242,7 @@ def loop(self, timeout=1):
240
242
def subscribe (self , feed_key = None , group_key = None , shared_user = None ):
241
243
"""Subscribes to your Adafruit IO feed or group.
242
244
Can also subscribe to someone else's feed.
245
+
243
246
:param str feed_key: Adafruit IO Feed key.
244
247
:param str group_key: Adafruit IO Group key.
245
248
:param str shared_user: Owner of the Adafruit IO feed, required for shared feeds.
@@ -283,6 +286,7 @@ def subscribe_to_errors(self):
283
286
284
287
def subscribe_to_randomizer (self , randomizer_id ):
285
288
"""Subscribes to a random data stream created by the Adafruit IO Words service.
289
+
286
290
:param int randomizer_id: Random word record you want data for.
287
291
"""
288
292
self ._client .subscribe (
@@ -292,6 +296,7 @@ def subscribe_to_randomizer(self, randomizer_id):
292
296
def subscribe_to_weather (self , weather_record , forecast ):
293
297
"""Subscribes to a weather forecast using the Adafruit IO PLUS weather
294
298
service. This feature is only avaliable to Adafruit IO PLUS subscribers.
299
+
295
300
:param int weather_record: Weather record you want data for.
296
301
:param str forecast: Forecast data you'd like to recieve.
297
302
"""
@@ -303,7 +308,9 @@ def subscribe_to_weather(self, weather_record, forecast):
303
308
304
309
def subscribe_to_time (self , time_type ):
305
310
"""Adafruit IO provides some built-in MQTT topics for getting the current server time.
311
+
306
312
:param str time_type: Current Adafruit IO server time. Can be 'seconds', 'millis', or 'iso'.
313
+
307
314
Information about these topics can be found on the Adafruit IO MQTT API Docs.:
308
315
https://io.adafruit.com/api/docs/mqtt.html#time-topics
309
316
"""
@@ -315,6 +322,7 @@ def subscribe_to_time(self, time_type):
315
322
def unsubscribe (self , feed_key = None , group_key = None , shared_user = None ):
316
323
"""Unsubscribes from an Adafruit IO feed or group.
317
324
Can also subscribe to someone else's feed.
325
+
318
326
:param str feed_key: Adafruit IO Feed key.
319
327
:param str group_key: Adafruit IO Group key.
320
328
:param str shared_user: Owner of the Adafruit IO feed, required for shared feeds.
@@ -337,7 +345,6 @@ def unsubscribe(self, feed_key=None, group_key=None, shared_user=None):
337
345
.. code-block:: python
338
346
339
347
client.unsubscribe('temperature', shared_user='adabot')
340
-
341
348
"""
342
349
if shared_user is not None and feed_key is not None :
343
350
validate_feed_key (feed_key )
@@ -361,10 +368,10 @@ def publish_multiple(self, feeds_and_data, timeout=3, is_group=False):
361
368
:param bool is_group: Set to True if you're publishing to a group.
362
369
363
370
Example of publishing multiple data points on different feeds to Adafruit IO:
364
- ..code-block:: python
365
371
366
- client.publish_multiple([('humidity', 24.5), ('temperature', 54)])
372
+ .. code-block:: python
367
373
374
+ client.publish_multiple([('humidity', 24.5), ('temperature', 54)])
368
375
"""
369
376
if isinstance (feeds_and_data , list ):
370
377
feed_data = []
@@ -393,38 +400,43 @@ def publish(self, feed_key, data, metadata=None, shared_user=None, is_group=Fals
393
400
:param bool is_group: Set True if publishing to an Adafruit IO Group.
394
401
395
402
Example of publishing an integer to Adafruit IO on feed 'temperature'.
396
- ..code-block:: python
403
+
404
+ .. code-block:: python
397
405
398
406
client.publish('temperature', 30)
399
407
400
408
Example of publishing a floating point value to feed 'temperature'.
401
- ..code-block:: python
409
+
410
+ .. code-block:: python
402
411
403
412
client.publish('temperature', 3.14)
404
413
405
414
Example of publishing a string to feed 'temperature'.
406
- ..code-block:: python
415
+
416
+ .. code-block:: python
407
417
408
418
client.publish('temperature, 'thirty degrees')
409
419
410
420
Example of publishing an integer to group 'weatherstation'.
411
- ..code-block:: python
421
+
422
+ .. code-block:: python
412
423
413
424
client.publish('weatherstation', 12, is_group=True)
414
425
415
426
Example of publishing to a shared feed.
416
- ..code-block:: python
427
+
428
+ .. code-block:: python
417
429
418
430
client.publish('temperature', shared_user='myfriend')
419
431
420
432
Example of publishing a value along with locational metadata to a feed.
421
- ..code-block:: python
433
+
434
+ .. code-block:: python
422
435
423
436
data = 42
424
437
# format: "lat, lon, ele"
425
438
metadata = "40.726190, -74.005334, -6"
426
439
io.publish("location-feed", data, metadata)
427
-
428
440
"""
429
441
validate_feed_key (feed_key )
430
442
if is_group :
@@ -445,10 +457,12 @@ def get(self, feed_key):
445
457
"""Calling this method will make Adafruit IO publish the most recent
446
458
value on feed_key.
447
459
https://io.adafruit.com/api/docs/mqtt.html#retained-values
460
+
448
461
:param str feed_key: Adafruit IO Feed key.
449
462
450
463
Example of obtaining a recently published value on a feed:
451
- ..code-block:: python
464
+
465
+ .. code-block:: python
452
466
453
467
io.get('temperature')
454
468
"""
@@ -461,9 +475,9 @@ class IO_HTTP:
461
475
Client for interacting with the Adafruit IO HTTP API.
462
476
https://io.adafruit.com/api/docs/#adafruit-io-http-api
463
477
464
- :param str adafruit_io_username: Adafruit IO Username
465
- :param str adafruit_io_key: Adafruit IO Key
466
- :param requests: A passed adafruit_requests module.
478
+ :param str adafruit_io_username: Adafruit IO Username
479
+ :param str adafruit_io_key: Adafruit IO Key
480
+ :param requests: A passed adafruit_requests module.
467
481
"""
468
482
469
483
def __init__ (self , adafruit_io_username , adafruit_io_key , requests ):
@@ -486,9 +500,9 @@ def _create_headers(io_headers):
486
500
@staticmethod
487
501
def _create_data (data , metadata ):
488
502
"""Returns a data payload as expected by the Adafruit IO HTTP API
503
+
489
504
:param data: Payload value.
490
505
:param dict metadata: Payload metadata.
491
-
492
506
"""
493
507
payload = {"value" : data }
494
508
if metadata : # metadata is expected as a dict, append key/vals
@@ -510,6 +524,7 @@ def _handle_error(response):
510
524
511
525
def _compose_path (self , path ):
512
526
"""Composes a valid API request path.
527
+
513
528
:param str path: Adafruit IO API URL path.
514
529
"""
515
530
return "https://io.adafruit.com/api/v2/{0}/{1}" .format (self .username , path )
@@ -518,6 +533,7 @@ def _compose_path(self, path):
518
533
def _post (self , path , payload ):
519
534
"""
520
535
POST data to Adafruit IO
536
+
521
537
:param str path: Formatted Adafruit IO URL from _compose_path
522
538
:param json payload: JSON data to send to Adafruit IO
523
539
"""
@@ -532,6 +548,7 @@ def _post(self, path, payload):
532
548
def _get (self , path ):
533
549
"""
534
550
GET data from Adafruit IO
551
+
535
552
:param str path: Formatted Adafruit IO URL from _compose_path
536
553
"""
537
554
response = self ._http .get (
@@ -545,6 +562,7 @@ def _get(self, path):
545
562
def _delete (self , path ):
546
563
"""
547
564
DELETE data from Adafruit IO.
565
+
548
566
:param str path: Formatted Adafruit IO URL from _compose_path
549
567
"""
550
568
response = self ._http .delete (
@@ -559,6 +577,7 @@ def _delete(self, path):
559
577
def send_data (self , feed_key , data , metadata = None , precision = None ):
560
578
"""
561
579
Sends value data to a specified Adafruit IO feed.
580
+
562
581
:param str feed_key: Adafruit IO feed key
563
582
:param str data: Data to send to the Adafruit IO feed
564
583
:param dict metadata: Optional metadata associated with the data
@@ -579,6 +598,7 @@ def send_data(self, feed_key, data, metadata=None, precision=None):
579
598
def send_batch_data (self , feed_key , data_list ):
580
599
"""
581
600
Sends a batch array of data to a specified Adafruit IO feed
601
+
582
602
:param str feed_key: Adafruit IO feed key
583
603
:param list Data: Data list to send
584
604
"""
@@ -591,6 +611,7 @@ def receive_all_data(self, feed_key):
591
611
"""
592
612
Get all data values from a specified Adafruit IO feed. Data is
593
613
returned in reverse order.
614
+
594
615
:param str feed_key: Adafruit IO feed key
595
616
"""
596
617
validate_feed_key (feed_key )
@@ -600,6 +621,7 @@ def receive_all_data(self, feed_key):
600
621
def receive_data (self , feed_key ):
601
622
"""
602
623
Return the most recent value for the specified feed.
624
+
603
625
:param string feed_key: Adafruit IO feed key
604
626
"""
605
627
validate_feed_key (feed_key )
@@ -609,6 +631,7 @@ def receive_data(self, feed_key):
609
631
def delete_data (self , feed_key , data_id ):
610
632
"""
611
633
Deletes an existing Data point from a feed.
634
+
612
635
:param string feed: Adafruit IO feed key
613
636
:param string data_id: Data point to delete from the feed
614
637
"""
@@ -620,6 +643,7 @@ def delete_data(self, feed_key, data_id):
620
643
def create_new_group (self , group_key , group_description ):
621
644
"""
622
645
Creates a new Adafruit IO Group.
646
+
623
647
:param str group_key: Adafruit IO Group Key
624
648
:param str group_description: Brief summary about the group
625
649
"""
@@ -630,6 +654,7 @@ def create_new_group(self, group_key, group_description):
630
654
def delete_group (self , group_key ):
631
655
"""
632
656
Deletes an existing group.
657
+
633
658
:param str group_key: Adafruit IO Group Key
634
659
"""
635
660
path = self ._compose_path ("groups/{0}" .format (group_key ))
@@ -638,16 +663,17 @@ def delete_group(self, group_key):
638
663
def get_group (self , group_key ):
639
664
"""
640
665
Returns Group based on Group Key
666
+
641
667
:param str group_key: Adafruit IO Group Key
642
668
"""
643
669
path = self ._compose_path ("groups/{0}" .format (group_key ))
644
670
return self ._get (path )
645
671
646
672
def create_feed_in_group (self , group_key , feed_name ):
647
673
"""Creates a new feed in an existing group.
674
+
648
675
:param str group_key: Group name.
649
676
:param str feed_name: Name of new feed.
650
-
651
677
"""
652
678
path = self ._compose_path ("groups/{0}/feeds" .format (group_key ))
653
679
payload = {"feed" : {"name" : feed_name }}
@@ -656,6 +682,7 @@ def create_feed_in_group(self, group_key, feed_name):
656
682
def add_feed_to_group (self , group_key , feed_key ):
657
683
"""
658
684
Adds an existing feed to a group
685
+
659
686
:param str group_key: Group
660
687
:param str feed_key: Feed to add to the group
661
688
"""
@@ -668,6 +695,7 @@ def add_feed_to_group(self, group_key, feed_key):
668
695
def get_feed (self , feed_key , detailed = False ):
669
696
"""
670
697
Returns an Adafruit IO feed based on the feed key
698
+
671
699
:param str feed_key: Adafruit IO Feed Key
672
700
:param bool detailed: Returns a more verbose feed record
673
701
"""
@@ -681,6 +709,7 @@ def get_feed(self, feed_key, detailed=False):
681
709
def create_new_feed (self , feed_key , feed_desc = None , feed_license = None ):
682
710
"""
683
711
Creates a new Adafruit IO feed.
712
+
684
713
:param str feed_key: Adafruit IO Feed Key
685
714
:param str feed_desc: Optional description of feed
686
715
:param str feed_license: Optional feed license
@@ -695,6 +724,7 @@ def create_and_get_feed(
695
724
):
696
725
"""
697
726
Attempts to return a feed; if the feed does not exist, it is created, and then returned.
727
+
698
728
:param str feed_key: Adafruit IO Feed Key
699
729
:param bool detailed: Returns a more verbose existing feed record
700
730
:param str feed_desc: Optional description of feed to be created
@@ -711,6 +741,7 @@ def create_and_get_feed(
711
741
def delete_feed (self , feed_key ):
712
742
"""
713
743
Deletes an existing feed.
744
+
714
745
:param str feed_key: Valid feed key
715
746
"""
716
747
validate_feed_key (feed_key )
@@ -722,6 +753,7 @@ def receive_weather(self, weather_id):
722
753
"""
723
754
Get data from the Adafruit IO Weather Forecast Service
724
755
NOTE: This service is avaliable to Adafruit IO Plus subscribers only.
756
+
725
757
:param int weather_id: ID for retrieving a specified weather record.
726
758
"""
727
759
path = self ._compose_path ("integrations/weather/{0}" .format (weather_id ))
@@ -730,6 +762,7 @@ def receive_weather(self, weather_id):
730
762
def receive_random_data (self , generator_id ):
731
763
"""
732
764
Get data from the Adafruit IO Random Data Stream Service
765
+
733
766
:param int generator_id: Specified randomizer record
734
767
"""
735
768
path = self ._compose_path ("integrations/words/{0}" .format (generator_id ))
0 commit comments