{"id":13799808,"url":"https://github.com/adafruit/adafruit-io-node","last_synced_at":"2025-10-03T06:30:18.150Z","repository":{"id":24636749,"uuid":"28046029","full_name":"adafruit/adafruit-io-node","owner":"adafruit","description":"A Node.js Adafruit IO Node.js Client, Local Server, \u0026 io.adafruit.com TLS Tunnel.","archived":true,"fork":false,"pushed_at":"2016-06-14T21:20:20.000Z","size":1324,"stargazers_count":103,"open_issues_count":4,"forks_count":26,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-01-19T18:54:15.701Z","etag":null,"topics":["adafruit-io"],"latest_commit_sha":null,"homepage":"https://io.adafruit.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adafruit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-15T16:46:43.000Z","updated_at":"2024-04-23T08:12:31.000Z","dependencies_parsed_at":"2022-09-08T05:41:15.835Z","dependency_job_id":null,"html_url":"https://github.com/adafruit/adafruit-io-node","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adafruit%2Fadafruit-io-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adafruit%2Fadafruit-io-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adafruit%2Fadafruit-io-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adafruit%2Fadafruit-io-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adafruit","download_url":"https://codeload.github.com/adafruit/adafruit-io-node/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235079282,"owners_count":18932498,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adafruit-io"],"created_at":"2024-08-04T00:01:06.276Z","updated_at":"2025-10-03T06:30:17.709Z","avatar_url":"https://github.com/adafruit.png","language":"JavaScript","funding_links":[],"categories":["\u003ca id=\"01e6651181d405ecdcd92a452989e7e0\"\u003e\u003c/a\u003e工具","Code"],"sub_categories":["\u003ca id=\"9d6789f22a280f5bb6491d1353b02384\"\u003e\u003c/a\u003e隧道\u0026\u0026穿透"],"readme":"# Adafruit IO [![Build Status](https://travis-ci.org/adafruit/adafruit-io-node.svg?branch=master)](https://travis-ci.org/adafruit/adafruit-io-node)\nA Node.js Adafruit IO Client, Local Server, \u0026 io.adafruit.com TLS Tunnel.\n\n## Installation\nMake sure you have [Node.js][5] **v4.0.0 or higher** installed on your computer.\n\n```console\n$ node -v\nv4.0.0\n```\nInstall `forever` and `adafruit-io` on your computer using `npm`.\n\n```console\n$ npm install -g forever adafruit-io\n```\n\nYou can also optionally install `forever-service` if you are using a Linux distro, and would like to run the server as a service.\n\n```console\n$ npm install -g forever-service\n```\n## Table of Contents\n* [Server](#server)\n  * [Usage](#usage)\n* [TLS Tunnel](#tls-tunnel)\n  * [Security Considerations](#security-considerations)\n  * [Usage](#usage-1)\n* [Client](#client)\n  * [Usage](#usage-2)\n    * [Authentication](#authentication)\n    * [Feeds](#feeds)\n    * [Data](#data)\n    * [Groups](#groups)\n\n## Help\nView the available sub commands for `adafruit-io`:\n\n```console\n$ adafruit-io help\nUsage: adafruit-io \u003ccommand\u003e\n\nCommands:\n  server      Adafruit IO local server\n  client      Adafruit IO client\n  tunnel      TLS tunnel to io.adafruit.com\n  help        Show help\n  version     Show version info\n  completion  generate bash completion script\n```\n\nThe three main commands available are `service`, `tunnel`, and `help`.\n\n## Server\nThe server included in this package is an open source API compatible version of\nAdafruit IO that you can run locally. Future additions to io.adafruit.com will\nallow you to sync your local data with the hosted service.\n\n### Usage\nThe tunnel commands will always be prefixed with `adafruit-io server`, and you can always get more information\nabout the available commands by running `adafruit-io server help`.\n\n#### Configuration\n\nFirst, you will need to configure the server with a `username` and `key` that\nyou will expect when clients make requests to the server. Let's look at the help\nfor `adafruit-io server config help`.\n\n```console\n$ adafruit-io server config help\nUsage: adafruit-io server config [options]\n\nCommands:\n  help  Show help\n\nOptions:\n  -p, --port      Server port                    [default: \"8080\"]\n  -u, --username  Local Adafruit IO Username            [required]\n  -k, --key       Local Adafruit IO Key                 [required]\n```\n\nThe `--username` and `--key` you set here will be used by the server to authenticate requests from\nyour devices. You can set them to any value, but make sure the Adafruit IO Key is not easily\nguessable.\n\n```console\n$ adafruit-io server config --username test_user --key efoih3r8hsfdfh1r31rhsdhf\n[info] Server settings saved\n```\nTo start the server daemon, you can run the following command on the default port of `8080`\n```console\n$ adafruit-io server start\n                                     ▄▄\n                                   ▄████\n                                 ▄███████\n                                █████████▌\n                               ███████████\n                              ████████████▌\n             ███████████████▄ ████████████▌\n              █████████████████████▀▀█████ ▄▄▄▄▄▄▄\n               ▐██████████████████   █████████████████▄▄\n                 ▀█████████  ▀▀███  ██████████████████████\n                   █████████▄▄  ▐████▀    ▐█████████████▀\n                     ▀▀███████████████▄▄█████████████▀\n                      ▄███████   ██  ▀████████████▀\n                     ███████▀  ▄████  ▐█████▄\n                    █████████████████▄▄██████▄\n                   ███████████████████████████\n                  ██████████████ ▐████████████▌\n                 ▐██████████▀▀    ▀███████████▌\n                 █████▀▀            ▀█████████▌\n                                       ▀██████\n                                          ▀███\n----------------------------------------------------------------------\n                           adafruit io\n----------------------------------------------------------------------\n[info] server ready at http://todd.local:8080/\n[info] documentation is available at http://todd.local:8080/api/docs\n```\nThe server will stay up until you shut down your computer, or stop the server.\nTo stop the server, run the following command:\n\n```console\n$ adafruit-io server stop\n[info] stopping server...\n```\n\nIf you would like to run the server on a different port, you can use the `-p` option\nto set the port you wish to use. **Note**: As as a general rule processes running\nwithout root privileges cannot bind to ports below 1024. Use a port \u003e 1024, or run\nthe server using elevated privileges via `sudo`, but this is not recommended.\n\n## TLS Tunnel\nThis is a TLS/SSL tunnel for securely connecting HTTP and MQTT clients to io.adafruit.com.\nInstead of pointing your MQTT or HTTP client at io.adafruit.com, use the IP address\nor hostname of the computer you are running the tunnel on.\n\n### HTTP\nRequests to port 8888 on the Pi will be tunneled to HTTPS port 443 on io.adafruit.com.\n\n### MQTT\nConnections to port 1883 on the Pi will be tunneled to MQTTS port 8883 on io.adafruit.com.\n\n### Security Considerations\n\nThe purpose of this service is to add an encryption layer, specifically TLS, to your adafruit IO messages in transit across the Internet. Not all IoT radio modules have a TLS stack and if you sent a message to adafruit.io with that device, it would be unencrypted at the application layer. For example, the message would be encrypted by the radio at the WiFi layer, but would be unencrypted at the Ethernet layer as it went from your router to the Internet.\n\nThe danger of unencrypted application messages are two-fold. The first is that your message may be modified in transit but more importantly, your message can be read by any server that routes your traffic. It's like sending a postcard. If you made a adafruit.io connected garage door, then a lot of people (and machines) would know when the door opened and closed.\n\nTherefore, this service protects your data from prying eyes on the Internet.\n\nHowever, this service runs as an unauthenticated service on your network. This is by design so that your IoT device can make a connection to it. But it also means that anything on your network can talk to this service. Your adafruit.io credentials are *not* stored on this gateway service, but on your IoT device. So an attacker would still need to know your adafuit.io credentials to post to adafruit.io.\n\nLastly, this service does not protect cellular modules. If you have something like a Adafruit FONA, then it makes an Internet connection directly through the cellular system and unless there is a TLS stack on the module, than most likely it's not end-to-end encrypted.\n\n### Usage\nThe tunnel commands will always be prefixed with `adafruit-io tunnel`, and you can always get more information\nabout the available commands by running `adafruit-io tunnel help`.\n\n```console\n$ adafruit-io tunnel help\nUsage: adafruit-io tunnel \u003ccommand\u003e [options]\n\nCommands:\n  install  Install tunnel service (linux only)\n  remove   Remove tunnel service (linux only)\n  start    Start tunnel daemon\n  restart  Restart tunnel daemon\n  stop     Stop tunnel daemon\n  help     Show help\n\nOptions:\n  -h, --http  HTTP port             [default: \"8888\"]\n  -m, --mqtt  MQTT port             [default: \"1883\"]\n```\n\nTo start the tunnel daemon, you can run the following command on the default port of `8888`:\n```console\n$ adafruit-io tunnel start\n                                     ▄▄\n                                   ▄████\n                                 ▄███████\n                                █████████▌\n                               ███████████\n                              ████████████▌\n             ███████████████▄ ████████████▌\n              █████████████████████▀▀█████ ▄▄▄▄▄▄▄\n               ▐██████████████████   █████████████████▄▄\n                 ▀█████████  ▀▀███  ██████████████████████\n                   █████████▄▄  ▐████▀    ▐█████████████▀\n                     ▀▀███████████████▄▄█████████████▀\n                      ▄███████   ██  ▀████████████▀\n                     ███████▀  ▄████  ▐█████▄\n                    █████████████████▄▄██████▄\n                   ███████████████████████████\n                  ██████████████ ▐████████████▌\n                 ▐██████████▀▀    ▀███████████▌\n                 █████▀▀            ▀█████████▌\n                                       ▀██████\n                                          ▀███\n----------------------------------------------------------------------\n                           adafruit io\n----------------------------------------------------------------------\n[info] io.adafruit.com HTTPS tunnel running: http://todd.local:8888/\n[info] io.adafruit.com MQTTS tunnel running: mqtt://todd.local:1883\n```\n\nThe tunnel will stay up until you shut down your computer, or stop the tunnel.\nTo stop the tunnel daemon, run the following command:\n\n```console\n$ adafruit-io tunnel stop\n[info] stopping tunnel...\n```\n\nIf you would like to run the tunnel on a different ports, you can use the `--http` \u0026 `--mqtt` options\nto set the ports you wish to use. **Note**: As as a general rule processes running\nwithout root privileges cannot bind to ports below 1024. Use a port \u003e 1024, or run\nthe tunnel using elevated privileges via `sudo`, but this is not recommended.\n\n## Client\n\nA CLI client for use with [io.adafruit.com][6] or the local Adafruit IO server included in this package.\n\n### Usage\n\nThe client commands will always be prefixed with `adafruit-io client`, and you can append `help` to any\ncommand to get more info about that command.\n\n#### Authentication\n```console\n$ adafruit-io client config help\nUsage: adafruit-io client config [options]\n\nCommands:\n  help  Show help\n\nOptions:\n  -h, --host      Server hostname                   [default: \"io.adafruit.com\"]\n  -p, --port      Server port                                    [default: \"80\"]\n  -u, --username  Adafruit IO Username                                [required]\n  -k, --key       Adafruit IO Key                                     [required]\n\n```\n\nYou can then use your Adafruit IO `username` and `key` to authenticate yourself.\n\n```console\n$ adafruit-io client config --username testing_username --key xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n[info] Client settings saved\n```\n\n#### Feeds\n\nFeeds are the core of the Adafruit IO system. The feed holds metadata about data that gets pushed, and you will\nhave one feed for each type of data you send to the system. You can have separate feeds for each\nsensor in a project, or you can use one feed to contain JSON encoded data for all of your sensors.\n\n```console\n$ adafruit-io client feeds help\nUsage: adafruit-io client feeds \u003caction\u003e\n\nActions:\n  all      All feeds for current user\n  create   Create a new Feed\n  destroy  Delete an existing Feed\n  get      Get feed by ID, Feed key, or Feed Name\n  update   Update properties of an existing Feed\n  replace  Replace an existing Feed\n  watch    Listen for new values\n  help     Show help\n```\n\n**Example:** List all feeds for your user\n```console\n$ adafruit-io client feeds all\n[info] Success\n[ { id: 1000,\n    key: 'frontdoor',\n    name: 'frontdoor',\n    description: '',\n    unit_type: null,\n    unit_symbol: null,\n    last_value: 'open',\n    status: 'offline',\n    visibility: 'private',\n    enabled: true,\n    license: null,\n    group_id: null,\n    created_at: '2015-08-28T17:13:12.516Z',\n    updated_at: '2015-09-21T17:20:04.630Z' } ]\n```\n\nSome commands will expect paramaters, so you can also view help on each command. Let's\ntake a look at the parameters expected by `update`.\n\n```console\n$ adafruit-io client feeds update help\nUsage: adafruit-io client feeds update \u003cid\u003e [options]\n\nParameters:\n  id    ID, key, or name of feed to use\n  help  Show help\n\nOptions:\n  -j, --json  JSON output\n```\n\n**Example:** Update `frontdoor` feed name to be `Front`\n\n```console\n$ adafruit-io client feeds update frontdoor\n? feed.name (optional): Front\n? feed.key (optional):\n? feed.description (optional):\n? feed.unit_type (optional):\n? feed.unit_symbol (optional):\n? feed.visibility (optional):\n? feed.license (optional):\n? feed.group_id (optional):\n[info] Success\n{ id: 1000,\n  key: 'frontdoor',\n  name: 'Front',\n  description: '',\n  unit_type: '',\n  unit_symbol: '',\n  last_value: 'open',\n  status: 'offline',\n  visibility: 'private',\n  enabled: true,\n  license: null,\n  group_id: null,\n  created_at: '2015-08-28T17:13:12.516Z',\n  updated_at: '2015-09-21T21:12:37.958Z' }\n```\n\nYou can also listen for realtime changes to your feeds by using the `watch` command.\n\n**Example:** Listen for changes to the `frontdoor` feed\n```console\n$ adafruit-io client feeds watch door\n[info] Feeds -\u003e Front\n{ id: 1000,\n  key: 'frontdoor',\n  name: 'Front',\n  description: '',\n  unit_type: '',\n  unit_symbol: '',\n  last_value: 'closed',\n  status: 'offline',\n  visibility: 'private',\n  user_id: 5,\n  created_at: '2015-08-28T17:13:12.516Z',\n  updated_at: '2015-09-21T21:12:37.958Z',\n  mode: null,\n  enabled: true,\n  fixed: false,\n  last_value_at: '2015-09-21T15:10:34.048Z',\n  license: null,\n  group_id: null,\n  feed_alias: null,\n  recorded: 'just now',\n  last_geo: { lat: null, lon: null, ele: null }\n}\n```\n\nAll operations can also output raw JSON so they can be piped to tools like [jq](https://stedolan.github.io/jq/)\nfor processing incoming data.\n\n**Example:** Get all feeds as JSON, and pipe the output to [jq](https://stedolan.github.io/jq/)\nto extract the feed names.\n```console\n$ adafruit-io client feeds all --json | jq '.[] | .name' --raw-output\nFront\ntemperature\nbattery\nfan\ndoor\n```\n\n**Example:** Watch the `door` feed for changes, output new values as JSON,\nand pipe the output to [jq](https://stedolan.github.io/jq/).\n```console\n$ adafruit-io client feeds watch door --json | jq .last_value --raw-output\nopen\nclosed\nopen\n```\n\n#### Data\n\nData represents the actual stored data sent to Adafruit IO feeds.\n\n```console\n$ adafruit-io client data help\nUsage: adafruit-io client data \u003caction\u003e\n\nActions:\n  all       All data for current feed\n  create    Create new Data\n  send      Create new Data and Feed\n  receive   Receive data?\n  previous  Previous Data in Queue\n  next      Next Data in Queue\n  last      Last Data in Queue\n  destroy   Delete existing Data\n  get       Returns data based on ID\n  update    Update properties of existing Data\n  replace   Replace existing Data\n  watch     Listen for new values\n  help      Show help\n```\n\nLet's look at the `all` operation as an example.\n\n```console\n$ adafruit-io client data all help\nUsage: adafruit-io client data all \u003cfeed_id\u003e\n\nParameters:\n  feed_id  ID, key, or name of feed\n  help     Show help\n```\n\n**Example:** View all feed data\n\n```console\n$ adafruit-io client data all door\n[info] Success\n[ { id: 122222,\n    value: 'open',\n    position: null,\n    feed_id: 1000,\n    group_id: null,\n    expiration: null,\n    lat: null,\n    lon: null,\n    ele: null,\n    completed_at: null,\n    created_at: '2015-09-21T15:10:34.048Z',\n    updated_at: '2015-09-21T15:10:34.048Z',\n    created_epoch: 1442848234.04861 } ]\n```\n\n#### Groups\n\nGroups allow you to update and retrieve multiple feeds with one request.\n\n```console\n$ adafruit-io client groups help\nUsage: adafruit-io client groups \u003caction\u003e\n\nActions:\n  all      All groups for current user\n  create   Create a new Group\n  destroy  Delete an existing Group\n  get      Returns Group based on ID\n  update   Update properties of an existing Group\n  replace  Replace an existing Group\n  watch    Listen for new values\n  help     Show help\n```\n**Example:** List all groups for your user\n```console\n$ adafruit-io client groups all\n[info] Success\n[ { id: 5,\n    name: 'weather',\n    key: 'weather',\n    description: null,\n    source: null,\n    properties: null,\n    source_keys: null,\n    created_at: '2015-07-14T22:41:48.898Z',\n    updated_at: '2015-07-14T22:41:48.898Z',\n    feeds: [ [Object], [Object] ] } ]\n```\n\n**Example:** Get the `weather` group as JSON and parse the feed names with [jq](https://stedolan.github.io/jq/)\n\n```console\n$ adafruit-io client groups get weather --json | jq '.feeds[] | .name' --raw-output\nhumidity\ntemp\n```\n\n## License\nCopyright (c) 2015 [Adafruit Industries](https://adafruit.com). Licensed under the [MIT license](/LICENSE?raw=true).\n\n[Adafruit](https://adafruit.com) invests time and resources providing this open source code. Please support Adafruit and open-source hardware by purchasing products from [Adafruit](https://adafruit.com).\n\n[1]: https://github.com/swagger-api/swagger-codegen\n[2]: https://io.adafruit.com/api/docs/\n[3]: https://github.com/swagger-api/swagger-codegen\n[4]: https://raw.githubusercontent.com/adafruit/io-swagger-templates\n[5]: https://nodejs.org\n[6]: https://io.adafruit.com\n[7]: https://learn.adafruit.com/adafruit-io/feeds\n[8]: https://learn.adafruit.com/adafruit-io/api-key\n[9]: https://npmjs.com\n[10]: https://learn.adafruit.com/adafruit-io/groups\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadafruit%2Fadafruit-io-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadafruit%2Fadafruit-io-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadafruit%2Fadafruit-io-node/lists"}