├── .gitignore ├── .travis.yml ├── Dockerfile ├── Makefile ├── README.md ├── deploy.sh ├── deploy_key.enc ├── docs ├── api │ ├── http.md │ ├── mqtt.md │ └── python.md ├── client-libraries.md ├── faq.md ├── howto │ ├── chip.md │ ├── o2.md │ └── rpi.md ├── index.md ├── plans-and-pricing.md ├── res │ ├── ds18b20.png │ ├── extra.css │ ├── managePackets │ │ ├── account-settings.png │ │ ├── buy.png │ │ ├── packets-info.png │ │ └── spending-cap.png │ └── troubleshooting-unbound-variable.png ├── start │ ├── chip.md │ ├── esp-ino.md │ ├── esp-pio.md │ ├── esp8266-upy.md │ ├── o2.md │ └── rpi.md └── troubleshooting.md ├── example-img ├── omega_led.png ├── omega_rgb.png └── panel.png ├── mkdocs.yml └── serve.sh.bat /.gitignore: -------------------------------------------------------------------------------- 1 | .idea/ 2 | .vscode/ 3 | 4 | site/ 5 | 6 | .DS_Store -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: python 2 | 3 | python: '3.6' 4 | 5 | install: make init 6 | 7 | script: make build_deploy 8 | 9 | env: 10 | global: 11 | - ENCRYPTION_LABEL: 2dbed6352b90 12 | - COMMIT_AUTHOR_EMAIL: "cloud4rpi@gmail.com" 13 | 14 | 15 | notifications: 16 | slack: 17 | on_success: change 18 | on_failure: always 19 | rooms: 20 | secure: OuoX9d5Cztvl7vimVrtAh/N0PQ0+x+y8s84cY6E0vei6ArIBlrcNJe1tftQW6a88RXi0VKbpFC8toTMCuz9FJHWlAy9YdaonsLF/06tXng9U3Ihj35VZ30MHTNpSsdbRx6DzzPYFHOjIzqCbFyYQZqKT6hEsk/v0fOCrM4tmtkIvuZcsmMDBg8WZCx53LDkUHx48RSHpqI699m0C1NMoaYTe+v9bmWkShVd8rFGiD20VH8aCVwddEaosqsm4wfCK38s+3jkYwF2ptoLLzrHSE5nQZIVRo5sg4euZCch9+I8+LG1Wzol2k6haWM4lhf+ia0Re4+rxee+FehqKCj4E4TexvaKSEG8pfSNJwJuP6krBesfZ3rmMSK1uTMQZdHwX8hIalzQjCnmxO1dR1Iu2WAtZ0wl7JOWkWh5vaxixwdK79jt/AZXCbZ9HvaGMlpDlisW0yn1Ob0YfqX1xZ6FZhC76qtFgzIJLgCd4ctTFCoo+Ks8EP1A9bKl6DkjmCM/19v+d2UGs6iax7KOzL4BAZxGfYDAIZdi3XAQDgf5+KUZV/82EqifYI2OH8LXHi4eiFB3RKgEVG33rzPg8rBZLAoJNlScvE78/urRDaBywZxiABj3VOQQ9VqBiaRrJt63ioTVRywJMhByKC/gLWG75xRIEGeXvMo0bEAkQWyrG3rA= 21 | -------------------------------------------------------------------------------- /Dockerfile: -------------------------------------------------------------------------------- 1 | FROM python:3.6-stretch 2 | 3 | RUN pip3 install mkdocs mkdocs-material 4 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | .PHONY: build clean publish build_deploy build_image build_in_docker serve_in_docker 2 | 3 | init: 4 | pip install mkdocs mkdocs-material 5 | 6 | build: 7 | mkdocs build --clean 8 | 9 | clean: 10 | rm -rf site/* 11 | 12 | publish: 13 | mkdocs gh-deploy --clean 14 | 15 | build_deploy: 16 | bash deploy.sh 17 | 18 | build_image: 19 | docker build --rm --tag docs-build-env . 20 | 21 | build_in_docker: build_image 22 | docker run --rm --volume $(shell pwd):/docs -w /docs docs-build-env make build 23 | 24 | serve_in_docker: build_in_docker 25 | docker run --rm --volume $(shell pwd):/docs -w /docs -p 8000:8000 docs-build-env mkdocs serve -a 0.0.0.0:8000 26 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | Cloud4RPi Documentation 2 | ======= 3 | 4 | This repository contains documentation for [Cloud4RPi](https://cloud4rpi.io/) service. 5 | 6 | [![Build Status](https://travis-ci.org/cloud4rpi/docs.svg?branch=master)](https://travis-ci.org/cloud4rpi/docs) 7 | 8 | You can read it on [Cloud4RPi Documentation](http://docs.cloud4rpi.io) website. 9 | 10 | The documentation is created with [MkDocs](http://www.mkdocs.org/). Follow the steps below to open it locally. 11 | 12 | - Use the `pip install mkdocs mkdocs-material` command to install [MkDocs](http://www.mkdocs.org/#installation) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/). 13 | - Run the [serve.sh.bat](serve.sh.bat) file. 14 | 15 | While **MkDocs** is running, use the [http://127.0.0.1:8000](http://127.0.0.1:8000) URL to access the documentation. 16 | 17 | 18 | ## See Also 19 | 20 | * [Client Library](https://github.com/cloud4rpi/cloud4rpi) 21 | * [Usage Examples for Raspberry Pi](https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python) 22 | -------------------------------------------------------------------------------- /deploy.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | set -e # Exit with nonzero exit code if anything fails 3 | 4 | SOURCE_BRANCH="master" 5 | TARGET_BRANCH="gh-pages" 6 | OUTPUT="site" 7 | 8 | # Pull requests and commits to other branches shouldn't try to deploy, just build to verify 9 | if [ "$TRAVIS_PULL_REQUEST" != "false" -o "$TRAVIS_BRANCH" != "$SOURCE_BRANCH" ]; then 10 | echo "Skipping deploy; just doing a build." 11 | make build 12 | exit 0 13 | fi 14 | 15 | # Save some useful information 16 | REPO=`git config remote.origin.url` 17 | SSH_REPO=${REPO/https:\/\/github.com\//git@github.com:} 18 | SHA=`git rev-parse --verify HEAD` 19 | 20 | # Clone the existing gh-pages for this repo into out/ 21 | # Create a new empty branch if gh-pages doesn't exist yet (should only happen on first deply) 22 | git clone $REPO $OUTPUT 23 | cd $OUTPUT 24 | git checkout $TARGET_BRANCH || git checkout --orphan $TARGET_BRANCH 25 | cd .. 26 | 27 | # Clean out existing contents 28 | rm -rf $OUTPUT/**/* || exit 0 29 | 30 | # Run our compile script 31 | make build 32 | 33 | 34 | # Now let's go have some fun with the cloned repo 35 | cd $OUTPUT 36 | git config user.name "Travis CI" 37 | git config user.email "cloud4rpi@gmail.com" 38 | 39 | # Configuring GitHub Pages Custom Domain 40 | echo -n "docs.cloud4rpi.io" > CNAME 41 | 42 | # If there are no changes (e.g. this is a README update) then just bail. 43 | echo "Looking for changes:" 44 | git diff -G"^([^B]|B[^u]|Bu[^i]|Bui[^l]|Buil[^d]|Build[^ ]|Build [^D]|Build D[^a]|Build Da[^t]|Build Dat[^e]|Build Date[^ ]|Build Date [^U])" 45 | if [[ -z `git diff -G"^([^B]|B[^u]|Bu[^i]|Bui[^l]|Buil[^d]|Build[^ ]|Build [^D]|Build D[^a]|Build Da[^t]|Build Dat[^e]|Build Date[^ ]|Build Date [^U])" --exit-code` ]]; then 46 | echo "No changes to the spec on this push; exiting." 47 | exit 0 48 | fi 49 | 50 | # Commit the the new version. 51 | git add -A . 52 | git commit -m "Deploy to GitHub Pages: ${SHA}" 53 | 54 | # Get the deploy key by using Travis's stored variables to decrypt deploy_key.enc 55 | ENCRYPTED_KEY_VAR="encrypted_${ENCRYPTION_LABEL}_key" 56 | ENCRYPTED_IV_VAR="encrypted_${ENCRYPTION_LABEL}_iv" 57 | ENCRYPTED_KEY=${!ENCRYPTED_KEY_VAR} 58 | ENCRYPTED_IV=${!ENCRYPTED_IV_VAR} 59 | 60 | cd .. 61 | openssl aes-256-cbc -K $ENCRYPTED_KEY -iv $ENCRYPTED_IV -in deploy_key.enc -out deploy_key -d 62 | chmod 600 deploy_key 63 | eval `ssh-agent -s` 64 | ssh-add deploy_key 65 | 66 | cd $OUTPUT 67 | 68 | # Now that we're all set up, we can push. 69 | git push $SSH_REPO $TARGET_BRANCH 70 | 71 | # Killing ssh-agent to let the session finish 72 | ssh-agent -k 73 | -------------------------------------------------------------------------------- /deploy_key.enc: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/deploy_key.enc -------------------------------------------------------------------------------- /docs/api/http.md: -------------------------------------------------------------------------------- 1 | HTTP Protocol API 2 | ================= 3 | 4 | ## Variables Configuration 5 | 6 | Updates the device's configuration. 7 | 8 | ### Request Destination 9 | 10 | * **Method**: POST 11 | * **URL**: `https://cloud4rpi.io/api/devices/{token}/config` 12 | 13 | #### URL Parameters 14 | 15 | Name | Description 16 | --------- | ----------------------- 17 | token | The [device](https://cloud4rpi.io/devices) token 18 | 19 | #### Headers 20 | 21 | ``` 22 | Content-Type: application/json 23 | ``` 24 | 25 | ### Request Body 26 | 27 | ```javascript 28 | [ 29 | {"name": name, "type": type}, 30 | {"name": name, "type": type}, 31 | // ... 32 | {"name": name, "type": type} 33 | ] 34 | ``` 35 | 36 | #### Parameters 37 | 38 | Name | Description | Type | Possible Values 39 | ----- | ------------- | ------ | ----------------------------- 40 | name | Variable name | string | Any string 41 | type | Variable type | string | "bool", "numeric", "string", or "location" 42 | 43 | 44 | ### Example 45 | 46 | The following example creates two variables on the device: 47 | 48 | * **Temperature** (numeric) 49 | * **LEDOn** (boolean) 50 | 51 | 52 | ```sh 53 | export DEVICE_TOKEN=your_device_token 54 | 55 | curl -X POST \ 56 | -H "Content-Type: application/json" \ 57 | -d '[{"name":"Temperature","type":"numeric"},{"name":"LEDOn","type":"bool"}]' \ 58 | "https://cloud4rpi.io/api/devices/$DEVICE_TOKEN/config" 59 | ``` 60 | 61 | !!! Note 62 | 63 | Replace **your_device_token** with your device token displayed on the [device page](https://cloud4rpi.io/devices). 64 | 65 | ### Response Body 66 | 67 | ```javascript 68 | { "message": "OK" } 69 | ``` 70 | or 71 | ```javascript 72 | { "error": error_text } 73 | ``` 74 | 75 | ## Variable Values 76 | 77 | Sends variable values. 78 | 79 | !!! Note 80 | 81 | Before sending variable values, configure variables by sending the [Variables Configuration message](#variables-configuration). 82 | 83 | ### Request Destination 84 | 85 | * **Method**: POST 86 | * **URL**: `https://cloud4rpi.io/api/devices/{token}/data` 87 | 88 | #### URL Parameters 89 | 90 | Name | Description 91 | --------- | ----------------------- 92 | token | The [device](https://cloud4rpi.io/devices) token 93 | 94 | #### Headers 95 | 96 | ``` 97 | Content-Type: application/json 98 | ``` 99 | 100 | ### Request Body 101 | 102 | ```javascript 103 | { 104 | "ts": datetime_isoformat, 105 | "payload": { 106 | var_name: var_value, 107 | var_name: var_value, 108 | // ... 109 | var_name: var_value 110 | } 111 | } 112 | ``` 113 | 114 | #### Parameters 115 | 116 | Name | Description | Type | Possible Values 117 | ------------------ | ------------------- | ------------- | ---------------------------- 118 | datetime_isoformat | Timestamp (optional) | string | Time in the **ISO 8601** format with the [time zone designator](https://en.wikipedia.org/wiki/ISO_8601#Time_zone_designators) specified explicitly 119 | var_name | Variable name | string | One of the variables 120 | var_value | Variable value | corresponding | Any 121 | 122 | !!! Note 123 | 124 | Use the following object to send the `location` variable values: `{"lat": latitude_value, "lng": longitude_value}`, where `latitude_value` and `longitude_value` are floating point numbers. 125 | 126 | ### Example 127 | 128 | The following example sends the values of two variables: 129 | 130 | * **Temperature**: *24*. 131 | * **LEDOn**: *true*. 132 | 133 | ```bash 134 | export DEVICE_TOKEN=your_device_token 135 | 136 | curl -X POST \ 137 | -H "Content-Type: application/json" \ 138 | -d '{"ts":"$(date -Is)","payload":{"Temperature":24,"LEDOn":true}}' \ 139 | "https://cloud4rpi.io/api/devices/$DEVICE_TOKEN/data" 140 | ``` 141 | 142 | !!! Note 143 | 144 | Replace **your_device_token** with your device token displayed on the [device page](https://cloud4rpi.io/devices). 145 | 146 | ### Response Body 147 | 148 | ```javascript 149 | { "message": "OK" } 150 | ``` 151 | or 152 | ```javascript 153 | { "error": error_text } 154 | ``` 155 | 156 | 157 | ## Diagnostic Data 158 | 159 | Sends device's diagnostic data. 160 | 161 | ### Request Destination 162 | 163 | * **Method**: POST 164 | * **URL**: `https://cloud4rpi.io/api/devices/{token}/diagnostics` 165 | 166 | #### URL Parameters 167 | 168 | Name | Description 169 | --------- | ----------------------- 170 | token | The [device](https://cloud4rpi.io/devices) token 171 | 172 | #### Headers 173 | 174 | ``` 175 | Content-Type: application/json 176 | ``` 177 | 178 | ### Request Body 179 | 180 | ```javascript 181 | { 182 | "ts": datetime_isoformat, 183 | "payload": { 184 | var_name: var_value, 185 | var_name: var_value, 186 | // ... 187 | var_name: var_value 188 | } 189 | } 190 | ``` 191 | 192 | #### Parameters 193 | 194 | Name | Description | Type | Possible Values 195 | ------------------ | -------------------- | ------ | ---------------------------- 196 | datetime_isoformat | Timestamp (optional) | string | Time in the **ISO 8601** format with the [time zone designator](https://en.wikipedia.org/wiki/ISO_8601#Time_zone_designators) specified explicitly 197 | var_name | Variable name | string | Any 198 | var_value | Variable value | any | Any 199 | 200 | 201 | ### Example 202 | 203 | The following example sends the following diagnostic values to Cloud4RPi: 204 | 205 | * **CPU Temperature**: *41* 206 | * **IP Address**: *192.168.1.50* 207 | 208 | ```sh 209 | export DEVICE_TOKEN=your_device_token 210 | 211 | curl -X POST \ 212 | -H "Content-Type: application/json" \ 213 | -d '{"ts":"$(date -Is)","payload":{"CPU Temperature":41,"IP Address":"192.168.1.50"}}' \ 214 | "https://cloud4rpi.io/api/devices/$DEVICE_TOKEN/diagnostics" 215 | ``` 216 | 217 | !!! Note 218 | 219 | Replace **your_device_token** with your device token displayed on the [device page](https://cloud4rpi.io/devices). 220 | 221 | ### Response Body 222 | 223 | ```javascript 224 | { "message": "OK" } 225 | ``` 226 | or 227 | ```javascript 228 | { "error": error_text } 229 | ``` 230 | 231 | 232 | ## Commands Queue 233 | 234 | Acquires the recent commands sent from the Control Panel. 235 | 236 | ### Request Destination 237 | 238 | * **Method**: GET 239 | * **URL**: `https://cloud4rpi.io/api/devices/{token}/commands/latest` 240 | 241 | #### URL Parameters 242 | 243 | Name | Description 244 | --------- | ----------------------- 245 | token | The [device](https://cloud4rpi.io/devices) token 246 | 247 | 248 | 249 | ### Example 250 | 251 | ```sh 252 | export DEVICE_TOKEN=your_device_token 253 | 254 | curl -X GET "https://cloud4rpi.io/api/devices/$DEVICE_TOKEN/commands/latest" 255 | ``` 256 | 257 | ### Response Body 258 | 259 | ```javascript 260 | [ 261 | {var_name: var_new_value}, 262 | {var_name: var_new_value}, 263 | // ... 264 | {var_name: var_new_value} 265 | ] 266 | ``` 267 | 268 | #### Parameters 269 | 270 | Name | Description | Type | Possible Values 271 | ------------------ | ------------------ | ---------------- | ---------------- 272 | var_name | Variable name | string | Any 273 | var_new_value | New variable value | corresponding | Any 274 | 275 | 276 | The commands are in chronological order. 277 | -------------------------------------------------------------------------------- /docs/api/mqtt.md: -------------------------------------------------------------------------------- 1 | MQTT Protocol API 2 | ================= 3 | 4 | 5 | ## Prerequisites 6 | 7 | The examples in this section are presented for the [Eclipse Mosquitto™](https://mosquitto.org/) MQTT client. Install the client if you are going to run the examples. On Debian-based operating systems you can install it using the following command: 8 | 9 | ```sh 10 | sudo apt-get install mosquitto-clients 11 | ``` 12 | 13 | ## Cloud4RPi MQTT Broker 14 | 15 | Use the following data to connect to the MQTT broker: 16 | 17 | * **Host:** 18 | * With SSL encryption: `mqtts://mq.cloud4rpi.io` 19 | * Without SSL encryption: `mqtt://mq.cloud4rpi.io` 20 | * **Port:** 21 | * With SSL encryption: `8883` 22 | * Without SSL encryption: `1883` 23 | * **Client ID**: Your [Device](https://cloud4rpi.io/devices/) Token 24 | 25 | 26 | !!! Warning 27 | Since the **Client ID** is used for authentication, you should not open more than one connection with a single **Device Token** at the same time. 28 | 29 | !!! Note 30 | **Login** and **Password** are not used, you can leave them empty. 31 | 32 | 33 | ## Variables Configuration 34 | 35 | Update the device's configuration by sending messages to the following topic: 36 | 37 | ```gradle 38 | devices/{token}/config 39 | ``` 40 | 41 | #### Topic Parameters 42 | 43 | Name | Description 44 | --------- | ----------------------- 45 | token | The [device](https://cloud4rpi.io/devices) token 46 | 47 | ### Message Structure 48 | 49 | ```javascript 50 | { 51 | "payload": [ 52 | {"name": name, "type": type}, 53 | {"name": name, "type": type}, 54 | // ... 55 | {"name": name, "type": type} 56 | ] 57 | } 58 | ``` 59 | 60 | #### Parameters 61 | 62 | Name | Description | Type | Possible Values 63 | ------------------ | ------------- | ------ | ---------------------------- 64 | name | Variable name | string | Any string 65 | type | Variable type | string | "bool", "numeric", "string", or "location" 66 | 67 | 68 | !!! Note 69 | 70 | Use the following object to send the `location` variable values: `{"lat": latitude_value, "lng": longitude_value}`, where `latitude_value` and `longitude_value` are floating point numbers. 71 | 72 | 73 | ### Example 74 | 75 | The following example creates two variables on the device: 76 | 77 | * **Temperature** (numeric) 78 | * **LEDOn** (boolean) 79 | 80 | 81 | ```sh 82 | export DEVICE_TOKEN=your_device_token 83 | mosquitto_pub -q 1 -d -t "devices/$DEVICE_TOKEN/config" -h mq.cloud4rpi.io -i "$DEVICE_TOKEN" \ 84 | -m '{"payload":[{"name":"Temperature","type":"numeric"},{"name":"LEDOn","type":"bool"}]}' 85 | ``` 86 | 87 | 88 | !!! Note 89 | Replace **your_device_token** with your device token displayed on the [device page](https://cloud4rpi.io/devices). 90 | 91 | ## Variable Values 92 | 93 | !!! Note 94 | Before sending variable values, configure variables by sending the [Variables Configuration message](#variables-configuration). 95 | 96 | Send messages with your variable values to the following topic: 97 | 98 | ```gradle 99 | devices/{token}/data 100 | ``` 101 | 102 | #### Topic Parameters 103 | 104 | Name | Description 105 | --------- | ----------------------- 106 | token | The [device](https://cloud4rpi.io/devices) token 107 | 108 | 109 | 110 | ### Message Structure 111 | 112 | ```javascript 113 | { 114 | "ts": datetime_isoformat, 115 | "payload": { 116 | var_name: var_value, 117 | var_name: var_value, 118 | // ... 119 | var_name: var_value 120 | } 121 | } 122 | ``` 123 | 124 | #### Parameters 125 | 126 | Name | Description | Type | Possible Values 127 | ------------------ | -------------------- | ------------- | ---------------------------- 128 | datetime_isoformat | Timestamp (optional) | string | Time in the **ISO 8601** format with the [time zone designator](https://en.wikipedia.org/wiki/ISO_8601#Time_zone_designators) specified explicitly 129 | var_name | Variable name | string | One of the variables 130 | var_value | Variable value | corresponding | Any 131 | 132 | 133 | ### Example 134 | 135 | The following example sends the values of two variables: 136 | 137 | * **Temperature**: *24* 138 | * **LEDOn**: *true* 139 | 140 | ```sh 141 | export DEVICE_TOKEN=your_device_token 142 | mosquitto_pub -q 1 -d -t "devices/$DEVICE_TOKEN/data" -h mq.cloud4rpi.io -i "$DEVICE_TOKEN" \ 143 | -m '{"payload":{"Temperature":24,"LEDOn":true}}' 144 | ``` 145 | 146 | !!! Note 147 | Replace **your_device_token** with your device token displayed on the [device page](https://cloud4rpi.io/devices). 148 | 149 | 150 | ## Diagnostic Data 151 | 152 | Send messages with your device's diagnostic data to the following topic: 153 | 154 | ```gradle 155 | devices/{token}/diagnostics 156 | ``` 157 | 158 | #### Topic Parameters 159 | 160 | Name | Description 161 | --------- | ----------------------- 162 | token | The [device](https://cloud4rpi.io/devices) token 163 | 164 | 165 | ### Message Structure 166 | 167 | ```javascript 168 | { 169 | "ts": datetime_isoformat, 170 | "payload": { 171 | var_name: var_value, 172 | var_name: var_value, 173 | // ... 174 | var_name: var_value 175 | } 176 | } 177 | ``` 178 | 179 | #### Parameters 180 | 181 | Name | Description | Type | Possible Values 182 | ------------------ | -------------------- | ------ | ---------------------------- 183 | datetime_isoformat | Timestamp (optional) | string | Time in the **ISO 8601** format with the [time zone designator](https://en.wikipedia.org/wiki/ISO_8601#Time_zone_designators) specified explicitly 184 | var_name | Variable name | string | Any 185 | var_value | Variable value | any | Any 186 | 187 | 188 | ### Example 189 | 190 | The following example sends the following diagnostic values to Cloud4RPI: 191 | 192 | * **CPU Temperature**: *41* 193 | * **IP Address**: *192.168.1.50* 194 | 195 | ```sh 196 | export DEVICE_TOKEN=your_device_token 197 | mosquitto_pub -q 1 -d -t "devices/$DEVICE_TOKEN/diagnostics" -h mq.cloud4rpi.io -i "$DEVICE_TOKEN" \ 198 | -m '{"payload":{"CPU Temperature":41,"IP Address":"192.168.1.50"}}' 199 | ``` 200 | 201 | !!! Note 202 | Replace **your_device_token** with your device token displayed on the [device page](https://cloud4rpi.io/devices). 203 | 204 | ## Commands Stream 205 | 206 | Receive commands sent from the [Control Panels](https://cloud4rpi.io/control-panels) in real time by subscribing to the following topic: 207 | 208 | ```gradle 209 | devices/{token}/commands 210 | ``` 211 | 212 | #### Topic Parameters 213 | 214 | Name | Description 215 | --------- | ----------------------- 216 | token | The [device](https://cloud4rpi.io/devices) token 217 | 218 | 219 | ### Example 220 | 221 | Execute the following command to subscribe: 222 | 223 | ```sh 224 | export DEVICE_TOKEN=your_device_token 225 | mosquitto_sub -d -t "devices/$DEVICE_TOKEN/commands" -h mq.cloud4rpi.io -i "$DEVICE_TOKEN" 226 | ``` 227 | 228 | This program works in the foreground and blocks the input while the connection to the broker persists. So, you instantly get commands sent from the UI in the following format: 229 | 230 | 231 | ### Message Structure 232 | 233 | ```javascript 234 | {var_name:var_new_value} 235 | ``` 236 | 237 | #### Parameters 238 | 239 | Name | Description | Type | Possible Values 240 | ------------------ | ------------------ | ---------------- | ---------------- 241 | var_name | Variable name | string | Any 242 | var_new_value | New variable value | corresponding | Any 243 | -------------------------------------------------------------------------------- /docs/api/python.md: -------------------------------------------------------------------------------- 1 | Python Library API 2 | ================== 3 | 4 | ## Library Root 5 | 6 | The [Cloud4RPi Python library](https://github.com/cloud4rpi/cloud4rpi) provides the following public methods (defined in the [\_\_init\_\_.py](https://github.com/cloud4rpi/cloud4rpi/blob/master/cloud4rpi/__init__.py) file): 7 | 8 | 9 | ### connect 10 | 11 | `connect(device_token, host=mqqtBrokerHost, port=None, tls_config=None)` – connects to the Cloud and returns a [Device](#device) object. 12 | 13 | **Parameters:** 14 | 15 | * `device_token` – a token displayed at the top of the device page on [cloud4rpi.io](https://cloud4rpi.io/devices). You can use the **New Device** button in the top right corner of the [Devices](https://cloud4rpi.io/devices) page to create a new device and use its token. 16 | * `host` *(optional)* – a Cloud4RPi MQTT broker address. The default address is defined in the [config.py](https://github.com/cloud4rpi/cloud4rpi/blob/master/cloud4rpi/config.py) file. 17 | * `port` *(optional)* – a Cloud4RPi MQTT broker port. The default port is defined in the [config.py](https://github.com/cloud4rpi/cloud4rpi/blob/master/cloud4rpi/config.py) file. 18 | * `tls_config` *(optional)* – a dictionary with parameters for the Paho MQTT's [tls_set()](https://github.com/eclipse/paho.mqtt.python#tls_set) function. 19 | 20 | **Example:** 21 | 22 | import cloud4rpi 23 | device = cloud4rpi.connect('823SnkK3N8L5Y7QQGiuGd53fi', tls_config={'ca_certs': '/etc/ssl/certs/ca-certificates.crt'}) 24 | 25 | 26 | ### set_logging_to_file 27 | 28 | `set_logging_to_file(log_file_path)` – configures the library to save activity logs to a specified file. 29 | 30 | **Parameters:** 31 | 32 | `log_file_path` – path to a log file. 33 | 34 | 35 | ### set_logging_level 36 | 37 | `set_logging_level(level=logging.INFO)` – changes the logging verbosity level. 38 | 39 | **Parameters:** 40 | 41 | * `level` *(optional)* – [logging verbosity level](https://docs.python.org/3/library/logging.html#levels). The default level is `INFO`. 42 | 43 | 44 | 45 | 46 | ## Device 47 | 48 | The [Device](https://github.com/cloud4rpi/cloud4rpi/blob/master/cloud4rpi/device.py) class provides the following methods to communicate with the Cloud4RPi server and manage the variables' state: 49 | 50 | 51 | ### declare 52 | 53 | `declare(variables)` – configures the variables attached to the device. 54 | 55 | **Parameters:** 56 | 57 | * `variables` – a dictionary with the variables description of the following structure: 58 | 59 | `{ name: { 'type': type, 'bind': binding, 'value': value }, ... }`, where: 60 | 61 | * `name` – an internal variable name. Name cannot contain dots (**.**) or dollar signs (**$**). You can change the name displayed in the UI on the device page. 62 | * `type` – a variable type. Available types: `'bool'`, `'numeric'`, `'string'` and `'location'`. 63 | * `binding` – a function that accepts the current variable as a parameter and returns a new variable. This function is called every time a value is updated (scheduled updates and value change signals from Control Panels). You can also pass a Python variable if the value should not be changed from Cloud4RPi Control Panels. 64 | * `value` *(optional)* – an initial variable value passed to a `binding` function during the first update. 65 | 66 | 67 | !!! Note 68 | 69 | Use the following object to send the `location` variable values: `{"lat": latitude_value, "lng": longitude_value}`, where `latitude_value` and `longitude_value` are floating point numbers. 70 | 71 | **Example:** 72 | 73 | def led_control(value): 74 | GPIO.output(LED_PIN, value) 75 | return GPIO.input(LED_PIN) 76 | 77 | ds_sensors = DS18b20.find_all() 78 | 79 | device.declare({ 80 | 'Room Temp': { 81 | 'type': 'numeric', 82 | 'bind': ds_sensors[0] if ds_sensors else None 83 | }, 84 | 'LED On': { 85 | 'type': 'bool', 86 | 'value': False, 87 | 'bind': led_control 88 | } 89 | }) 90 | 91 | 92 | ### declare_diag 93 | 94 | `declare_diag(diag)` – configures the diagnostic variables attached to the device. 95 | 96 | **Parameters:** 97 | 98 | * `diag` – a dictionary with the diagnostic variables' description. It has the following structure: 99 | 100 | `{ name: binding, ... }`, where: 101 | 102 | * `name` – a diagnostic variable's name. 103 | * `binding` – a Python variable or function that holds or returns the actual Cloud4RPi diagnostic variable's value. 104 | 105 | **Example:** 106 | 107 | device.declare_diag({ 108 | 'Host': gethostname(), 109 | 'Operating System': " ".join(uname()) 110 | }) 111 | 112 | 113 | ### read_config 114 | 115 | `read_config()` – prepares the previously declared (with the `declare(variables)` function) variables' configuration for publishing (with the `publish_config(cfg=None)` function). 116 | 117 | **Returns:** A dictionary in the format suitable for the `publish_config(cfg=None)` function. 118 | 119 | 120 | ### read_data 121 | 122 | `read_data()` – updates all variable values and prepares the variables' state for publishing (with the `publish_data(data=None)` function). This method calls all the `binding` functions and saves the returned values as new variable values. 123 | 124 | **Returns:** A dictionary in the format suitable for the `publish_data(data=None)` function. 125 | 126 | 127 | ### read_diag 128 | 129 | `read_diag()` – reads all the diagnostic variable values and prepares the data for publishing (with the `publish_diag(diag=None)` function). 130 | 131 | **Returns:** A dictionary in the format suitable for the `publish_diag(diag=None)` function. 132 | 133 | 134 | ### publish_config 135 | 136 | `publish_config(cfg=None)` – publishes the variables' configuration to the Cloud4RPi server. 137 | 138 | **Parameters:** 139 | 140 | * `cfg` *(optional)* – the `read_config()` output. If not passed, `read_config()` is invoked internally. This is a list with the following structure: 141 | 142 | `[{'name': name, 'type': type}, ...]`, where `name` and `type` corresponds to the same values in the `variables` parameter passed to the `declare(variables)` function. 143 | 144 | 145 | ### publish_data 146 | 147 | `publish_data(data=None)` – publishes variable values to the Cloud4RPi server. 148 | 149 | **Parameters:** 150 | 151 | * `data` *(optional)* – the `read_data()` output. If not passed, `read_data()` is invoked internally. This is a dictionary with the following structure: 152 | 153 | `{name: value, ...}`, where `name` corresponds to the variable name in the `variables` parameter passed to the `declare(variables)` function, and `value` is the variable value returned by `binding`. 154 | 155 | 156 | ### publish_diag 157 | 158 | `publish_diag(diag=None)` – publishes diagnostic variable values to the Cloud4RPi server. 159 | 160 | **Parameters:** 161 | 162 | * `diag` *(optional)* – the `read_diag()` output. If not passed, `read_diag()` is invoked internally. This is a dictionary with the following structure: 163 | 164 | `{name: value, ...}`, where `name` corresponds to the variable's name in the `diag` parameter passed to the `declare_diag(diag)` function, and `value` is the variable's value the `binding` returns. 165 | -------------------------------------------------------------------------------- /docs/client-libraries.md: -------------------------------------------------------------------------------- 1 | The table below lists download links for the latest versions of the Cloud4RPi client libraries. 2 | 3 | | Platform | Version | Download Links | 4 | | -------- | ------- | -------------- | 5 | | Python | 1.1.1 | [Github](https://github.com/cloud4rpi/cloud4rpi)
[PyPi](https://pypi.org/project/cloud4rpi) | 6 | | Arduino | 1.1.0 | [Github](https://github.com/cloud4rpi/cloud4rpi-esp-arduino)
[Arduino Library List](https://www.arduinolibraries.info/libraries/cloud4rpi-esp-arduino)
[PlatformIO](https://platformio.org/lib/show/2045/cloud4rpi-esp-arduino) | -------------------------------------------------------------------------------- /docs/faq.md: -------------------------------------------------------------------------------- 1 | Frequently asked questions and possible issues you can encounter with [Cloud4RPi](https://cloud4rpi.io): 2 | 3 | 4 | ## How to update Cloud4RPi client installation? 5 | 6 | The Cloud4RPi client library is a [PyPI package](https://pypi.python.org/pypi/cloud4rpi) the [pip utility](https://pip.pypa.io/en/stable/) manages. Execute the following command to update the Cloud4RPi client library: 7 | 8 | ```sh 9 | sudo pip install --upgrade cloud4rpi 10 | ``` 11 | 12 | 13 | ## What are packets? 14 | 15 | Packet is a data portion sent from a device to the Cloud4RPi server (using the [MQTT](/api/mqtt/#cloud4rpi-mqtt-broker) or [HTTPs](/api/http/) protocol). A single packet can include multiple variable values. [Diagnostic data](/api/mqtt/#diagnostic-data) transfer is unlimited and does not consume packets. 16 | 17 | Packet information is displayed at the top right corner of Cloud4RPi pages and in the **Pricing Plan** category of your [account settings](https://cloud4rpi.io/account). 18 | 19 | ![](/res/managePackets/packets-info.png) 20 | 21 | Learn more about the subscription plans in the [Plans and Pricing](/plans-and-pricing) section. 22 | 23 | 24 | 25 | 26 | 27 | ## Where are the log files? 28 | 29 | Use one of the following commands to read the logs containing the service's output and errors: 30 | 31 | * `less /var/log/cloud4rpi.log` — if your init manager is `init` and you have left the [service name](https://gist.github.com/c4r-gists/3bdeff914dd57a26928973656685a503#file-service_install-sh-L4) and [log path](https://gist.github.com/c4r-gists/3bdeff914dd57a26928973656685a503#file-service_install-sh-L55) unchanged; 32 | * `sudo journalctl -u cloud4rpi` — if your init manager is `systemd` and you have not changed the [service name](https://gist.github.com/c4r-gists/3bdeff914dd57a26928973656685a503#file-service_install-sh-L4). 33 | 34 | 35 | !!! Note 36 | Use the `ps -p 1` command to see your operating system's init manager. Refer to your init manager's documentation for more information or [contact us](https://cloud4rpi.answerdesk.io/) if it differs from `init` and `systemd`. 37 | 38 | You can also call the following function at the beginning of your script to save the script output. It is useful if you do not run your Cloud4RPi-enabled script as a service: 39 | 40 | ```python 41 | cloud4rpi.set_logging_to_file(YOUR_LOGFILE_PATH) 42 | ``` 43 | 44 | 45 | ## How to use the service installed using the service_install.sh script? 46 | 47 | The default service's name is **cloud4rpi** (can be changed in [service_install.sh:4](https://gist.github.com/c4r-gists/3bdeff914dd57a26928973656685a503#file-service_install-sh-L4)). You can use the following commands if your init manager is `init`: 48 | 49 | ```sh 50 | sudo service cloud4rpi start|stop|status|restart|uninstall 51 | ``` 52 | 53 | If your init manager is `systemd`, you can use the same commands except for `uninstall`. To remove the `systemd` service, execute the following commands: 54 | 55 | ```sh 56 | sudo systemctl stop cloud4rpi.service 57 | sudo systemctl disable cloud4rpi.service 58 | sudo rm /lib/systemd/system/cloud4rpi.service 59 | sudo systemctl daemon-reload 60 | ``` 61 | 62 | 63 | ## How to choose the DATA_SENDING_INTERVAL value? 64 | 65 | Call [device.publish_data()](/api/python/#publish_data) and [device.publish_diag()](/api/python/#publish_diag) functions frequently to update the monitored variables. The update frequency depends on the variable dynamics, for example, atmospheric conditions do not change every minute. This means the delay between updates for a weather station should be one to ten minutes. You should also consider available [packets](#what-are-packets) when choosing the `DATA_SENDING_INTERVAL` value. 66 | 67 | If you monitor several variables with different dynamics, the delay between updates should be the shortest. 68 | 69 | !!! Note 70 | The variable update interval does not affect commands, and variable changes made through the Web UI (**Switch** or **Slider** widget) are applied instantly. 71 | 72 | 73 | -------------------------------------------------------------------------------- /docs/howto/chip.md: -------------------------------------------------------------------------------- 1 | # Control LED from WEB using C.H.I.P. 2 | 3 | ## Prerequisites 4 | 5 | - Configured and [connected](/#connecting-a-new-device) device. 6 | - Breadboard, connecting wires, 330Ω..1kΩ resistor. 7 | 8 | ## Code 9 | 10 | - Open the [control.py](https://github.com/cloud4rpi/cloud4rpi-chip-python/blob/master/control.py) sample file. 11 | - Replace `__YOUR_DEVICE_TOKEN__` with the device token from the [Device](https://cloud4rpi.io/devices) page. 12 | - Connect an LED to a GPIO pin and set the correct value to the `LED_PIN` variable. The default pin is **XIO-P0**. 13 | - Run `sudo python control.py`. A new `LED On` variable should appear on the [Device](https://cloud4rpi.io/devices) page. 14 | - Open the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel. 15 | - Add a new **Switch** widget and choose the newly added `LED On` variable. 16 | 17 | You can now switch the LED state using this widget. 18 | 19 | # Monitor Device Events using Colored Status 20 | 21 | ## Prerequisites 22 | 23 | - Configured and [connected](/#connecting-a-new-device) device. 24 | 25 | ## Code 26 | 27 | - Open the [control.py](https://github.com/cloud4rpi/cloud4rpi-chip-python/blob/master/control.py) sample file. 28 | - Replace `__YOUR_DEVICE_TOKEN__` with the device token from the [Device](https://cloud4rpi.io/devices) page. 29 | - Run `sudo python control.py`. A new `STATUS` variable should appear on the [Device](https://cloud4rpi.io/devices) page. 30 | - Open the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel or open an existing one. 31 | - Add a new `Text` widget and choose the newly added `STATUS` variable. 32 | - Change the pre-defined status color items according to the event names from the code above. 33 | - As a result, you should have the following items: 34 | `{ IDLE: #00ff00} { RING: #ff6600} { BOOM!: #ff0000}` 35 | 36 | Now this widget displays an incoming status with color. 37 | 38 | 39 | # Connect DS18B20 Temperature Sensor 40 | 41 | This example shows how to use the [DS18B20](https://datasheets.maximintegrated.com/en/ds/DS18B20.pdf) temperature sensor with the Cloud4RPi service. 42 | 43 | ## Prerequisites 44 | 45 | - Configured and [connected](/#connecting-a-new-device) device. 46 | - Breadboard, connecting wires, a pull-up resistor (4.7kΩ). 47 | 48 | ## Schematics 49 | 50 | ![](/res/ds18b20.png) 51 | 52 | - Connect the **GND** pin to any GND pin on your board. 53 | - Connect the **Vdd** pin to a 5V or 3.3V pin. 54 | - Connect the **DQ** pin to the pull-up resistor and the resistor to **Vdd**. 55 | - Connect the **DQ** pin to the **LCD-D2** pin. 56 | 57 | You can connect several 1-Wire devices to the bus without additional resistors. 58 | 59 | ## Code 60 | 61 | - Open the [control.py](https://github.com/cloud4rpi/cloud4rpi-chip-python/blob/master/control.py). 62 | - Replace `__YOUR_DEVICE_TOKEN__` with the device token from the [Device](https://cloud4rpi.io/devices) page. 63 | 64 | - Run `sudo python control.py`. New `Room Temp` and `CPU Temp` variables should appear on the [Device](https://cloud4rpi.io/devices) page. 65 | - Open the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel. 66 | - Add a new **Chart** widget and choose the newly added `Room Temp` variable. 67 | - Add a new **Gauge** widget and choose the newly added `CPU Temp` variable. 68 | 69 | You can now monitor CPU and room temperature using these widgets. 70 | 71 | !!! Note 72 | If you need to start your script automatically when the system loads, install the **control.py** script as a service using our [service_install.sh](https://github.com/cloud4rpi/cloud4rpi-chip-python/blob/master/service_install.sh) script. Refer to the [Installing as a Service](https://docs.cloud4rpi.io/start/chip/#installing-as-a-service) section for more details. 73 | 74 | 75 | 76 | # Secure your MQTT connection 77 | 78 | Cloud4RPi supports the TLS-enabled MQTTs protocol. If your task requires an encrypted data transfer, enable TLS by changing the `cloud4rpi.connect()` method call as follows: 79 | 80 | ```python 81 | device = cloud4rpi.connect(DEVICE_TOKEN, tls_config={'ca_certs': '/etc/ssl/certs/ca-certificates.crt'}) 82 | ``` 83 | 84 | The `tls_config` dictionary holds parameters for the Paho MQTT's [tls_set()](https://github.com/eclipse/paho.mqtt.python#tls_set) function. -------------------------------------------------------------------------------- /docs/howto/o2.md: -------------------------------------------------------------------------------- 1 | # Control Omega LEDs from WEB 2 | 3 | ## Prerequisites 4 | 5 | - Configured and [connected](/#connecting-a-new-device) Omega2 board. 6 | - [Expansion Dock](https://docs.onion.io/omega2-docs/expansion-dock.html) (optional) 7 | 8 | ### Code 9 | 10 | - Open the [control.py](https://github.com/cloud4rpi/cloud4rpi-omega2-python/blob/master/control.py) sample file. 11 | - Replace `__YOUR_DEVICE_TOKEN__` with the device token from the from the [Device](https://cloud4rpi.io/devices) page. 12 | - Run `python control.py`. Four new variables should appear on the [Device](https://cloud4rpi.io/devices) page: `Omega LED`, `RGB LED - Red`, `RGB LED - Green` and `RGB LED - Blue`. 13 | - Open the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel. 14 | - Add a **Switch** widget and bind them to the `Omega LED` variable. 15 | - Add **Slider** widgets and bind them to `RGB LED` variables with range from 0 to 255. 16 | 17 | You can now change the onboard LED state (and RGB LED color if you use the Expansion Dock) with these widgets. 18 | 19 | 20 | # Secure your MQTT connection 21 | 22 | Cloud4RPi supports the TLS-enabled MQTTs protocol. If your task requires an encrypted data transfer, follow the steps below: 23 | 24 | 1. Install a package that provides the CA certificates for SSL and TLS protocols: 25 | 26 | ```sh 27 | opkg update && opkg install ca-certificates 28 | ``` 29 | 30 | 2. Enable TLS by changing the `cloud4rpi.connect()` method call as follows: 31 | 32 | ```python 33 | device = cloud4rpi.connect(DEVICE_TOKEN, tls_config={'ca_certs': '/etc/ssl/certs/ca-certificates.crt'}) 34 | ``` 35 | 36 | The `tls_config` dictionary holds parameters for the Paho MQTT's [tls_set()](https://github.com/eclipse/paho.mqtt.python#tls_set) function. 37 | 38 | -------------------------------------------------------------------------------- /docs/howto/rpi.md: -------------------------------------------------------------------------------- 1 | # Control LED from WEB using Raspberry Pi 2 | 3 | ## Prerequisites 4 | 5 | - Configured and [connected](/#connecting-a-new-device) device. 6 | - Breadboard, connecting wires, 330Ω..1kΩ resistor. 7 | 8 | ## Code 9 | 10 | - Open the [control.py](https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python/blob/master/control.py) sample file. 11 | - Replace `__YOUR_DEVICE_TOKEN__` with the device token from the [Device](https://cloud4rpi.io/devices) page. 12 | - Connect an LED to a GPIO pin and set the correct value to the `LED_PIN` variable. The default pin is **GPIO18** (Pin 12). 13 | - Run `sudo python control.py`. A new `LED On` variable should appear on the [Device](https://cloud4rpi.io/devices) page. 14 | - Open the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel. 15 | - Add a new **Switch** widget and choose the newly added `LED On` variable. 16 | 17 | You can now switch the LED state using this widget. 18 | 19 | 20 | # Monitor Device Events using Colored Status 21 | 22 | ## Prerequisites 23 | 24 | - Configured and [connected](/#connecting-a-new-device) device. 25 | 26 | ## Code 27 | 28 | - Open the [control.py](https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python/blob/master/control.py) sample file. 29 | - Replace `__YOUR_DEVICE_TOKEN__` with the device token from the [Device](https://cloud4rpi.io/devices) page. 30 | - Run `sudo python control.py`. A new `STATUS` variable should appear on the [Device](https://cloud4rpi.io/devices) page. 31 | - Open the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel or open an existing one. 32 | - Add a new `Text` widget and choose the newly added `STATUS` variable. 33 | - Change the pre-defined status color items according to the event names from the code above. 34 | - As a result, you should have the following items: 35 | `{ IDLE: #00ff00} { RING: #ff6600} { BOOM!: #ff0000}` 36 | 37 | Now this widget displays an incoming status with color. 38 | 39 | 40 | 41 | # Connect DS18B20 Temperature Sensor 42 | 43 | This example shows how to use the [DS18B20](https://datasheets.maximintegrated.com/en/ds/DS18B20.pdf) temperature sensor with the Cloud4RPi service. 44 | 45 | ## Prerequisites 46 | 47 | - Configured and [connected](/#connecting-a-new-device) device with 1-Wire support. 48 | - [Enabled](/#prerequisites) 1-Wire interface. 49 | - Breadboard, connecting wires, a pull-up resistor (4.7kΩ). 50 | 51 | ## Schematics 52 | 53 | ![](/res/ds18b20.png) 54 | 55 | - Connect the **GND** pin to any GND pin on your board. 56 | - Connect the **Vdd** pin to a 5V or 3.3V pin. 57 | - Connect the **DQ** pin to the pull-up resistor and the resistor to **Vdd**. 58 | - Connect the **DQ** pin to the 1-Wire pin. The default pin is **GPIO4** (Pin 7). 59 | 60 | You can connect several 1-Wire devices to the bus without additional resistors. 61 | 62 | ## Code 63 | 64 | - Open the [control.py](https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python/blob/master/control.py) sample file. 65 | - Replace `__YOUR_DEVICE_TOKEN__` with your personal device token from the [Device](https://cloud4rpi.io/devices) page. 66 | 67 | - Run `sudo python control.py`. New `Room Temp` and `CPU Temp` variables should appear on the [Device](https://cloud4rpi.io/devices) page. 68 | - Open the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel. 69 | - Add a new **Chart** widget and choose the newly added `Room Temp` variable. 70 | - Add a new **Gauge** widget and choose the newly added `CPU Temp` variable. 71 | 72 | You can now monitor CPU and room temperature using these widgets. 73 | 74 | !!! Note 75 | If you need to start your script automatically when the system loads, install the **control.py** script as a service using our [service_install.sh](https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python/blob/master/service_install.sh) script. Refer to the [Installing as a Service](https://docs.cloud4rpi.io/start/rpi/#installing-as-a-service) section for more details. 76 | 77 | 78 | # Secure your MQTT connection 79 | 80 | Cloud4RPi supports the TLS-enabled MQTTs protocol. If your task requires an encrypted data transfer, enable TLS by changing the `cloud4rpi.connect()` method call as follows: 81 | 82 | ```python 83 | device = cloud4rpi.connect(DEVICE_TOKEN, tls_config={'ca_certs': '/etc/ssl/certs/ca-certificates.crt'}) 84 | ``` 85 | 86 | The `tls_config` dictionary holds parameters for the Paho MQTT's [tls_set()](https://github.com/eclipse/paho.mqtt.python#tls_set) function. -------------------------------------------------------------------------------- /docs/index.md: -------------------------------------------------------------------------------- 1 | # Cloud4RPi Documentation 2 | 3 | This website provides documentation for the [Cloud4RPi](https://cloud4rpi.io/) service—a cloud control panel for your IoT projects. 4 | 5 | --- 6 | 7 | ## Supported Platforms 8 | 9 | Cloud4RPi communicates with almost any device via the [MQTT](https://en.wikipedia.org/wiki/MQTT) or **HTTP** protocol. 10 | 11 | Detailed instructions and examples are available for the following platforms and languages: 12 | 13 | - [Raspberry Pi using Python](/start/rpi/) ([GitHub Repository](https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python)) 14 | - [Next Thing Co. C.H.I.P. using Python](/start/chip/) ([GitHub Repository](https://github.com/cloud4rpi/cloud4rpi-chip-python)) 15 | - [Onion Omega2 using Python](/start/o2/) ([GitHub Repository](https://github.com/cloud4rpi/cloud4rpi-omega2-python)) 16 | - [ESP8266 using MicroPython](/start/esp8266-upy/) ([GitHub Repository](https://github.com/cloud4rpi/cloud4rpi-esp8266-micropython)) 17 | - [ESP8266 or ESP32 using Arduino](/start/esp-ino/) ([GitHub Repository](https://github.com/cloud4rpi/cloud4rpi-esp-arduino)) 18 | - [ESP8266 or ESP32 using PlatformIO](/start/esp-pio/) ([GitHub Repository](https://github.com/cloud4rpi/cloud4rpi-esp-arduino)) 19 | 20 | !!! Note 21 | Python 2 and Python 3 are supported. 22 | 23 | [Contact us](https://cloud4rpi.answerdesk.io/) if your device or preferred language is not listed. 24 | -------------------------------------------------------------------------------- /docs/plans-and-pricing.md: -------------------------------------------------------------------------------- 1 | # Plans and Pricing 2 | 3 | ## The Free Tier 4 | 5 | You receive 5k free [packets](/faq/#what-are-packets) every month. This is enough to send data to the cloud every ten minutes for a month. The table below compares different packet spending rates: 6 | 7 | | | 1 packet per 10 minutes | 1 packet per 5 minutes | 1 packet per minute | 8 | | -------------------------- | ----------------------: | ---------------------: | ------------------: | 9 | | **1 hour** | 6 | 12 | 60 | 10 | | **24 hours** | 144 | 288 | 1,440 | 11 | | **1 week** | 1,008 | 2,016 | 10,080 | 12 | | **1 month** | 4,464 | 8,928 | 44,640 | 13 | | **extra packets required** | 0 | 3,928 | 39,640 | 14 | 15 | ## Purchase Extra Packets 16 | 17 | If you need a higher throughput, you can purchase extra packets. These packets are used only when you have no free packets left. To view prices, refer to the [Pricing](https://cloud4rpi.io/home#pricing) page. 18 | 19 | The web UI's header displays the number of available packets. You can click it for more information. In the invoked menu, click the **Buy more packets** button to purchase additional packets: 20 | 21 | ![Buy Packets](/res/managePackets/buy.png) 22 | 23 | The same functionality is available in the **Pricing Plan** category of your [account settings](https://cloud4rpi.io/account): 24 | 25 | ![Account Settings](/res/managePackets/account-settings.png) 26 | 27 | ## Packet Spending Rate 28 | 29 | You can spend packets at any rate. Unspent free and purchased packets are carried over to the next month. 30 | 31 | ## Send Data When Out of Packets 32 | 33 | If you run out of packets, you can still send data at 1 packet per hour. 34 | 35 | ## Control the Spending Rate 36 | 37 | You can specify a personal spending cap to ensure that you never spend too many packets in rapid succession. To do this, go to your [account settings](https://cloud4rpi.io/account) and locate the **Pricing Plan** category. Use the **Packets limit per hour** slider to specify the spending cap. 38 | 39 | ![Spending Cap](/res/managePackets/spending-cap.png) 40 | 41 | The minimum cap is 1 packet an hour—the maximum is unlimited. 42 | 43 | ## Set Up Your Device 44 | 45 | When you write your device's scripts, make sure to send data to the cloud at a rate based on your budget and requirements. 46 | -------------------------------------------------------------------------------- /docs/res/ds18b20.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/docs/res/ds18b20.png -------------------------------------------------------------------------------- /docs/res/extra.css: -------------------------------------------------------------------------------- 1 | /* theme: mkdocs 2 | 3 | .bs-sidenav>li { 4 | margin-left: 1.5em; 5 | } 6 | ul.nav .main { 7 | margin-left: 0px; 8 | } 9 | 10 | /* theme: readthedocs 11 | 12 | .toctree-l3 { 13 | font-style: italic; 14 | margin-left: 2em; 15 | } 16 | 17 | h1 { 18 | font-size: 36px; 19 | 20 | 21 | /* theme: material */ 22 | 23 | .md-header { 24 | background-color: #29b5ec; 25 | } 26 | 27 | .md-source:hover { 28 | color: #fff; 29 | } 30 | 31 | .md-typeset a, .md-nav__link:focus, .md-nav__link:hover { 32 | color: #29b5ec; 33 | } 34 | 35 | .md-typeset a:active, .md-typeset a:hover, .md-nav__link--active, .md-nav__link:active { 36 | color: #1089b8; 37 | } 38 | 39 | @media only screen and (min-width: 60em) { 40 | .md-search__input { 41 | border: 1px solid hsla(0,0%,100%,0.0); 42 | border-radius: 22px; 43 | transition: background-color .25s cubic-bezier(.1,.7,.1,1), 44 | border-color .25s cubic-bezier(.1,.7,.1,1), 45 | color .25s cubic-bezier(.1,.7,.1,1), 46 | border-radius .25s cubic-bezier(.1,.7,.1,1); 47 | } 48 | 49 | .md-search__input:hover { 50 | background-color: rgba(0, 0, 0, 0); 51 | border-color:hsla(0,0%,100%,0.7); 52 | } 53 | 54 | [data-md-toggle=search]:checked~.md-search__input { 55 | border-radius: .2rem .2rem 0 0; 56 | } 57 | } 58 | 59 | @media only screen and (max-width: 59.9375em) { 60 | .md-nav__source { 61 | background-color: hsl(197, 71%, 40%); 62 | } 63 | } 64 | 65 | @media only screen and (max-width: 76.1875em) { 66 | html .md-nav--primary .md-nav__title--site { 67 | background-color: #29b5ec; 68 | } 69 | } 70 | 71 | .md-nav__item > .md-nav { 72 | font-size: 90% 73 | } -------------------------------------------------------------------------------- /docs/res/managePackets/account-settings.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/docs/res/managePackets/account-settings.png -------------------------------------------------------------------------------- /docs/res/managePackets/buy.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/docs/res/managePackets/buy.png -------------------------------------------------------------------------------- /docs/res/managePackets/packets-info.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/docs/res/managePackets/packets-info.png -------------------------------------------------------------------------------- /docs/res/managePackets/spending-cap.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/docs/res/managePackets/spending-cap.png -------------------------------------------------------------------------------- /docs/res/troubleshooting-unbound-variable.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/docs/res/troubleshooting-unbound-variable.png -------------------------------------------------------------------------------- /docs/start/chip.md: -------------------------------------------------------------------------------- 1 | # Connecting a C.H.I.P. Board 2 | 3 | Follow the instructions below to connect your device to the [Cloud4RPi](https://cloud4rpi.io) control panel. 4 | 5 | ## Prerequisites 6 | 7 | It is advisable to update your system before installing. 8 | 9 | ```sh 10 | sudo apt update && sudo apt upgrade -y 11 | ``` 12 | 13 | Install/update the required packages. 14 | 15 | ```sh 16 | sudo apt install git python3 python3-pip -y 17 | ``` 18 | 19 | You can use alternative methods to [install pip](https://pip.pypa.io/en/stable/installing.html). 20 | 21 | !!! Note 22 | The Cloud4RPi library is compatible with Python 3.2+ and Python 2.7.9+ versions. 23 | 24 | ## Getting the Cloud4RPi Client Library 25 | 26 | Install the library using your preferred Python version. The following command installs and integrates Cloud4RPi with your OS's default Python interpreter (usually Python 3): 27 | 28 | ```sh 29 | sudo pip3 install cloud4rpi 30 | ``` 31 | 32 | If you are using Python 2, use the following command: 33 | 34 | ```sh 35 | sudo python2 -m pip install cloud4rpi 36 | ``` 37 | 38 | !!! Note 39 | For information on how to work with several versions of Python installed, see [Python Documentation](https://docs.python.org/3/installing/). 40 | 41 | If you get an error while using **pip**, try to update the **setuptools** and **pip** packages. 42 | 43 | ```sh 44 | sudo pip3 install --upgrade setuptools pip 45 | ``` 46 | 47 | ## Hacking Together some Code 48 | 49 | We have prepared sample code for several platforms in the [cloud4rpi-chip-python](https://github.com/cloud4rpi/cloud4rpi-chip-python) repository to demonstrate sending data to the Cloud. 50 | 51 | Get Cloud4RPi examples for your device: 52 | 53 | ```sh 54 | git clone https://github.com/cloud4rpi/cloud4rpi-chip-python.git && cd cloud4rpi-chip-python 55 | ``` 56 | 57 | Before running a sample ([control.py](https://github.com/cloud4rpi/cloud4rpi-chip-python/blob/master/control.py)), remember to replace the `__YOUR_DEVICE_TOKEN__` string with your real device token. Use a text editor (for instance, `nano`) to replace `__YOUR_DEVICE_TOKEN__` with the token displayed at the top of the device page on [cloud4rpi.io](https://cloud4rpi.io/). If you have no token yet, open the [Devices](https://cloud4rpi.io/devices) page, create a device using the **New Device** button in the top right corner, and use its token. 58 | 59 | !!! Note 60 | Install the [CHIP_IO](https://github.com/xtacocorex/CHIP_IO) Python library as described [in its documentation](https://github.com/xtacocorex/CHIP_IO) to use the C.H.I.P.'s GPIO subsystem from Python. If you do not need GPIO, remove the `import CHIP_IO.GPIO as GPIO` line and all `GPIO` references from the [control.py](https://github.com/cloud4rpi/cloud4rpi-chip-python/blob/master/control.py) example. 61 | 62 | ## Running 63 | 64 | Execute the script with a Python interpreter, for example: 65 | 66 | ```sh 67 | sudo python3 control.py 68 | ``` 69 | 70 | !!! Note 71 | If you have installed Cloud4RPi to a non-default Python, use the version with the Cloud4RPi library. 72 | 73 | If the script output looks right, open the [Devices](https://cloud4rpi.io/devices) page to see if the device status has changed. 74 | 75 | 76 | ## Installing as a Service 77 | 78 | You can use our service templates to facilitate service installation. Pass the path to your Cloud4RPi-enabled Python script to the [service_install.sh](https://github.com/cloud4rpi/cloud4rpi-chip-python/blob/master/service_install.sh) script as a parameter. 79 | 80 | ```sh 81 | chmod +x service_install.sh 82 | sudo ./service_install.sh your_script.py 83 | ``` 84 | 85 | !!! Note 86 | You need to replace 'your_script.py' with the actual path to your service script. 87 | -------------------------------------------------------------------------------- /docs/start/esp-ino.md: -------------------------------------------------------------------------------- 1 | # Connecting an ESP8266 or ESP32 2 | 3 | Follow the instructions below to connect your [ESP8266](https://en.wikipedia.org/wiki/ESP8266) board (like [NodeMCU Dev Kit](http://www.nodemcu.com/index_en.html#fr_54747661d775ef1a3600009e)) or [ESP32](https://en.wikipedia.org/wiki/ESP32) board (like [ESP32-DevKitC](https://www.espressif.com/en/products/hardware/esp32-devkitc/overview)) to the [Cloud4RPi](https://cloud4rpi.io) control panel. 4 | 5 | ## Getting Libraries and Examples 6 | 7 | 1. Open **Arduino** and select your board in the **Tools** | **Board** menu. Add [ESP8266](https://github.com/esp8266/Arduino#installing-with-boards-manager) or [ESP32](https://github.com/espressif/arduino-esp32/blob/master/docs/arduino-ide/boards_manager.md) support if it is not added yet. 8 | 2. Install the Cloud4RPi library from the **Library Manager**. To do this, open the **Sketch** | **Include Library** | **Manage Libraries** menu, enter `cloud4rpi` into the search field and install the **cloud4rpi-esp-arduino** package. 9 | 3. Install the dependencies: **ArduinoJson** and **PubSubClient** libraries. 10 | 4. Configure the installed libraries: 11 | 12 | 1. Open the `%HOMEPATH%\Documents\Arduino\libraries\PubSubClient\src\PubSubClient.h` (`~/Documents/Arduino/libraries/PubSubClient/src/PubSubClient.h` on Mac) file with any text editor (for instance, [VS Code](https://code.visualstudio.com)). 13 | 2. Add the following define directives at the beginning: 14 | 15 | #define MQTT_MAX_PACKET_SIZE 1024 16 | #define MQTT_MAX_TRANSFER_SIZE 128 17 | 18 | 3. [Optional] Open the `%HOMEPATH%\Documents\Arduino\libraries\cloud4rpi-esp-arduino\src\Cloud4RPi.h` (`~/Documents/Arduino/libraries/cloud4rpi-esp-arduino/src/Cloud4RPi.h` on Mac) file and add the `#define CLOUD4RPI_DEBUG 1` line at the beginning to enable verbose output. 19 | 20 | ## Opening Sample Code 21 | 22 | 5. Use the **File** | **Examples** | **cloud4rpi-esp-arduino** menu item to open the sample code. Restart Arduino IDE if this item does not appear. 23 | 6. Select the **ESP32 Dev Module** board in **Tools** menu. 24 | 7. If the `LED_BUILTIN` constant is not defined in your board's library, change this constant to the LED's pin number (for example, `2`). 25 | 8. Replace the `__SSID__` and `__PASSWORD__` strings with your Wi-Fi network data. 26 | 27 | ## Connecting to Your Cloud4RPi Account 28 | 29 | 4. [Log in to your Cloud4RPi account](https://cloud4rpi.io/signin) or [create a new one](https://cloud4rpi.io/register). 30 | 5. Copy [your device](https://cloud4rpi.io/devices)'s **Device Token**. You can create a device on the [Devices](https://cloud4rpi.io/devices) page and copy its **Device Token** if you do not have one. 31 | 6. Replace the `__YOUR_DEVICE_TOKEN__` string with your device token. 32 | 33 | ## Running 34 | 35 | 6. Hit the `Build` button and wait until the compilation is completed. 36 | 7. Hit the `Upload` button. 37 | 8. If the upload fails, try to start the board in the flashing mode (connect the power supply with the GPIO0 pin connected to GND) and try uploading again. 38 | 9. Once flashing is complete, open `Serial Monitor` to monitor the device's status. 39 | 10. Notice that the device on the [Devices page](https://cloud4rpi.io/devices) went online and started sending data. 40 | 11. Go to the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel. 41 | 12. Add a new **Switch** widget and bind it to the `LED On` variable. 42 | 13. Add a new **Text** widget and bind it to the `State` variable. Configure different colors for the **"IDLE"**, **"RING"** and **"BOOM!"** strings. 43 | 14. Add a new **Slider** widget and bind it to the `DesiredTemp` variable, set its minimum value to 10 and maximum value to 30. 44 | 15. Add a new **Gauge** widget and bind it to the `DesiredTemp` variable, set its minimum value to 10 and maximum value to 30. 45 | 46 | ## Video 47 | 48 | 49 | -------------------------------------------------------------------------------- /docs/start/esp-pio.md: -------------------------------------------------------------------------------- 1 | # Connecting an ESP8266 or ESP32 2 | 3 | Follow the instructions below to connect your [ESP8266](https://en.wikipedia.org/wiki/ESP8266) board (like [NodeMCU Dev Kit](http://www.nodemcu.com/index_en.html#fr_54747661d775ef1a3600009e)) or [ESP32](https://en.wikipedia.org/wiki/ESP32) board (like [ESP32-DevKitC](https://www.espressif.com/en/products/hardware/esp32-devkitc/overview)) to the [Cloud4RPi](https://cloud4rpi.io) control panel. 4 | 5 | ## Creating a Project 6 | 7 | The [Cloud4RPi library](http://platformio.org/lib/show/2045/cloud4rpi-esp-arduino) is published in the [PlatformIO Registry](http://platformio.org/lib). Follow the instructions below to start a new Cloud4RPi-enabled project: 8 | 9 | 1. Create a new PlatformIO project for your board as described in the PlatformIO documentation ([Visual Studio Code](http://docs.platformio.org/en/latest/ide/vscode.html#id3), [Atom](http://docs.platformio.org/en/latest/ide/atom.html#setting-up-the-project)) 10 | 2. Open your `platformio.ini` and add the following lines to the end: 11 | 12 | lib_deps = 13 | cloud4rpi-esp-arduino 14 | 15 | build_flags= 16 | ; Required for PubSub library 17 | -D MQTT_MAX_PACKET_SIZE=1024 18 | -D MQTT_MAX_TRANSFER_SIZE=128 19 | ; Enables the verbose output to Serial 20 | -D CLOUD4RPI_DEBUG=1 21 | 22 | 3. Save the `platformio.ini` file and open the `src\main.cpp` file. 23 | 4. Copy-paste the [sample code](https://github.com/cloud4rpi/cloud4rpi-esp-arduino/blob/master/examples/control/control.ino). 24 | 5. If the `LED_BUILTIN` constant is not defined in your board's library, change this constant to the LED's pin number (for example, `2`). 25 | 6. Replace the `__SSID__` and `__PASSWORD__` strings with your Wi-Fi network data. 26 | 27 | ## Connecting to Your Cloud4RPi Account 28 | 29 | 4. [Log in to your Cloud4RPi account](https://cloud4rpi.io/signin) or [create a new one](https://cloud4rpi.io/register). 30 | 5. Copy [your device](https://cloud4rpi.io/devices)'s **Device Token**. You can create a device on the [Devices](https://cloud4rpi.io/devices) page and copy its **Device Token** if you do not have one. 31 | 6. Replace the `__YOUR_DEVICE_TOKEN__` string with your device token. 32 | 33 | ## Running 34 | 35 | 6. Hit the `Build` button and wait until the compilation is completed. 36 | 7. Hit the `Upload` button. 37 | 8. If the upload fails, try to start the board in the flashing mode (connect the power supply with the GPIO0 pin connected to GND) and try uploading again. 38 | 9. Once flashing is complete, open `Serial Monitor` to monitor the device's status. 39 | 10. Notice that the device on the [Devices page](https://cloud4rpi.io/devices) went online and started sending data. 40 | 11. Go to the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel. 41 | 12. Add a new **Switch** widget and bind it to the `LED On` variable. 42 | 13. Add a new **Text** widget and bind it to the `State` variable. Configure different colors for the **"IDLE"**, **"RING"** and **"BOOM!"** strings. 43 | 14. Add a new **Slider** widget and bind it to the `DesiredTemp` variable, set its minimum value to 10 and maximum value to 30. 44 | 15. Add a new **Gauge** widget and bind it to the `DesiredTemp` variable, set its minimum value to 10 and maximum value to 30. 45 | 46 | ## Video 47 | 48 | 49 | -------------------------------------------------------------------------------- /docs/start/esp8266-upy.md: -------------------------------------------------------------------------------- 1 | # Connecting an ESP8266 2 | 3 | Follow the instructions below to connect your device to the [Cloud4RPi](https://cloud4rpi.io) control panel. 4 | 5 | ## Prerequisites 6 | 7 | Your ESP8266 module should have at least 1Mbyte of flash storage to install the full version of MicroPython. 8 | 9 | 1. Flash the latest version of [MicroPython](http://micropython.org/) using [the official manual](http://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/intro.html#intro). 10 | 2. Connect to your Wi-Fi network: 11 | 12 | >>> from network import WLAN 13 | >>> STA = WLAN(0); STA.active(1) 14 | >>> STA.connect('__SSID__', '__PASSWORD__') 15 | >>> STA.ifconfig() # Outputs the network configuration. If it is not valid, wait and re-execute 16 | 17 | 3. Configure [WebREPL](http://docs.micropython.org/en/latest/esp8266/esp8266/tutorial/repl.html#webrepl-a-prompt-over-wifi) for easier file uploading. 18 | 19 | >>> import webrepl_setup 20 | 21 | 4. Connect to the ESP8266 via **WebREPL**. 22 | 23 | ## Getting Libraries and Examples 24 | 25 | Download the required source code files to your computer: 26 | 27 | - [simple.py](https://github.com/micropython/micropython-lib/blob/master/umqtt.simple/umqtt/simple.py): MQTT Library for MicroPython. Save this file as **mqtt.py** when downloading. 28 | - [cloud4rpi.py](https://github.com/cloud4rpi/cloud4rpi-esp8266-micropython/blob/master/cloud4rpi.py): Cloud4RPi client library for MicroPython. 29 | - [main.py](https://github.com/cloud4rpi/cloud4rpi-esp8266-micropython/blob/master/main.py): Sample code. 30 | 31 | 32 | ## Hacking Together some Code 33 | 34 | Open the [main.py](https://github.com/cloud4rpi/cloud4rpi-esp8266-micropython/blob/master/main.py) file in a text editor (for instance, [Visual Studio Code](https://code.visualstudio.com/)) and replace the following strings: 35 | 36 | - `__SSID__` with your Wi-Fi network name. 37 | - `__PWD__` with your Wi-Fi network password. If you have an open network, remove the `'__PWD__'` element without removing the trailing comma so that the `WIFI_SSID_PASSWORD` variable becomes a tuple with one element. 38 | - `__YOUR_DEVICE_TOKEN__` with the token displayed at the top of the device page on [cloud4rpi.io](https://cloud4rpi.io/). If you have no token yet, open the [Devices](https://cloud4rpi.io/devices) page, create a device using the **New Device** button in the top right corner, and use its token. 39 | 40 | Save the file. 41 | 42 | ## The LED & Button Example's Hardware 43 | 44 | Connect the LED to **GPIO12** and a button to **GPIO16**. If you need to use other pins, change the corresponding variables in **main.py**. 45 | 46 | ![](https://github.com/cloud4rpi/cloud4rpi-esp8266-micropython/raw/master/hardware.png) 47 | 48 | ## Running 49 | 50 | 1. Upload three files (**mqtt.py**, **cloud4rpi.py** and **main.py**) to your ESP8266 via the **WebREPL**. 51 | 6. Reset the ESP8266. You can use the console for this: 52 | 53 | >>> import machine 54 | >>> machine.reset() 55 | 56 | 8. Check that the [device](https://cloud4rpi.io/devices) goes online and starts sending data. 57 | 9. Go to the [Control Panels](https://cloud4rpi.io/control-panels/) page and add a new control panel. 58 | 10. Add a new **Switch** widget and bind it to the `LED` variable. 59 | 11. Add a new **Text** widget and bind it to the `Button` variable. Configure different colors for the "true" and "false" strings. 60 | 12. Press the hardware button and notice the changes on the control panel. 61 | 13. Use the **LED** switch on the control panel to light the hardware LED. 62 | 63 | Explore the code of the [main.py](https://github.com/cloud4rpi/cloud4rpi-esp8266-micropython/blob/master/main.py) file and adapt it for your needs. Feel free to [share](https://cloud4rpi.answerdesk.io/) your projects and ideas with us! 64 | -------------------------------------------------------------------------------- /docs/start/o2.md: -------------------------------------------------------------------------------- 1 | # Connecting an Omega2 Board 2 | 3 | Follow the instructions below to connect your device to the [Cloud4RPi](https://cloud4rpi.io) control panel. 4 | 5 | ## Prerequisites 6 | 7 | Install/update the required packages. 8 | 9 | ```sh 10 | opkg update 11 | opkg install wget python3 python3-pip 12 | pip3 install --upgrade setuptools pip 13 | ``` 14 | 15 | You can use alternative methods to [install pip](https://pip.pypa.io/en/stable/installing.html). 16 | 17 | !!! Note 18 | The Cloud4RPi library is compatible with Python 3.2+ and Python 2.7.9+ versions. 19 | 20 | ## Getting the Cloud4RPi Client Library 21 | 22 | Install the library using your preferred Python version. The following command installs and integrates Cloud4RPi with your OS's default Python interpreter (usually Python 3): 23 | 24 | ```sh 25 | pip3 install cloud4rpi 26 | ``` 27 | 28 | ## Hacking Together some Code 29 | 30 | We have prepared sample code for several platforms in the [cloud4rpi-omega2-python](https://github.com/cloud4rpi/cloud4rpi-omega2-python) repository to demonstrate sending data to the Cloud. 31 | 32 | Get Cloud4RPi examples for your device: 33 | 34 | ```sh 35 | mkdir cloud4rpi-omega2-python && cd cloud4rpi-omega2-python 36 | repo="https://raw.githubusercontent.com/cloud4rpi/cloud4rpi-omega2-python/master" 37 | wget "$repo/omega2.py" "$repo/control.py" 38 | ``` 39 | 40 | !!! Note 41 | You can install **git** if your board has sufficient memory and you prefer using it, and clone this repository with the following command: `opkg install git git-http ca-bundle && git clone https://github.com/cloud4rpi/cloud4rpi-omega2-python.git && cd cloud4rpi-omega2-python` 42 | 43 | Before running a sample ([control.py](https://github.com/cloud4rpi/cloud4rpi-omega2-python/blob/master/control.py)), remember to replace the `__YOUR_DEVICE_TOKEN__` string with your real device token. Use a text editor (for instance, `vim`) to replace `__YOUR_DEVICE_TOKEN__` with the token displayed at the top of the device page on [cloud4rpi.io](https://cloud4rpi.io/). If you have no token yet, open the [Devices](https://cloud4rpi.io/devices) page, create a device using the **New Device** button in the top right corner, and use its token. 44 | 45 | 46 | ## Running 47 | 48 | Execute the script with a Python interpreter, for example: 49 | 50 | ```sh 51 | python3 control.py 52 | ``` 53 | 54 | !!! Note 55 | If you have installed Cloud4RPi to a non-default Python, use the version with the Cloud4RPi library. 56 | 57 | If the script output looks right, open the [Devices](https://cloud4rpi.io/devices) page to see if the device status has changed. 58 | 59 | -------------------------------------------------------------------------------- /docs/start/rpi.md: -------------------------------------------------------------------------------- 1 | # Connecting a Raspberry Pi Board 2 | 3 | Follow the instructions below to connect your device to the [Cloud4RPi](https://cloud4rpi.io) control panel. 4 | 5 | ## Prerequisites 6 | 7 | It is advisable to update your system before installing. 8 | 9 | ```sh 10 | sudo apt update && sudo apt upgrade -y 11 | ``` 12 | 13 | Install/update the required packages. 14 | 15 | ```sh 16 | sudo apt install git python3 python3-pip -y 17 | ``` 18 | 19 | You can use alternative methods to [install pip](https://pip.pypa.io/en/stable/installing.html). 20 | 21 | !!! Note 22 | The Cloud4RPi library is compatible with Python 3.2+ and Python 2.7.9+ versions. 23 | 24 | 25 | ### [Optional] Enable interfaces 26 | 27 | - Run `sudo raspi-config` 28 | - Open a section for configuring additional interfaces (`Advanced Options` or `Interfacing Options | Configure connections to peripherals` depending on the version). 29 | - Enable I2C, 1-wire and other necessary interfaces. 30 | - Choose ``. 31 | - Reboot the device with the `sudo reboot` command. 32 | 33 | 34 | ## Getting the Cloud4RPi Client Library 35 | 36 | Install the library using your preferred Python version. The following command installs and integrates Cloud4RPi with your OS's default Python interpreter (usually Python 3): 37 | 38 | ```sh 39 | sudo pip3 install cloud4rpi 40 | ``` 41 | 42 | If you are using Python 2, use the following command: 43 | 44 | ```sh 45 | sudo python2 -m pip install cloud4rpi 46 | ``` 47 | 48 | !!! Note 49 | For information on how to work with several versions of Python installed, see [Python Documentation](https://docs.python.org/3/installing/). 50 | 51 | If you get an error while using **pip**, try to update the **setuptools** and **pip** packages. 52 | 53 | ```sh 54 | sudo pip3 install --upgrade setuptools pip 55 | ``` 56 | 57 | ## Hacking Together some Code 58 | 59 | We have prepared sample code for several platforms in the [cloud4rpi-raspberrypi-python](https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python) repository to demonstrate sending data to the Cloud. 60 | 61 | Get Cloud4RPi examples for your device: 62 | 63 | ```sh 64 | git clone https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python.git && cd cloud4rpi-raspberrypi-python 65 | ``` 66 | 67 | Before running a sample ([control.py](https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python/blob/master/control.py)), remember to replace the `__YOUR_DEVICE_TOKEN__` string with your real device token. Use a text editor (for instance, `nano`) to replace `__YOUR_DEVICE_TOKEN__` with the token displayed at the top of the device page on [cloud4rpi.io](https://cloud4rpi.io/). If you have no token yet, open the [Devices](https://cloud4rpi.io/devices) page, create a device using the **New Device** button in the top right corner, and use its token. 68 | 69 | 70 | ## Running 71 | 72 | Execute the script with a Python interpreter, for example: 73 | 74 | ```sh 75 | sudo python3 control.py 76 | ``` 77 | 78 | !!! Note 79 | If you have installed Cloud4RPi to a non-default Python, use the version with the Cloud4RPi library. 80 | 81 | If the script output looks right, open the [Devices](https://cloud4rpi.io/devices) page to see if the device status has changed. 82 | 83 | 84 | ## Installing as a Service 85 | 86 | You can use our service templates to facilitate service installation. Pass the path to your Cloud4RPi-enabled Python script to the [service_install.sh](https://github.com/cloud4rpi/cloud4rpi-raspberrypi-python/blob/master/service_install.sh) script as a parameter. 87 | 88 | ```sh 89 | chmod +x service_install.sh 90 | sudo ./service_install.sh your_script.py 91 | ``` 92 | 93 | !!! Note 94 | You need to replace 'your_script.py' with the actual path to your service script. 95 | 96 | 97 | ## Video 98 | 99 | -------------------------------------------------------------------------------- /docs/troubleshooting.md: -------------------------------------------------------------------------------- 1 | ## I receive installation errors 2 | 3 | You can get one of the following errors when you use the `sudo pip install cloud4rpi` command to install the Cloud4RPi client library: 4 | 5 | 1. InstallationError: Command "python setup.py egg_info" failed with error code 1 6 | 2. Error while finding spec for 'pip.\_\_main\_\_' (<class 'ImportError'>: cannot import name 'IncompleteRead'); 'pip' is a package and cannot be directly executed 7 | 8 | This happens because the **setuptools** and/or **pip** packages your Python interpreter uses are outdated. Update the packages with the following command: 9 | 10 | ```sh 11 | sudo pip install --upgrade setuptools pip 12 | ``` 13 | 14 | After updating, reinstall **cloud4rpi**: 15 | 16 | ```sh 17 | sudo pip install cloud4rpi 18 | ``` 19 | 20 | 21 | 22 | ## Raspberry Pi does not recognize my 1-Wire device 23 | 24 | Follow the instructions below if you experience issues with the 1-Wire interface on Raspberry Pi. 25 | 26 | 1. Run `sudo raspi-config` and make sure that the 1-Wire interface is enabled (**Interfacing Options** | **1-Wire** menu). 27 | 2. Add the `dtoverlay=w1-gpio` string to your `/boot/config.txt` file (`echo dtoverlay=w1-gpio | sudo tee -a /boot/config.txt`). 28 | 3. Reboot (`sudo reboot` command). 29 | 4. Double-check the wiring and your device's operational voltage. The 1-Wire **DATA** bus should be connected to **GPIO4** (Pin 7) and pulled-up to **VCC**. 30 | 31 | ![](/res/ds18b20.png) 32 | 33 | 34 | 35 | ## I receive an "Insecure Platform" warning 36 | 37 | The `InsecurePlatformWarning: A true SSLContext object is not available...` notification appears when you run Cloud4RPi on Python v2.7.9 and earlier. Use the following command to check the Python version: 38 | 39 | ```sh 40 | python --version 41 | ``` 42 | 43 | You can use [one of the following approaches](https://docs.python.org/2/using/index.html) to install the latest version: 44 | 45 | 46 | 47 | ## I get a WiFi library collision in the Arduino IDE 48 | 49 | The `Multiple libraries were found for "WiFi.h"` message can appear in Arduino IDE. This indicates the IDE has two libraries with the same name, and it does not know which one to use. 50 | 51 | To avoid this error, specify the absolute path to the header file in the `#include` directive, for example: 52 | 53 | ```c 54 | #include 55 | ``` 56 | 57 | You can copy-paste the valid path to both libraries that appear in the error message. Add the `src\` subfolder between the library path and header file name. 58 | 59 | 60 | ## A control panel widget displays a "No data found" error 61 | 62 | This means that a variable's name was changed on the device. 63 | 64 | ![Unbound Variable](/res/troubleshooting-unbound-variable.png) 65 | 66 | If you revert to the old name or assign the new name the widget, the widget will successfully bind to the variable and retain all its data. 67 | 68 | -------------------------------------------------------------------------------- /example-img/omega_led.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/example-img/omega_led.png -------------------------------------------------------------------------------- /example-img/omega_rgb.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/example-img/omega_rgb.png -------------------------------------------------------------------------------- /example-img/panel.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/cloud4rpi/docs/284bd9caaca995c9160b6d3a04c4c10f881e627b/example-img/panel.png -------------------------------------------------------------------------------- /mkdocs.yml: -------------------------------------------------------------------------------- 1 | site_name: Cloud4RPi Documentation 2 | site_description: Cloud control panel for your IoT projects. 3 | site_author: Cloud4RPi Team 4 | repo_url: https://github.com/cloud4rpi/docs 5 | 6 | nav: 7 | - Home: index.md 8 | - Getting Started: 9 | - Raspberry Pi: start/rpi.md 10 | - C.H.I.P.: start/chip.md 11 | - Omega2: start/o2.md 12 | - ESP8266/ESP32: 13 | - MicroPython: start/esp8266-upy.md 14 | - PlatformIO: start/esp-pio.md 15 | - Arduino: start/esp-ino.md 16 | - Plans and Pricing: plans-and-pricing.md 17 | - How To: 18 | - Raspberry Pi: howto/rpi.md 19 | - C.H.I.P.: howto/chip.md 20 | - Omega2: howto/o2.md 21 | - API: 22 | - Python Library: api/python.md 23 | - MQTT Protocol: api/mqtt.md 24 | - HTTP Protocol: api/http.md 25 | - Client Libraries: client-libraries.md 26 | - FAQ: faq.md 27 | - Troubleshooting: troubleshooting.md 28 | 29 | markdown_extensions: 30 | - admonition: 31 | - attr_list: 32 | 33 | extra_css: [res/extra.css] 34 | theme: material 35 | 36 | copyright: © 2016-2020 Devsoft Baltic OÜ. All rights reserved. 37 | -------------------------------------------------------------------------------- /serve.sh.bat: -------------------------------------------------------------------------------- 1 | mkdocs serve --------------------------------------------------------------------------------