Tamashii Agent [![Gem Version](https://badge.fury.io/rb/tamashii-agent.svg)](https://badge.fury.io/rb/tamashii-agent) 
===

Tamashii Agent is the client gem opposites to the server gem [Tamashii Manager](https://github.com/tamashii-io/tamashii-manager).

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 the following code to your `Gemfile`:

```ruby
gem 'tamashii-agent'
```

And then execute:
```
$ bundle install
```

Or install it yourself with:
```
$ gem install tamashii-agent
```

After installation, a new command line tool is provided as `tamashii-agent`. Get more information by executing 
```
$ tamashii-agent -h
```

### 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

### 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

To get the source code

    $ git clone git@github.com:tamashii-io/tamashii-agent.git

Initialize the development environment

    $ ./bin/setup

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/)