README.md in tamashii-agent-0.3.1 vs README.md in tamashii-agent-0.3.3
- old
+ new
@@ -1,38 +1,251 @@
-# Tamashii::Agent
+Tamashii Agent [](https://badge.fury.io/rb/tamashii-agent)
+===
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/tamashii/agent`. To experiment with that code, run `bin/console` for an interactive prompt.
+Tamashii Agent is the client gem opposites to the server gem [Tamashii Manager](https://github.com/tamashii-io/tamashii-manager).
-TODO: Delete this and the text above, and describe your gem
+The Tamashii Agent runs on Raspberry PI. It manages the IoT components on the device and provides high-level API to let developers control the components easily.
+It is designed to integrate the devices into internet. With the help of [Tamashii Manager](https://github.com/tamashii-io/tamashii-manager), we can create IoT applications with Rails. The networking is based on [Tamashii Client](https://github.com/tamashii-io/tamashii-client).
+
+## Hardware Requirement
+
+Tamashii Agent is designed and tested on Raspberry PI 3 (running Raspbian Jessie). This readme will assume you are using the same version of Raspberry PI (newer versions should also be supported, however the configuration may differ).
+
+You need to install this gem on a real device to make it work. Following sections assume you are operating on a correctly configured Raspberry PI.
+
+>**Note**: we also provide **dummy** devices. These devices will simulate the behavior of those real devices such as RFID readers and buzzers. With them, the Tamashii Agent doesn't need to be executed on Raspberry PI. You can also run Tamashii Agent on non-Raspberry PI devices such as desktop Linux or Mac. Please refer to [this section](#dummy-devices).
+
+Tamashii Agent comes with some common hardware-related modules. They wrap the low-level operation of the devices.
+
+You can choose which components to be integrated into your application in [configuration file](#configuration-and-execution). Currently it supports the following hardware that can be attached to a Raspberry PI:
+
+- RFID/NFC modules
+ - MFRC522 RFID reader (SPI)
+ - PN532 NFC module (UART)
+- LCD Displays
+ - LCM 1602 (I2C)
+- Buzzers
+ - DC buzzer using PWM
+
+For pin layout of each component module, please refer to [this page](https://github.com/tamashii-io/tamashii-agent/tree/master/lib/tamashii/agent/device).
+
+
## Installation
-Add this line to your application's Gemfile:
+Add the following code to your `Gemfile`:
```ruby
gem 'tamashii-agent'
```
And then execute:
+```
+$ bundle install
+```
- $ bundle
+Or install it yourself with:
+```
+$ gem install tamashii-agent
+```
-Or install it yourself as:
+After installation, a new command line tool is provided as `tamashii-agent`. Get more information by executing
+```
+$ tamashii-agent -h
+```
- $ gem install tamashii-agent
+### Daemonize
+Although it is okay to run Tamashii Agent as a usual ruby program, Tamashii Agent usually runs as a system daemon on the Raspberry PI.
+
+This gem also provides a simple daemon installation for `systemd`.
+If you are using Raspberry PI running `systemd` (such as Raspbian Jessie), you can install daemon scripts by executing:
+```
+$ tamashii-agent --install-systemd
+```
+
+This will generate a `systemd` script `/etc/systemd/system/tamashii-agent.service` and a default configuration file `/etc/tamashii-agent-config.rb`. Modify them to match your need.
+
+
## Usage
-TODO: Write usage instructions here
+### Configuration and Execution
+Whether the Tamashii Agent is running as system daemon or simply as a ruby program, we need to write a configuration file for it. The default configuration generated by `tamashii-agent --install-systemd` is:
+
+```ruby
+Tamashii::Agent::config do
+ # these connection configuration will be forwarded to Tamashii Client
+ # please refer to configuration of Tamashii Client
+ use_ssl false
+ host "localhost"
+ port 3000
+ entry_point "/tamashii"
+ # where to output logs. Default is STDOUT
+ log_file "/var/log/tamashii-agent.log"
+ # the log level. Default is :DEBUG
+ log_level :INFO
+ # the authentication information. Must be the same as those in Tamashii Manager
+ auth_type :token
+ token "SECRET_TOKEN"
+end
+```
+
+The configuration above does not drive any extra components such as NFC readers or buzzers. It only establishs a connection to the [Tamashii Manager](https://github.com/tamashii-io/tamashii-manager) running on `localhost:3000`.
+
+- To run as system daemon:
+ - Put the configuration file in `/etc/tamashii-agent-config.rb`.
+ - Restart the agent by
+
+ ```
+ $ sudo systemctl restart tamashii-agent
+ ```
+
+- To execute Tamashii Agent as a usual ruby program
+ - Specify the path to the configuration file by `-C` option.
+ - For example, to load the configuration file in `/path/to/tamashii-agent-config.rb`:
+
+ ```
+ $ sudo tamashii-agent -C /path/to/tamashii-agent-config.rb
+ ```
+
+> Note: many hardware operations on Raspberry PI require root permission to access the IO. Don't forget to use `sudo` to run the agent command.
+
+### Simple Example for Testing Tamashii Agent
+
+The following program is a simple server based on [Tamashii Manager](https://github.com/tamashii-io/tamashii-manager). In this example, the Agent will play a beep sound when swiping the RFID card on the reader.
+
+> **Note**: you need to connect a RFID reader (either MFRC522 or PN532) and a DC buzzer to your Raspberry PI. Please refer to [this page](https://github.com/tamashii-io/tamashii-agent/tree/master/lib/tamashii/agent/device) about the setup details.
+
+> **Note**: the code below requires Tamashii Manager correctly installed on your system. You may need to install some dependencies such as `redis`.
+
+```ruby
+class MyPacketHook < Tamashii::Hook
+ def call(request_packet)
+ # we only cares about RFID NUMBER from agent
+ if request_packet.type == Tamashii::Type::RFID_NUMBER
+ # fetch client infomation from env
+ client = @env[:client]
+
+ # parse data in the packet (in json format)
+ json = JSON.parse(request_packet.body)
+ packet_id = json['id']
+ card_id = json['ev_body']
+
+ # build response in json format
+ type = Tamashii::Type::RFID_RESPONSE_JSON
+ body = {
+ id: packet_id,
+ ev_body: {
+ auth: true # true for 1 beep, false for 3 beeps
+ }.to_json
+ }.to_json
+
+ # build packet
+ response_packet = Tamashii::Packet.new(
+ type, client.tag, body
+ )
+ # send to client
+ client.send(response_packet.dump)
+ # return true means we have already handled this packet
+ return true
+ else
+ # return false so that the default handler can be executed
+ return false
+ end
+ end
+end
+
+Tamashii::Manager.config do |config|
+ config.port = 3000
+ # this pre-shared token can exclude the unwanted access
+ config.auth_type = :token
+ config.token = 'abc123'
+end
+
+Tamashii::Resolver.config do
+ # forward the packet to our hook
+ hook MyPacketHook
+end
+```
+
+Save the code above as `manager_config.rb`, then execute the following command to boot up Tamashii Manager.
+```
+$ tamashii-manager -C ./manager_config.rb
+```
+
+Now let's write a simple configuration for Tamashii Agent:
+```ruby
+Tamashii::Agent.config do
+ # The token must be same as server's
+ auth_type :token
+ token "abc123"
+ # Remember to change to your Tamashii Manager's hostname or IP!
+ host "tamashii.manager.local"
+ port 3000
+
+ # components to use
+ # the buzzer to play 'beep' sound. Assume the PWM buzzer is connected at pin 19
+ add_component :buzzer, 'Buzzer', device: 'PwmBuzzer', pin: 19
+
+ # card readers
+ # assume the PN532 NFC module is connected via UART interface
+ add_component :card_reader_felica, 'CardReader', device: 'Pn532Uart'
+ # uncomment following line if you are using MFRC522 via SPI interface
+ # add_component :card_reader_mfrc, 'CardReader', device: 'Mfrc522Spi'
+end
+```
+
+Save the code above as `agent_config.rb`, then execute following command to boot up Tamashii Agent.
+```
+$ sudo tamashii-agent -C ./agent_config.rb
+```
+
+Now you can swipe a card on the reader! You should hear a beep sound if everything works fine.
+
+## Dummy Devices
+
+Although the Tamashii Agent is designed to run on Raspberry PI, if you need to develop applications on non-Raspberry PI platforms, you can use the **Dummy** devices. Dummy devices simulate the behavior of RFID readers and buzzers. To use them, you need to specify the `Dummy` devices in the configuration file.
+
+For example, in the simple example mentioned above, you can change the configuration so that the example can run on non-Raspberry PI platforms:
+
+```ruby
+Tamashii::Agent.config do
+ # The token must be same as server's
+ auth_type :token
+ token "abc123"
+ # Remember to change to your Tamashii Manager's hostname or IP!
+ host "tamashii.manager.local"
+ port 3000
+
+ # dummy devices
+ add_component :buzzer, 'Buzzer', device: 'Dummy'
+ add_component :card_reader, 'CardReader', device: 'Dummy'
+end
+```
+
+The dummy buzzers will print the "beep sound" into the log file, while the dummy card reader generates random card uids periodically.
+
## Development
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+To get the source code
-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](https://rubygems.org).
+ $ git clone git@github.com:tamashii-io/tamashii-agent.git
-## Contributing
+Initialize the development environment
-Bug reports and pull requests are welcome on GitHub at https://github.com/lctseng/tamashii-agent.
+ $ ./bin/setup
-Contributed by [5xruby Inc.](https://5xruby.tw/)
+Run the spec
+
+ $ rspec
+
+Installation the version of development on localhost
+
+ $ bundle exec rake install
+
+## Contribution
+
+Please report to us on [Github](https://github.com/tamashii-io/tamashii-agent) if there is any bug or suggested modified.
+
+The project was developed by [5xruby Inc.](https://5xruby.tw/)