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