This gem was created in order to allow Ruby developers to interact with the Cassia Bluetooth Gateway API's https://www.cassianetworks.com/download/docs/Cassia_SDK_Implementation_Guide.pdf.
Add this line to your application's Gemfile:
gem 'cassia-ruby'
And then execute:
$ bundle
Or install it yourself as:
$ gem install cassia-ruby
Here is a list of the available configuration options and their default values
Option | Description | Optional |
---|---|---|
ac_url |
The URL of your AC server address | No |
client_id |
Your Cassia API Developer Key | No |
secret |
Your Cassia API Developer Secret | No |
client_cert |
Your SSL client cert | Yes |
client_key |
Your SSL client key | Yes |
ca_file |
Your SSL CA file | Yes |
ca_path |
The path to your SSL CA files | Yes |
To set configuration options use the Cassia.configure
method:
Cassia.configure do |config|
config.ac_url = ENV['CASSIA_AC_URL']
config.client_id = ENV['CASSIA_CLIENT_ID']
config.secret = ENV['CASSIA_SECRET']
end
In the following context, access_controller
is a Cassia::AccessController
object which contains attributes and structures of a Cassia access controller.
access_controller.get_token
access_controller.access_token
get_token
will make a request from access_controller
to generate an access token encoded from config.client_id
and config.secret
using base64.
access_token
will return the access token of access_controller
.
access_controller.get_all_routers_status
access_controller.routers
routers
will return an Array of Router
objects connected to access_controller
.
access_controller.switch_autoselect(flag: 1)
If flag
is 1, the router auto-selection function will be enabled. If flag
is 0, the router auto-selection function will be disabled.
access_controller.open_scan(aps: ["CC:1B:E0:E7:FE:F8", "CC:1B:E0:E7:FE:F8", "CC:1B:E0:E7:FE:F8"], chip: 0, active: 0, filter_name: "cassia", filter_mac: "CC:1B:E0:E7:FE:F7", filter_uuid: "00001800-0000-1000-800000805f9b34fb")
aps
is an array of one or multiple router's MAC address.
chip
(optional) means which chip to scan.
active
(optional) is either 0 or 1. 0 means enable passive scanning, 1 means enable active scanning.
filter_name
(optional) is a filter for device name.
filter_mac
(optional) is a filter for device MAC.
filter_uuid
(optional) is a filter for device UUID.
access_controller.close_scan(aps: ["CC:1B:E0:E7:FE:F8", "CC:1B:E0:E7:FE:F8", "CC:1B:E0:E7:FE:F8"])
aps
is an array of one or multiple router's MAC address.
access_controller.connect_device(aps: '*', device_mac: "CC:1B:E0:E7:FE:F8")
aps
is an array of one or multiple router's MAC address, or the string '*' which refers to all currently connected routers.
device_mac
is the mac address of the device that you are connecting to. You may only pass in one MAC address.
access_controller.disconnect_device(device_mac: "CC:1B:E0:E7:FE:F8")
device_mac
is the mac address of the device that you are disconnecting.
access_controller.open_notify(aps: ["CC:1B:E0:E7:FE:F8","CC:1B:E0:E7:FE:F8"])
aps
is an array of one or multiple router's MAC address.
access_controller.close_notify(aps: ["CC:1B:E0:E7:FE:F8","CC:1B:E0:E7:FE:F8"])
aps
is an array of one or multiple router's MAC address.
access_controller.open_connection_state(aps: ["CC:1B:E0:E7:FE:F8","CC:1B:E0:E7:FE:F8"])
aps
is an array of one or multiple router's MAC address.
access_controller.close_connection_state(aps: ["CC:1B:E0:E7:FE:F8","CC:1B:E0:E7:FE:F9"])
aps
is an array of one or multiple router's MAC address.
access_controller.open_ap_state
access_controller.close_ap_state
access_controller.combined_sse do |client|
client.on_event do |event|
puts "I received an event: #{event.type}, #{event.data}"
# put code here to act on events
end
client.on_error { |err| puts "#{err.status}" }
end
You can pass a block to the combined_sse method that allows you to act on the SSE's that you get from the routers.
We are using the https://github.com/launchdarkly/ruby-eventsource gem ld-eventsource for our SSE client. Please refer to their documentation for more info.
access_controller.discover_all_services(router: "CC:1B:E0:E7:FE:F8", device_mac: "CC:1B:E0:E7:FE:F9")
device.services
router
is the MAC address of the router that is currently connected to the access controller.
device_mac
is the mac address of the device that you are discovering all GATT services of.
device
is an Cassia::Device
object with mac address device_mac
. device.services
returns all GATT services provided by device
.
access_controller.discover_all_char(router: "CC:1B:E0:E7:FE:F8", device_mac: "CC:1B:E0:E7:FE:F9")
device.characteristics
router
is the MAC address of the router that is currently connected to the access controller.
device_mac
is the mac address of the device that you are discovering all GATT characteristics of.
device
is an Cassia::Device
object with mac address device_mac
. device.characteristics
returns all GATT characteristics of services provided by device
.
access_controller.discover_all_char(router: "CC:1B:E0:E7:FE:F8", device_mac: "CC:1B:E0:E7:FE:F9", service_uuid: "00001800-0000-1000-800000805f9b34fb")
service.characteristics
router
is the MAC address of the router that is currently connected to the access controller.
device_mac
is the mac address of the device that you are discovering GATT characteristics of.
servide_uuid
is the uuid of the service that you are discovering GATT characteristics of.
service
is an Cassia::Service
object with uuid service_uuid
. service.characteristics
returns all GATT characteristics of service
.
access_controller.discover_all_services_and_chars(router: "CC:1B:E0:E7:FE:F8", device_mac: "CC:1B:E0:E7:FE:F9")
device.services
device.characteristics
router
is the MAC address of the router that is currently connected to the access controller.
device_mac
is the mac address of the device that you are discovering GATT characteristics and services of.
device
is an Cassia::Device
object with mac address device_mac
. device.services
returns all GATT services provided by device
.
device.characteristics
returns all GATT characteristics of services provided by device
.
access_controller.write_char_by_handle(router: "CC:1B:E0:E7:FE:F8", device_mac: "CC:1B:E0:E7:FE:F9", handle: 3, value: "0100")
router
is the MAC address of the router that is currently connected to the access controller.
device_mac
is the mac address of the device that you are writing GATT characteristic to.
handle
is the handle of the characteristic that you are writing.
value
refers to the function you would like executed. To open the notification, set value
to "0100". To close the notification, set value
to "0000".
access_controller.open_char_notification(router: "CC:1B:E0:E7:FE:F8", device_mac: "CC:1B:E0:E7:FE:F9", handle: 3)
router
is the MAC address of the router that is currently connected to the access controller.
device_mac
is the mac address of the device whose characteristic is being turned on notification.
handle
is the handle of the characteristic that you are turning notification on.
access_controller.close_char_notification(router: "CC:1B:E0:E7:FE:F8", device_mac: "CC:1B:E0:E7:FE:F9", handle: 3)
router
is the MAC address of the router that is currently connected to the access controller.
device_mac
is the mac address of the device whose characteristic is being turned off notification.
handle
is the handle of the characteristic that you are turning notification off.
In the following context, router
is a Cassia::Router
object which contains attributes and structures of a router.
router.connect_local(access_controller, device_mac: "CC:1B:E0:E7:FE:F9", type: "random")
device_mac
is the mac address of the device that you are connecting router
to.
type
is the address type of the device, either "public" or "random".
router.disconnect_local(access_controller, device_mac: "CC:1B:E0:E7:FE:F9")
device_mac
is the mac address of the device that you are disconnecting from router
.
router.get_connected_devices(access_controller)
router.connected_devices
connected_devices
returns an Array of devices connected to router
.
router.discover_all_services(access_controller, device_mac: "CC:1B:E0:E7:FE:F9")
device.services
device_mac
is the mac address of the device that you are discovering all GATT services of.
device
is an Cassia::Device
object with mac address device_mac
. device.services
returns all GATT services provided by device
.
router.discover_all_char(access_controller, device_mac: "CC:1B:E0:E7:FE:F9")
device.characteristics
device_mac
is the mac address of the device that you are discovering all GATT characteristics of.
device
is an Cassia::Device
object with mac address device_mac
. device.characteristics
returns all GATT characteristics of services provided by device
.
router.discover_all_char(access_controller, device_mac: "CC:1B:E0:E7:FE:F9", service_uuid: "00001800-0000-1000-800000805f9b34fb")
service.characteristics
device_mac
is the mac address of the device that you are discovering GATT characteristics of.
servide_uuid
is the uuid of the service that you are discovering GATT characteristics of.
service
is an Cassia::Service
object with uuid service_uuid
. service.characteristics
returns all GATT characteristics of service
.
router.discover_all_services_and_chars(access_controller, device_mac: "CC:1B:E0:E7:FE:F9")
device.services
device.characteristics
device_mac
is the mac address of the device that you are discovering GATT characteristics and services of.
device
is an Cassia::Device
object with mac address device_mac
. device.services
returns all GATT services provided by device
.
device.characteristics
returns all GATT characteristics of services provided by device
.
router.write_char_by_handle(access_controller, device_mac: "CC:1B:E0:E7:FE:F9", handle: 3, value: "0100")
device_mac
is the mac address of the device that you are writing GATT characteristic to.
handle
is the handle of the characteristic that you are writing.
value
refers to the function you would like executed. To open the notification, set value
to "0100". To close the notification, set value
to "0000".
router.open_char_notification(access_controller, device_mac: "CC:1B:E0:E7:FE:F9", handle: 3)
device_mac
is the mac address of the device whose characteristic is being turned on notification.
handle
is the handle of the characteristic that you are turning notification on.
router.close_char_notification(access_controller, device_mac: "CC:1B:E0:E7:FE:F9", handle: 3)
device_mac
is the mac address of the device whose characteristic is being turned off notification.
handle
is the handle of the characteristic that you are turning notification off.
A class whose objects contain attributes of a characteristic of some service provided by a BLE device.
A class whose objects contain attributes of a BLE device.
A class whose objects contain attributes of a service provided by a BLE device.
After checking out the repo, run bin/setup
to install dependencies. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/iteratelabs/cassia-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Cassia::Ruby project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.