gobot.io/x/gobot/v2@v2.1.0/platforms/nats/README.md (about)

     1  # NATS
     2  
     3  NATS is a lightweight messaging protocol perfect for your IoT/Robotics projects. It operates over TCP, offers a great
     4  number of features but an incredibly simple Pub Sub style model of communicating broadcast messages. NATS is blazingly
     5  fast as it is written in Go.
     6  
     7  This repository contains the Gobot adaptor/drivers to connect to NATS servers. It uses the NATS Go Client available at
     8  <https://github.com/nats-io/nats>. The NATS project is a project part of the [CNCF](https://www.cncf.io/). Find more
     9  information on setting up a NATS server and its capability at <http://nats.io/>.
    10  
    11  The NATS messaging protocol (<http://www.nats.io/documentation/internals/nats-protocol-demo/>) is really easy to work
    12  with and can be practiced by setting up a NATS server using Go or Docker. For information on setting up a server using
    13  the source code, visit <https://github.com/nats-io/gnatsd>. For information on the Docker image up on Docker Hub, see
    14  <https://hub.docker.com/_/nats/>. Getting the server set up is very easy. The server itself is Golang, can be built for
    15  different architectures and installs in a small footprint. This is an excellent way to get communications going between
    16  your IoT and Robotics projects.
    17  
    18  ## How to Install
    19  
    20  Install running:
    21  
    22  ```sh
    23  go get -d -u gobot.io/x/gobot/v2/...
    24  ```
    25  
    26  ## How to Use
    27  
    28  Before running the example, make sure you have an NATS server running somewhere you can connect to (for demo purposes
    29  you could also use the public endpoint `demo.nats.io:4222`).
    30  
    31  ```go
    32  package main
    33  
    34  import (
    35    "fmt"
    36    "time"
    37  
    38    "gobot.io/x/gobot/v2"
    39    "gobot.io/x/gobot/v2/platforms/nats"
    40  )
    41  
    42  func main() {
    43    natsAdaptor := nats.NewAdaptor("nats://localhost:4222", 1234)
    44  
    45    work := func() {
    46      natsAdaptor.On("hello", func(msg nats.Message) {
    47        fmt.Printf("[Received on %q] %s\n", msg.Subject, string(msg.Data))
    48      })
    49      natsAdaptor.On("hola", func(msg nats.Message) {
    50        fmt.Printf("[Received on %q] %s\n", msg.Subject, string(msg.Data))
    51      })
    52  
    53      data := []byte("Hello Gobot!")
    54      gobot.Every(1*time.Second, func() {
    55        natsAdaptor.Publish("hello", data)
    56      })
    57      gobot.Every(5*time.Second, func() {
    58        natsAdaptor.Publish("hola", data)
    59      })
    60    }
    61  
    62    robot := gobot.NewRobot("natsBot",
    63      []gobot.Connection{natsAdaptor},
    64      work,
    65    )
    66  
    67    robot.Start()
    68  }
    69  ```
    70  
    71  To run with TLS enabled, set the URL scheme prefix to `tls://`. Make sure the NATS server has TLS enabled and use the
    72  NATS option parameters to pass in the TLS settings to the adaptor. Refer to the [github.com/nats-io/go-nats](https://github.com/nats-io/go-nats)
    73  README for more TLS option parameters.
    74  
    75  ```go
    76  package main
    77  
    78  import (
    79    "fmt"
    80    "time"
    81  
    82    natsio "github.com/nats-io/go-nats"
    83    "gobot.io/x/gobot/v2"
    84    "gobot.io/x/gobot/v2/platforms/nats"
    85  )
    86  
    87  func main() {
    88    natsAdaptor := nats.NewAdaptor("tls://localhost:4222", 1234, natsio.RootCAs("certs/ca.pem"))
    89  
    90    work := func() {
    91      natsAdaptor.On("hello", func(msg nats.Message) {
    92        fmt.Printf("[Received on %q] %s\n", msg.Subject, string(msg.Data))
    93      })
    94      natsAdaptor.On("hola", func(msg nats.Message) {
    95        fmt.Printf("[Received on %q] %s\n", msg.Subject, string(msg.Data))
    96      })
    97  
    98      data := []byte("Hello Gobot!")
    99      gobot.Every(1*time.Second, func() {
   100        natsAdaptor.Publish("hello", data)
   101      })
   102      gobot.Every(5*time.Second, func() {
   103        natsAdaptor.Publish("hola", data)
   104      })
   105    }
   106  
   107    robot := gobot.NewRobot("natsBot",
   108      []gobot.Connection{natsAdaptor},
   109      work,
   110    )
   111  
   112    robot.Start()
   113  }
   114  ```
   115  
   116  ### Supported Features
   117  
   118  * Publish messages
   119  * Respond to incoming message events
   120  * Support for Username/password authentication
   121  * Support for NATS adaptor options to support TLS
   122  
   123  ### Upcoming Features
   124  
   125  * Encoded messages (JSON)
   126  * Exposing more NATS Features (tls)
   127  * Simplified tests
   128  
   129  ## License
   130  
   131  Copyright (c) 2013-2018 The Hybrid Group. Licensed under the Apache 2.0 license.