apiotics_aws_iot_client 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 9dcf9447f54d144c79fbc9aa1935c73e8e1c7e98
+  data.tar.gz: 72f4d3bfd7908fe2428125bd6b72b553b60c3607
+SHA512:
+  metadata.gz: 1e64f22d198216bd8f813252aa2dad798fd4346e4d0079b4f9510cafd53644ad3d25c055a2aad10f68565289678166226e4b5bb40fef06ffc5281ad660e527df
+  data.tar.gz: d454649ee4bb8e9944c4ccca8ed9c31ec63087b8a3096f9a4661051a200f73e0afe3f1288ed3d4ea9a569f0fddbd14889a9d7b2e6fb229f0a5b6d988b57b26e9

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http://contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in aws_iot.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright  2016 Ruby Development Inc.
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,207 @@
+<a href="https://codeclimate.com/repos/57d10b3aaee68e0a2d0016b7/feed"><img src="https://codeclimate.com/repos/57d10b3aaee68e0a2d0016b7/badges/aad862afb3ada6425b90/gpa.svg" /></a>
+[![Dependency Status](https://gemnasium.com/badges/github.com/RubyDevInc/aws-iot-device-sdk-ruby.svg)](https://gemnasium.com/github.com/RubyDevInc/aws-iot-device-sdk-ruby)
+[![Gem Version](https://badge.fury.io/rb/aws_iot_device.svg)](https://badge.fury.io/rb/aws_iot_device)
+
+# AWS IoT Device SDK for Ruby
+
+## Contents
+* [Dependencies](#dependencies)
+* [Overview](#overview)
+* [Installation](#installation)
+* [Usage](#usage)
+  * [Getting started](#getting-started)
+  * [Sample files](#sample-files)
+* [API Description](#api-description)
+  * [Shadow Client](#shadow-client)
+  * [Connection Mode](#connection-mode)
+  * [MQTT Adapter](#mqtt-adapter)
+* [License](#license)
+* [Contact](#contact)
+
+## Dependencies
+Ruby gems:
+- ruby >= 2.2
+- mqtt >= 0.0.2
+- json >= 2.0
+- facets >= 3.1
+- timers >= 4.1
+- paho-mqtt >= 0.0.2
+
+## Overview
+`aws_iot_device` is a gem that enables a remote client to communicate with the AWS IoT platform. The AWS IoT platform allows to register a device as a `thing`. The status of each `thing` is stored in a json format, referred as the `shadow` of a `thing`. The SDK uses the MQTT protocol to control the `thing` registered on the AWS IoT platform. The MQTT protocol is a lightweight protocol used to exchange short messages between a client and a message broker. The message broker is located on the AWS IoT platform, and the client is included in the `aws_iot_device` gem, the default client is the `paho-mqtt`. The `paho-mqtt` client has a MQTT API and a callback system to handle the events trigger by the mqtt packages.
+
+## Installation
+The gem is currentely in its first version, key features are available but any improvements is welcomed.  
+There are two ways to install the gem, from [rubygems](https://rubygems.org/gems/aws_iot_device) or directly from [sources](https://github.com/RubyDevInc/aws-iot-device-sdk-ruby).
+- From RubyGems:  
+The gem may be find on [RubyGems](https://rubygems.org/gems/aws_iot_device) and installed with the following command:
+```
+gem install aws_iot_device
+```
+
+- From sources:
+
+The gem could be download and installed manually:
+
+```
+git clone https://github.com/RubyDevInc/aws-iot-device-sdk-ruby.git
+cd aws-iot-device-sdk-ruby
+bundle install
+```
+## Usage
+### Getting started
+The following example is a strait-forward way for using shadows. Check at the samples files for more detailed usage.
+```ruby
+require "aws_iot_device"
+
+host = "AWS IoT endpoint"
+port = 8883
+thing = "Thing Name"
+
+root_ca_path = "Path to your CA certificate"
+private_key_path = "Path to your private key"
+certificate_path = "Path to your certificate"
+
+shadow_client = AwsIotDevice::MqttShadowClient::ShadowClient.new
+shadow_client.configure_endpoint(host, port)
+shadow_client.configure_credentials(root_ca_path, private_key_path, certificate_path)
+shadow_client.create_shadow_handler_with_name(thing, true)
+
+shadow_client.connect
+shadow_client.get_shadow do |message|
+  # Do what you want with the get_shadow's answer
+  # ...
+  p ":)"
+end
+sleep 2 #Timer to ensure that the answer is received
+
+shadow_client.disconnect
+```
+
+### Sample files
+Once you have cloned the current repository the several samples files provide test on the API a multiple levels.
+The shadow examples could be run with the following command :
+```
+ruby samples/shadow_client_samples/samples_shadow_client_xxx.rb -c "CERTIFICATE PATH" -k "PRIVATE KEY PATH"  -a "CA CERTIFICATE PATH" -H "AWS IOT ENDPOINT" -t "THING NAME"
+```
+
+## API Description
+Thank you very much for your interst in the `aws_iot_device` gem. The following part details all the features available with the SDK.
+
+### Shadow Client
+The shadow client API provide the key functions to control a thing/shadow on the Aws IoT platform. The methods contain in the API could be seperate in three differents roles, the configuration roles, the communication roles, and the treatements roles.
+
+#### Configuration role
+The Shadow client initializer would create the mqtt client used by the shadow client to communicate with the remote host. The parameters available on the initialization depend on the type of the chosen mqtt client. The default mqtt client type is the paho_client, the availables parameters are detailed in `paho-mqtt` gem [page](https://github.com/RubyDevInc/paho.mqtt.ruby#initialization).
+
+The remote host(endpoint) and port could be configured with the following method:
+```
+shaadow_client.configure_endpoint(host, port)
+```
+
+The encryption configuration could be done with the following method:
+```
+shadow_client.configure_credentials(root_ca_path, private_key_path, certificate_path)
+```
+
+The thing where the client would connect is done by the following method. The persitent_subscribe attribute is a boolean that would prevent the client to unsubscribe to the mqtt topic after every action. As the susbcription require a short time, for performace issues it might usefull to keep subscribed (default is `false`).
+```
+shadow_client.create_shadow_handler_with_name(thing, persistent_subscribe)
+
+```
+
+Finally, the connect method enable to send a connect request and (re)define some attributes threw a `Hash`. The available parameter are `:host`, `:port`, `:keep_alive`, `:persitent` and `:blocking`. `:persistent` and `:blocking` are detailed in the connection mode [section](#connection-mode)
+```
+shadow_client.connect
+```
+
+#### Communication role
+In the API there are three methods that directely act on the remote shadow. A `timeout` define the time until which the request should be considered as a failure. The default timeout is five second. The `get` and `delete` do not accept a payload where a json format payload is mandatory for the `update` action. 
+```
+timeout = 2
+
+shadow_client.get_shadow(timeout)
+
+payload = "{\"state: \": \"desired\": ..... }"
+shadow_client.update_shadow(payload)
+
+shadow_client.delete_shadow
+```
+
+#### Callbacks
+Callbacks are small piece of code that would be executed when the answer of one action is received by the client. The Shadow client API enables to register two kind of callbacks, a generic callback and single usage callback.
+For generic action (get, update, delete), the callback would be executed on every answer of the dedicated generic action. Futhermore, another callback may be executed for a single answer of a dedicated action. The generic callback could be seen as re-usable callback functions when the single usage could be seen as disposable treatment.
+Both kind of callbacks must be registered as a `block`, a `proc` or a `lambda`. The followings lines provide an examples of the different callbacks usage.
+```ruby
+# Register a callback for the get action as a block
+shadow_client.register_get_callback do
+  puts "generic callback for get action"
+end
+
+# Register a callback for the delete action as a proc
+shadow_client.register_delete_callback(proc { puts "generic callback for delete action"})
+
+# Register a callback for the update action as a lambda
+shadow_client.register_update_callback(lambda {|message| puts "genereic callback for update action"})
+
+# Register a callback for the delta events
+shadow_client.register_delta_callback do
+  puts "delta have been catch in a callback"
+end
+
+# Send a get request with an associated callback in a block
+shadow_client.get_shadow do
+  puts "get thing"
+end
+
+# Send a delete request with an associated callback in a proc
+shadow_client.delete_shadow(timeout, proc {puts "delete thing"})
+
+# Send a udpate request with an associated callback in a lambda
+shadow_client.update_shadow("{\"state\":{\"desired\":{\"message\":\"Hello\"}}}", timeout, lambda {|message| puts "update thing"})
+
+# Clear out the previously registered callback for each action
+shadow_client.remove_get_callback
+shadow_client.remove_update_callback
+shadow_client.remove_delete_callback
+shadow_client.remove_delta_callback
+```
+
+### Client persitences
+For performance issues, sometimes subscriptions and (re)connection time would better to saved. This could be done with two different persistences, the subscription persistence and the connection persistence. The subscription persistence keeps the shadow_client subscribed to action topics (get/accepted, get/rejected, update/accepted, update/rejected, delete/accepted and delete/rejected). The subscription process require a short time, the persistent subscription avoid to susbscribe before each and so saved the subscription time. The subscription persistence could be set at the initialization of the shadow handler or directely at the shadow client initialization.
+```ruby
+shadow_client = AwsIotDevice::MqttShadowClient::ShadowClient.new({:shadow_name => "Thing name", :persistent_subscribe => true})
+# Or
+shadow_client.create_shadow_handler_with_name(shadow_name, persistent_subscribe)
+```
+The default subscription persistence if desactivated, so the client might subscribe/unsubscribe to reserved topics before/after every actions.  
+  
+The connection persistence enables the client to keep the mqtt connection alive until the client explicitly requests to disconnect. The basic client would disconnect from the remote host if no activity has been detected for a preset keep_alive timer. There is two ways to configure the connection persistence, at the initialization of the shadow client or at the connection time.
+```ruby
+shadow_client = AwsIotDevice::MqttShadowClient::ShadowClient.new({:persistent => true})
+# Or
+shadow_client.connect({:persitent => true})
+```
+
+
+### MQTT Adapter
+The `aws-iot-device` gem is based on a MQTT client (`paho-mqtt`) that enables the usage of basic MQTT operations.  
+```ruby
+mqtt_client = AwsIoTDevice::MqttShadowClient::MqttManager.new
+
+mqtt_client.config_endpoint(host, port)
+mqtt_client.config_ssl_context(host, port)
+mqtt_client.connect
+
+mqtt_client.subscribe(topic, qos, callback)
+mqtt_client.publish(topic, "Hello world!", qos, retain)
+
+mqtt_client.unsubscribe(topic)
+mqtt_client.disconnect
+```
+For the default paho mqtt_client, some callbacks are available for each event related with the MQTT protocol. We recommend to read the `paho-mqtt` [gem page](https://github.com/RubyDevInc/paho.mqtt.ruby#handlers-and-callbacks) for more details about the mqtt callbacks usage.
+
+## License
+This SDK is distributed under the [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0).
+
+## Contact

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec