diff --git a/docs/api.md b/docs/api.md index aafa426..b5aa608 100644 --- a/docs/api.md +++ b/docs/api.md @@ -2,8 +2,6 @@ title: API --- -# API - ## Reference API reference in the Swagger UI can be found at: [https://api.magistrala.abstractmachines.fr][api] @@ -2588,7 +2586,7 @@ Access-Control-Expose-Headers: Location ### Add policies -Only actions defined on [Predefined Policies section][predefined-policies] are allowed. +Only actions defined on Predefined Policies section are allowed. ```bash curl -sSiX POST http://localhost/users/policies -H "Content-Type: application/json" -H "Authorization: Bearer " -d @- << EOF @@ -2643,7 +2641,7 @@ Access-Control-Expose-Headers: Location ### Update policies -Only actions defined on [Predefined Policies section][predefined-policies] are allowed. +Only actions defined on Predefined Policies section are allowed. ```bash curl -sSiX PUT http://localhost/users/policies -H "Content-Type: application/json" -H "Authorization: Bearer " -d @- << EOF diff --git a/docs/architecture.md b/docs/architecture.md index f387bbe..c082dc9 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -2,8 +2,6 @@ title: Architecture --- -# Architecture - ## Components SuperMQ IoT platform is comprised of the following services: diff --git a/docs/authentication.md b/docs/authentication.md index 7c99d9a..ba1ac1d 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -2,7 +2,6 @@ title: Authentication --- -# Authentication ## User authentication diff --git a/docs/authorization.md b/docs/authorization.md index a8de403..5162418 100644 --- a/docs/authorization.md +++ b/docs/authorization.md @@ -2,8 +2,6 @@ title: Authorization --- -# Authorization - SuperMQ allows for fine-grained control over user permissions, taking into account hierarchical relationships between entities domains, groups, channels, and things. The structure and functionality of an authorization system implemented using [SpiceDB](https://github.com/authzed/spicedb) and its associated [schema language](https://authzed.com/docs/reference/schema-lang). `auth` service backed by SpiceDB manages permissions for users, domains, groups, channels, and things. ## Domains diff --git a/docs/benchmark.md b/docs/benchmark.md index 6bc774c..1c45564 100644 --- a/docs/benchmark.md +++ b/docs/benchmark.md @@ -2,8 +2,6 @@ title: Test Spec --- -# Test spec - ## Tools - [MZBench][mzbench] @@ -121,7 +119,7 @@ Testing environment to be determined. In this scenario, large number of requests are sent to HTTP adapter service every second. This test checks how much time HTTP adapter needs to respond to each request. -#### Results +#### Message Publishing Results TBD @@ -129,7 +127,7 @@ TBD In this scenario, large number of requests are sent to things service to create things and than to retrieve their data. This test checks how much time things service needs to respond to each request. -#### Results +#### Create and Get Client Results TBD diff --git a/docs/bootstrap.md b/docs/bootstrap.md index f753ac9..f68016d 100644 --- a/docs/bootstrap.md +++ b/docs/bootstrap.md @@ -2,8 +2,6 @@ title: Bootstrap --- -# Bootstrap - `Bootstrapping` refers to a self-starting process that is supposed to proceed without external input. SuperMQ platform supports bootstrapping process, but some of the preconditions need to be fulfilled in advance. The device can trigger a bootstrap when:s - device contains only bootstrap credentials and no SuperMQ credentials @@ -124,7 +122,7 @@ In order to disconnect, the same request should be sent with the value of `state ### Using curl request for secure bootstrap configuration -- *Encrypt the external key.* +- _Encrypt the external key._ First, encrypt the external key of your thing using AES encryption. The encryption key is specified by the `SMQ_BOOTSTRAP_ENCRYPT_KEY` environment variable. Use a library or utility that supports AES encryption to do this. Here's an example of how to encrypt using Go: @@ -132,53 +130,52 @@ First, encrypt the external key of your thing using AES encryption. The encrypti package main import ( - "crypto/aes" - "crypto/cipher" - "crypto/rand" - "fmt" - "io" + "crypto/aes" + "crypto/cipher" + "crypto/rand" + "fmt" + "io" ) type reader struct { - encKey []byte + encKey []byte } func (r reader) encrypt(in []byte) ([]byte, error) { - block, err := aes.NewCipher(r.encKey) - if err != nil { - return nil, err - } - ciphertext := make([]byte, aes.BlockSize+len(in)) - iv := ciphertext[:aes.BlockSize] - if _, err := io.ReadFull(rand.Reader, iv); err != nil { - return nil, err - } - stream := cipher.NewCFBEncrypter(block, iv) - stream.XORKeyStream(ciphertext[aes.BlockSize:], in) - return ciphertext, nil + block, err := aes.NewCipher(r.encKey) + if err != nil { + return nil, err + } + ciphertext := make([]byte, aes.BlockSize+len(in)) + iv := ciphertext[:aes.BlockSize] + if _, err := io.ReadFull(rand.Reader, iv); err != nil { + return nil, err + } + stream := cipher.NewCFBEncrypter(block, iv) + stream.XORKeyStream(ciphertext[aes.BlockSize:], in) + return ciphertext, nil } func main() { - data := []byte("") + data := []byte("") - r := reader{ - encKey: []byte(""), - } + r := reader{ + encKey: []byte(""), + } - encryptedData, err := r.encrypt(data) - if err != nil { - fmt.Println("Error encrypting data:", err) - return - } + encryptedData, err := r.encrypt(data) + if err != nil { + fmt.Println("Error encrypting data:", err) + return + } - fmt.Printf("%x\n", encryptedData) + fmt.Printf("%x\n", encryptedData) } ``` Replace `` and `` with the thing's external key and `SMQ_BOOTSTRAP_ENCRYPT_KEY` respectively. -- *Make a request to the bootstrap service.* - +- _Make a request to the bootstrap service._ Once the key is encrypted, make a request to the Bootstrap service. Here's how to do this using `curl`: @@ -196,7 +193,7 @@ curl --location 'http://localhost:9013/things/bootstrap/secure/' \ --header 'authorization: Thing ' --output ~/// ``` -- *Decrypt the response* +- _Decrypt the response_ Finally, decrypt the response using a function. Here's an example of how to do this using Go: @@ -204,38 +201,38 @@ Finally, decrypt the response using a function. Here's an example of how to do t package main import ( - "crypto/aes" - "crypto/cipher" - "log" - "os" + "crypto/aes" + "crypto/cipher" + "log" + "os" ) func main() { - encodedData, err := os.ReadFile("~///") - if err != nil { - log.Fatal(err) - } - - key := []byte("") - - block, err := aes.NewCipher(key) - if err != nil { - log.Fatal(err) - } - - if len(encodedData) < aes.BlockSize { - log.Fatal("ciphertext too short") - } - - iv := encodedData[:aes.BlockSize] - encodedData = encodedData[aes.BlockSize:] - stream := cipher.NewCFBDecrypter(block, iv) - stream.XORKeyStream(encodedData, encodedData) - - err = os.WriteFile("~///", encodedData, 0644) - if err != nil { - log.Fatal(err) - } + encodedData, err := os.ReadFile("~///") + if err != nil { + log.Fatal(err) + } + + key := []byte("") + + block, err := aes.NewCipher(key) + if err != nil { + log.Fatal(err) + } + + if len(encodedData) < aes.BlockSize { + log.Fatal("ciphertext too short") + } + + iv := encodedData[:aes.BlockSize] + encodedData = encodedData[aes.BlockSize:] + stream := cipher.NewCFBDecrypter(block, iv) + stream.XORKeyStream(encodedData, encodedData) + + err = os.WriteFile("~///", encodedData, 0644) + if err != nil { + log.Fatal(err) + } } ``` @@ -246,13 +243,13 @@ To use SuperMQ CLI for the secure bootstrap configuration, use the following com ```bash supermq-cli bootstrap secure ``` + for example ```bash supermq-cli bootstrap bootstrap secure '09:6:0:sb:sa' 'key' 'v7aT0HGxJxt2gULzr3RHwf4WIf6DusPp' ``` - For more information about the Bootstrap service API, please check out the [API documentation][api-docs]. [api-docs]: https://github.com/absmach/supermq/blob/main/api/openapi/bootstrap.yml diff --git a/docs/certs.md b/docs/certs.md index 3686f30..ad511a6 100644 --- a/docs/certs.md +++ b/docs/certs.md @@ -3,8 +3,6 @@ title: Certs --- -# Certs - Provisioning is a process of configuration of an IoT platform in which system operator creates and sets-up different entities used in the platform - users, groups, channels and things. ## Certs Service diff --git a/docs/cli.md b/docs/cli.md index af36864..edd80b8 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -2,7 +2,6 @@ title: CLI --- -# CLI SuperMQ CLI makes it easy to manage users, things, channels and messages. diff --git a/docs/dev-guide.md b/docs/dev-guide.md index b6634b6..6ea8b6d 100644 --- a/docs/dev-guide.md +++ b/docs/dev-guide.md @@ -2,7 +2,6 @@ title: Developer's Guide --- -# Developer's guide ## Getting SuperMQ @@ -17,7 +16,7 @@ cd $SOMEPATH/supermq ## Building -### Prerequisites +### Building Prerequisites Make sure that you have [Protocol Buffers][protocol-buffers] (version 21.12) compiler (`protoc`) installed. @@ -214,7 +213,7 @@ which will do this copying of the binaries. ## Deployment -### Prerequisites +### Deployment Prerequisites SuperMQ depends on several infrastructural services, notably the default message broker, [NATS][nats] and [PostgreSQL][postgresql] database. @@ -288,7 +287,6 @@ Please assure that MQTT microservice has `node_modules` installed, as explained [cleanup-docker]: #cleaning-up-your-dockerized-supermq-setup [docker-compose-ref]: https://docs.docker.com/compose/reference/overview/ [docker-compose-extend]: https://docs.docker.com/compose/extends/ -[increase-nodes-memory]: https://medium.com/tomincode/increasing-nodes-memory-337dfb1a60dd [go-cross-compile]: https://dave.cheney.net/2015/08/22/cross-compilation-with-go-1-5 [go-arm]: https://www.alexruf.net/golang/arm/raspberrypi/2016/01/16/cross-compile-with-go-1-5-for-raspberry-pi.html [wiki-go-arm]: https://go.dev/wiki/GoArm diff --git a/docs/edge.md b/docs/edge.md index 765a45c..9280a8f 100644 --- a/docs/edge.md +++ b/docs/edge.md @@ -3,8 +3,6 @@ title: Edge --- -# Edge - SuperMQ IoT platform provides services for supporting management of devices on the edge. Typically, IoT solution includes devices (sensors/actuators) deployed in far edge and connected through some proxy gateway. Although most devices could be connected to the SuperMQ directly, using gateways decentralizes system, decreases load on the cloud and makes setup less difficult. Also, gateways can provide additional data processing, filtering and storage. Services that can be used on gateway to enable data and control plane for edge: diff --git a/docs/entities.md b/docs/entities.md index 1115ee6..9e4c65f 100644 --- a/docs/entities.md +++ b/docs/entities.md @@ -3,8 +3,6 @@ title: Entities --- -# Entities - Client is a component that will replace and unify the SuperMQ Things and Users services. The purpose is to represent generic client accounts. Each client is identified using its identity and secret. The client will differ from Things service to Users service but we aim to achieve 1:1 implementation between the clients whilst changing how client secret works. This includes client secret generation, usage, modification and storage ## Generic Client Entity diff --git a/docs/events.md b/docs/events.md index 0ac5d8a..4e7087a 100644 --- a/docs/events.md +++ b/docs/events.md @@ -3,8 +3,6 @@ title: Events --- -# Events - In order to be easily integratable system, SuperMQ is using [Redis Streams][redis-streams] as an event log for event sourcing. Services that are publishing events to Redis Streams are `users` service, `things` service, `bootstrap` service and `mqtt` adapter. ## Users Service @@ -64,7 +62,7 @@ Whenever user is created, `users` service will generate new `create` event. This 16) "-small-flower@email.com" ``` -As you can see from this example, every odd field represents field name while every even field represents field value. This is standard event format for Redis Streams. If you want to extract `metadata` field from this event, you'll have to read it as string first and then you can deserialize it to some structured format. + As you can see from this example, every odd field represents field name while every even field represents field value. This is standard event format for Redis Streams. If you want to extract `metadata` field from this event, you'll have to read it as string first and then you can deserialize it to some structured format. 2. In Nats JetStream @@ -75,6 +73,7 @@ As you can see from this example, every odd field represents field name while ev ``` 3. In RabbitMQ Streams + ```json { "created_at": "2023-10-17T08:43:52.329385Z", @@ -614,7 +613,7 @@ Whenever group is created, `users` service will generate new `create` event. Thi 16) "e1b982d8-a332-4bc2-aaff-4bbaa86880fc" ``` -As you can see from this example, every odd field represents field name while every even field represents field value. This is standard event format for Redis Streams. If you want to extract `metadata` field from this event, you'll have to read it as string first and then you can deserialize it to some structured format. + As you can see from this example, every odd field represents field name while every even field represents field value. This is standard event format for Redis Streams. If you want to extract `metadata` field from this event, you'll have to read it as string first and then you can deserialize it to some structured format. 2. In Nats JetStream @@ -1115,7 +1114,7 @@ Whenever thing is created, `things` service will generate new `create` event. Th 16) "1693311470576589894" ``` -As you can see from this example, every odd field represents field name while every even field represents field value. This is standard event format for Redis Streams. If you want to extract `metadata` field from this event, you'll have to read it as string first and then you can deserialize it to some structured format. + As you can see from this example, every odd field represents field name while every even field represents field value. This is standard event format for Redis Streams. If you want to extract `metadata` field from this event, you'll have to read it as string first and then you can deserialize it to some structured format. 2. In Nats JetStreams @@ -1788,7 +1787,7 @@ Whenever channel list by thing is fetched, `things` service will generate new `l 14) "enabled" ``` -### Policy authorize event +### Thing Policy authorize event Whenever policy is authorized, `things` service will generate new `authorize` event. This event will have the following format: @@ -1828,7 +1827,7 @@ Whenever policy is authorized, `things` service will generate new `authorize` ev } ``` -### Policy add event +### Thing Policy add event Whenever policy is added, `things` service will generate new `add` event. This event will have the following format: @@ -1874,7 +1873,7 @@ Whenever policy is added, `things` service will generate new `add` event. This e } ``` -### Policy update event +### Thing Policy update event Whenever policy is updated, `things` service will generate new `update` event. This event will have the following format: @@ -1915,7 +1914,7 @@ Whenever policy is updated, `things` service will generate new `update` event. T } ``` -### Policy remove event +### Thing Policy remove event Whenever policy is removed, `things` service will generate new `remove` event. This event will have the following format: @@ -1955,7 +1954,7 @@ Whenever policy is removed, `things` service will generate new `remove` event. T } ``` -### Policy list event +### Thing Policy list event Whenever policy list is fetched, `things` service will generate new `list` event. This event will have the following format: diff --git a/docs/getting-started.md b/docs/getting-started.md index 727d812..d54c9b7 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -2,7 +2,6 @@ title: Getting Started --- -# Getting Started ## Step 1 - Run the System diff --git a/docs/index.md b/docs/index.md index efe5a9b..6cc02e8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,7 +2,6 @@ title: Overview --- -# Overview ## About diff --git a/docs/kubernetes.md b/docs/kubernetes.md index 55a68a5..d18f438 100644 --- a/docs/kubernetes.md +++ b/docs/kubernetes.md @@ -2,7 +2,6 @@ title: Kubernetes --- -# Kubernetes SuperMQ can be easily deployed on the Kubernetes platform using Helm Charts from the official [SuperMQ DevOps GitHub repository](https://github.com/absmach/devops). @@ -24,7 +23,7 @@ docker --version K3d is a lightweight Kubernetes distribution that runs inside Docker, ideal for local development. -#### Steps to install K3d: +#### Steps to install K3d ```bash curl -s https://raw.githubusercontent.com/k3d-io/k3d/main/install.sh | bash @@ -36,7 +35,7 @@ For more information on K3d, refer to the official [K3d documentation](https://k `kubectl` is the command-line tool used to interact with your Kubernetes cluster. -#### Steps to install kubectl: +#### Steps to install kubectl ```bash curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl" @@ -55,7 +54,7 @@ kubectl version --client Helm is a package manager for Kubernetes, simplifying application installation and management. -#### Steps to install Helm: +#### Steps to install Helm ```bash curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash @@ -71,7 +70,7 @@ helm version ### 5. Add Helm Repositories -#### Add Stable Helm Repository: +#### Add Stable Helm Repository The **Helm stable repository** contains Helm charts that you can use to install applications on Kubernetes. @@ -80,7 +79,7 @@ helm repo add stable https://charts.helm.sh/stable helm repo update ``` -#### Add Bitnami Helm Repository: +#### Add Bitnami Helm Repository Bitnami offers a collection of popular Helm charts for various applications. @@ -95,7 +94,7 @@ helm repo update The Nginx Ingress Controller manages external access to services within your Kubernetes cluster. -#### Install Nginx Ingress Controller using Helm: +#### Install Nginx Ingress Controller using Helm ```bash helm repo add ingress-nginx https://kubernetes.github.io/ingress-nginx @@ -118,7 +117,7 @@ kubectl get pods -n ingress-nginx This method involves **manually deploying SuperMQ** by cloning the Helm chart repository to your local machine, making any necessary customizations, and installing the chart from the local directory. -#### Use Case: +### Deploy Use Case This approach is useful if you want to: @@ -126,9 +125,9 @@ This approach is useful if you want to: - Modify the chart before installation. - Perform development or testing on the chart. -### Steps: +### Steps -#### 1. Clone SuperMQ Helm Chart Repository: +#### 1. Clone SuperMQ Helm Chart Repository ```bash git clone https://github.com/absmach/devops.git @@ -156,7 +155,7 @@ helm dependency update If the repositories are set up correctly, this will resolve and download all chart dependencies to `charts/magistrala/charts`. -### 3. Create a Namespace (if needed): +### 3. Create a Namespace (if needed) ```bash kubectl create namespace mg @@ -164,7 +163,7 @@ kubectl create namespace mg --- -### 4. Deploy SuperMQ: +### 4. Deploy SuperMQ Deploy the SuperMQ Helm chart into the `mg` namespace: @@ -218,11 +217,15 @@ The ingress-nginx-controller handles the routing for your deployed services usin You can usually find this IP address in your DigitalOcean dashboard under the "Networking" or "Load Balancers" section, or by using the following command in your terminal: +```bash kubectl get svc -A | grep LoadBalancer +``` This command searches all namespaces for services of type `LoadBalancer`. The output looks something like this: +```plaintext ingress-nginx ingress-nginx-controller LoadBalancer 10.245.192.202 138.68.126.8 80:30424/TCP,443:31752/TCP 64d +``` NOTE: The Public IP in this case is `138.68.126.8`. @@ -231,13 +234,15 @@ NOTE: The Public IP in this case is `138.68.126.8`. - Once you have the Public IP address, open your web browser. - In the address bar, enter the IP address followed by `/ui/login` as shown below: - http://138.68.126.8/ui/login +```plaintext + http://138.68.126.8/ui/login +``` #### Using Postman If you prefer working with APIs, you can also interact with SuperMQ services using Postman by sending requests to the Public IP address of your load balancer. For example, to create a user: -###### 1. Set Up the Postman Request +##### 1. Set Up the Postman Request - **Method:** `POST` - **URL:** `http://138.68.126.8/users` @@ -270,16 +275,16 @@ For more examples, refer to this [Postman Collection](https://elements.getpostma This method is the **standard installation** approach, where you install the SuperMQ chart directly from a Helm repository. This is quicker and ideal for end-users who do not need to modify the chart manually. -#### Use Case: +### Install Use Case This approach is suitable for: - End-users who simply want to install SuperMQ without modifying the source code. - Production environments where the chart is deployed directly from a hosted Helm repository. -### Steps: +### Install Steps -#### 1. Add the SuperMQ Helm Repository: +#### 1. Add the SuperMQ Helm Repository The Helm charts are published via GitHub Pages. After installing Helm, add the SuperMQ DevOps Helm repository by running: @@ -290,7 +295,7 @@ helm repo update For a complete list of all available flags to use with the `helm repo add [NAME] [URL] [flags]` command, run `helm repo add --help` -#### 2. Install the SuperMQ Chart: +#### 2. Install the SuperMQ Chart ```bash helm install magistrala-devops/magistrala [flags] @@ -306,7 +311,7 @@ helm install my-magistrala magistrala-devops/magistrala --version 0.14.0 --- -#### 3. Upgrading the SuperMQ Chart: +#### 3. Upgrading the SuperMQ Chart To upgrade the chart to a new version or update configurations: @@ -316,7 +321,7 @@ helm upgrade magistrala-devops/magistrala --- -#### 4. Uninstalling SuperMQ: +#### 4. Uninstalling SuperMQ To uninstall the SuperMQ release: @@ -328,7 +333,7 @@ This will remove the SuperMQ release from the previously created `mg` namespace. --- -### Customizing SuperMQ Installation: +### Customizing SuperMQ Installation To override values in the chart, use either the `--values` flag and pass in a file or use the `--set` flag and pass configuration from the command line, to force a string value use `--set-string`. You can use `--set-file` to set individual values from a file when the value itself is too long for the command line or is dynamically generated. You can also use `--set-json` to set json values (scalars/objects/arrays) from the command line. @@ -480,11 +485,6 @@ You can test sending an MQTT message with the following command: mosquitto_pub -d -L mqtts://:@example.com:8883/channels//messages --cert thing.crt --key thing.key --cafile ca.crt -m "test-message" ``` -[devops-repo]: https://github.com/absmach/devops -[kubernetes-setup]: https://kubernetes.io/docs/setup/ -[kubectl-setup]: https://kubernetes.io/docs/tasks/tools/install-kubectl/ -[helm-setup]: https://helm.sh/docs/intro/install/ -[nginx-ingress]: https://kubernetes.github.io/ingress-nginx/deploy/ [ingress-yaml]: https://github.com/absmach/devops/blob/master/charts/mainflux/templates/ingress.yaml#L141 [ingress-controller-args]: https://kubernetes.github.io/ingress-nginx/user-guide/cli-arguments/ [ingress-controller-tcp-udp]: https://kubernetes.github.io/ingress-nginx/user-guide/exposing-tcp-udp-services/ diff --git a/docs/lora.md b/docs/lora.md index 4e7b09c..16b9023 100644 --- a/docs/lora.md +++ b/docs/lora.md @@ -2,7 +2,6 @@ title: LoRa --- -# LoRa Bridging with LoRaWAN Networks can be done over the [lora-adapter][lora-adapter]. This service sits between SuperMQ and [LoRa Server][lora-server] and just forwards the messages from one system to another via MQTT protocol, using the adequate MQTT topics and in the good message format (JSON and SenML), i.e. respecting the APIs of both systems. diff --git a/docs/messaging.md b/docs/messaging.md index 8aace66..22e4e92 100644 --- a/docs/messaging.md +++ b/docs/messaging.md @@ -2,7 +2,6 @@ title: Messaging --- -# Messaging Once a channel is provisioned and thing is connected to it, it can start to publish messages on the channel. The following sections will provide an example of message publishing for each of the supported protocols. @@ -103,74 +102,74 @@ ws.on("error", (e) => { package main import ( - "log" - "os" - "os/signal" - "time" + "log" + "os" + "os/signal" + "time" - "github.com/gorilla/websocket" + "github.com/gorilla/websocket" ) var done chan interface{} var interrupt chan os.Signal func receiveHandler(connection *websocket.Conn) { - defer close(done) + defer close(done) - for { - _, msg, err := connection.ReadMessage() - if err != nil { - log.Fatal("Error in receive: ", err) - return - } + for { + _, msg, err := connection.ReadMessage() + if err != nil { + log.Fatal("Error in receive: ", err) + return + } - log.Printf("Received: %s\n", msg) - } + log.Printf("Received: %s\n", msg) + } } func main() { - done = make(chan interface{}) - interrupt = make(chan os.Signal) - - signal.Notify(interrupt, os.Interrupt) - - channelId := "30315311-56ba-484d-b500-c1e08305511f" - thingSecret := "c02ff576-ccd5-40f6-ba5f-c85377aad529" - - socketUrl := "ws://localhost:8186/channels/" + channelId + "/messages/?authorization=" + thingSecret - - conn, _, err := websocket.DefaultDialer.Dial(socketUrl, nil) - if err != nil { - log.Fatal("Error connecting to Websocket Server: ", err) - } else { - log.Println("Connected to the ws adapter") - } - defer conn.Close() - - go receiveHandler(conn) - - for { - select { - - case <-interrupt: - log.Println("Interrupt occured, closing the connection...") - conn.Close() - err := conn.WriteMessage(websocket.TextMessage, []byte("closed this ws client just now")) - if err != nil { - log.Println("Error during closing websocket: ", err) - return - } - - select { - case <-done: - log.Println("Receiver Channel Closed! Exiting...") - - case <-time.After(time.Duration(1) * time.Second): - log.Println("Timeout in closing receiving channel. Exiting...") - } - return - } - } + done = make(chan interface{}) + interrupt = make(chan os.Signal) + + signal.Notify(interrupt, os.Interrupt) + + channelId := "30315311-56ba-484d-b500-c1e08305511f" + thingSecret := "c02ff576-ccd5-40f6-ba5f-c85377aad529" + + socketUrl := "ws://localhost:8186/channels/" + channelId + "/messages/?authorization=" + thingSecret + + conn, _, err := websocket.DefaultDialer.Dial(socketUrl, nil) + if err != nil { + log.Fatal("Error connecting to Websocket Server: ", err) + } else { + log.Println("Connected to the ws adapter") + } + defer conn.Close() + + go receiveHandler(conn) + + for { + select { + + case <-interrupt: + log.Println("Interrupt occured, closing the connection...") + conn.Close() + err := conn.WriteMessage(websocket.TextMessage, []byte("closed this ws client just now")) + if err != nil { + log.Println("Error during closing websocket: ", err) + return + } + + select { + case <-done: + log.Println("Receiver Channel Closed! Exiting...") + + case <-time.After(time.Duration(1) * time.Second): + log.Println("Timeout in closing receiving channel. Exiting...") + } + return + } + } } ``` @@ -344,7 +343,7 @@ Key features of VerneMQ include: - Lower Total Cost of Ownership (TCO): VerneMQ offers a favourable TCO compared to many messaging Platform-as-a-Service (PaaS) solutions. - Full MQTT Support: VerneMQ implements the full MQTT 3.1, 3.1.1, and 5.0 specifications, including various QoS levels, authentication and authorization options, TLS/SSL encryption, WebSockets support, clustering, and more. -#### Architecture +#### Vernemq MQTT Architecture VerneMQ is designed from the ground up to work as a distributed message broker, ensuring continued operation even in the event of node or network failures. It can easily scale both horizontally and vertically to handle large numbers of concurrent clients. @@ -379,7 +378,7 @@ jetstream { These are the default values but you can change them by editing the configuration file. For more information about nats configuration checkout [official nats documentation][nats-jestream]. The health check endpoint is exposed on `SMQ_NATS_HTTP_PORT` and its `/healthz` path. -#### Architecture +#### NATS JetStream Architecture The main reason for using Nats with JetStream enabled is to have a distributed system with high availability and minimal dependencies. Nats is configure to run as the default message broker, but you can use any other message broker supported by SuperMQ. Nats is configured to use JetStream, which is a distributed streaming platform built on top of nats. JetStream is used to store messages and to provide high availability. This makes nats to be used as the default event store, but you can use any other event store supported by SuperMQ. Nats with JetStream enabled is also used as a key-value store for caching purposes. This makes nats to be used as the default cache store, but you can use any other cache store supported by SuperMQ. @@ -391,7 +390,7 @@ Since SuperMQ uses a configurable message broker, you can use RabbitMQ as a mess Since SuperMQ is using `rabbitmq:3.9.20-management-alpine` docker image, the management console is available at port `SMQ_RABBITMQ_HTTP_PORT` -#### Architecture +#### RabbitMQ Architecture SuperMQ has one exchange for the entire platform called `messages`. This exchange is of type `topic`. The exchange is `durable` i.e. it will survive broker restarts and remain declared when there are no remaining bindings. The exchange does not `auto-delete` when all queues have finished using it. When declaring the exchange `no_wait` is set to `false` which means that the broker will wait for a confirmation from the server that the exchange was successfully declared. The exchange is not `internal` i.e. other exchanges can publish messages to it. @@ -416,7 +415,7 @@ Since SuperMQ uses a configurable message broker, you can use Kafka as a message SuperMQ utilizes `spotify/kafka:latest` docker image. The image also exposes `kafka:9092` and `zookeeper:2181` ports. This is used for development purposes only. For production, it is assumed that you have your own Kafka cluster. -##### Architecture +#### Kafka Architecture The publisher implementation is based on the `segmentio/kafka-go` library. Publishing messages is well supported by the library, but subscribing to topics is not. The library does not provide a way to subscribe to all topics, but only to a specific topic. This is a problem because the SuperMQ platform uses a topic per channel, and the number of channels is not known in advance. The solution is to use the Zookeeper library to get a list of all topics and then subscribe to each of them. The list of topics is obtained by connecting to the Zookeeper server and reading the list of topics from the `/brokers/topics` node. The first message published from the topic can be lost if subscription happens closely followed by publishing. After the subscription, we guarantee that all messages will be received. diff --git a/docs/opcua.md b/docs/opcua.md index 3ff33ae..29ee01d 100644 --- a/docs/opcua.md +++ b/docs/opcua.md @@ -2,7 +2,6 @@ title: OPC-UA --- -# OPC-UA OPC Unified Architecture (OPC-UA) is a communication protocol and framework that is widely used in industrial automation and the Industrial Internet of Things (IIoT). It provides a standard platform for connecting industrial devices and systems, allowing them to share data and information seamlessly. Data from the devices is sent to the OPC-UA Server where a client can consume it. @@ -113,7 +112,7 @@ To forward OPC-UA messages the opcua-adapter subscribes to the Node ID of an OPC ### Sample Use Case -The OPC-UA adapter can be used in an industrial setup to monitor process values from the different industrial devices and machines. The industrial devices which are controlled by controllers such as PLCs (Programmable Logic Controllers) send data to the OPC-UA server over TCP/IP, with each device containing a specific node ID. +The OPC-UA adapter can be used in an industrial setup to monitor process values from the different industrial devices and machines. The industrial devices which are controlled by controllers such as PLCs (Programmable Logic Controllers) send data to the OPC-UA server over TCP/IP, with each device containing a specific node ID. Things on SuperMQ can be created to represent these devices and the channels can be created to represent the data points on the devices. The OPC-UA adapter can then be used to subscribe to the OPC-UA server and forward the data to the NATS message broker. This data can then be consumed by other services in the SuperMQ system, and further processing done if need be. diff --git a/docs/provision.md b/docs/provision.md index fee55f4..0f72b7d 100644 --- a/docs/provision.md +++ b/docs/provision.md @@ -2,7 +2,6 @@ title: Provision --- -# Provision Provisioning is a process of configuration of an IoT platform in which system operator creates and sets-up different entities used in the platform - users, groups, channels and things. diff --git a/docs/security.md b/docs/security.md index e6e4142..855dc24 100644 --- a/docs/security.md +++ b/docs/security.md @@ -2,7 +2,6 @@ title: Security --- -# Security ## Server Configuration diff --git a/docs/smq-contrib.md b/docs/smq-contrib.md index e07ddc4..56fa634 100644 --- a/docs/smq-contrib.md +++ b/docs/smq-contrib.md @@ -2,10 +2,9 @@ title: SMQ-Contrib Repository --- -# SMQ-Contrib Repository -The **SuperMQ-Contrib** repository serves as a collection of additional services, tools, and extensions that complement the SuperMQ platform. -These contributions include features that did not make it into the main SuperMQ platform but are invaluable for specific use cases. +The **SuperMQ-Contrib** repository serves as a collection of additional services, tools, and extensions that complement the SuperMQ platform. +These contributions include features that did not make it into the main SuperMQ platform but are invaluable for specific use cases. The repository acts as a playground for exploring and testing new ideas and contributions to the ecosystem. This repository is an excellent starting point for developers looking to contribute new features or experiment with custom services and integrations for SuperMQ. @@ -13,8 +12,9 @@ This repository is an excellent starting point for developers looking to contrib ## Available Services in smq-contrib ### LoRa -The **[LoRa Adapter][lora]** bridges SuperMQ with LoRaWAN networks. -It forwards messages between SuperMQ and a LoRaWAN Server using MQTT while adhering to JSON and SenML formats. + +The **[LoRa Adapter][lora]** bridges SuperMQ with LoRaWAN networks. +It forwards messages between SuperMQ and a LoRaWAN Server using MQTT while adhering to JSON and SenML formats. This adapter is ideal for users integrating low-power, wide-area devices into the SuperMQ ecosystem. - [Learn more about the LoRa Adapter](./lora.md) @@ -22,7 +22,8 @@ This adapter is ideal for users integrating low-power, wide-area devices into th --- ### OPC-UA -The **[OPC-UA Adapter][opcua]** serves as a bridge between SuperMQ and OPC-UA servers, enabling seamless communication with industrial devices. + +The **[OPC-UA Adapter][opcua]** serves as a bridge between SuperMQ and OPC-UA servers, enabling seamless communication with industrial devices. It supports browse and subscription methods for retrieving data from nodes on the OPC-UA server and forwards this data to the SuperMQ platform. - [Learn more about the OPC-UA Adapter](./opcua.md) @@ -30,6 +31,7 @@ It supports browse and subscription methods for retrieving data from nodes on th --- ### Twins Service + The **[Twins Service][twins]** introduces the concept of digital twins to SuperMQ. Digital twins provide a unified, abstract representation of complex real-world systems. The Twins Service maintains a history of system states, definitions, and metadata, offering an enhanced way to monitor and manage interconnected devices. @@ -79,4 +81,3 @@ The **SuperMQ-Contrib** repository complements the SuperMQ platform by extending [influx]: https://github.com/absmach/smq-contrib/tree/main/readers/influxdb [readers]: https://github.com/absmach/smq-contrib/tree/main/readers [consumers]: https://github.com/absmach/smq-contrib/tree/main/consumers - diff --git a/docs/storage.md b/docs/storage.md index 87711a1..2f2f553 100644 --- a/docs/storage.md +++ b/docs/storage.md @@ -2,7 +2,6 @@ title: Storage --- -# Storage SuperMQ supports various storage databases in which messages are stored: diff --git a/docs/tracing.md b/docs/tracing.md index 354192a..ccfb1b2 100644 --- a/docs/tracing.md +++ b/docs/tracing.md @@ -2,7 +2,6 @@ title: Tracing --- -# Tracing Distributed tracing is a method of profiling and monitoring applications. It can provide valuable insight when optimizing and debugging an application. SuperMQ includes the [Jaeger][jaegertracing] open tracing framework as a service with its stack by default. diff --git a/docs/twins.md b/docs/twins.md index f716ffb..a312a43 100644 --- a/docs/twins.md +++ b/docs/twins.md @@ -2,7 +2,6 @@ title: Twins Service --- -# Twins Service SuperMQ twins service is built on top of the SuperMQ platform. In order to fully understand what follows, be sure to get acquainted with [overall SuperMQ architecture][architecture]. @@ -291,7 +290,7 @@ curl -s -S -i -X DELETE -H "Authorization: Bearer " http://localhost ## STATES operations -### List +### STATES List ```bash curl -s -S -i -X GET -H "Authorization: Bearer " http://localhost:9018/states/ diff --git a/src/components/HomepageFeatures/index.tsx b/src/components/HomepageFeatures/index.tsx index 2845d57..b19ba03 100644 --- a/src/components/HomepageFeatures/index.tsx +++ b/src/components/HomepageFeatures/index.tsx @@ -20,19 +20,19 @@ const FeatureList: FeatureItem[] = [ description: ( <> - SuperMQ provides a robust middleware for IoT, supporting HTTP, MQTT, WebSocket, and CoAP protocols. + SuperMQ provides a robust middleware solution, supporting HTTP, MQTT, WebSocket, and CoAP protocols for seamless communication. ), }, { - title: "Device Management", + title: "Client Management", Svg: require("@site/static/img/device_management.svg").default, description: ( <> - Manage your IoT devices and secure communications using fine-grained access control and token-based authentication. + Manage your clients, groups and secure communications using fine-grained access control and token-based authentication. ), }, @@ -44,7 +44,7 @@ const FeatureList: FeatureItem[] = [ description: ( <> - SuperMQ is fully open-source and patent-free, enabling community-driven innovation for IoT applications. + SuperMQ is fully open-source and patent-free, fostering community-driven innovation and collaboration. ), },