{"id":21331194,"url":"https://github.com/netbeast/bigfoot","last_synced_at":"2025-07-12T09:31:43.777Z","repository":{"id":21183044,"uuid":"91880860","full_name":"netbeast/bigfoot","owner":"netbeast","description":":feet: Quickly connect IoT devices with a great UX","archived":false,"fork":false,"pushed_at":"2023-01-23T19:28:34.000Z","size":1052,"stargazers_count":55,"open_issues_count":33,"forks_count":9,"subscribers_count":13,"default_branch":"master","last_synced_at":"2024-04-13T17:15:08.906Z","etag":null,"topics":["bigfoot","discovery","golang","iot","mqtt","node","python","ssdp","virtual-devices"],"latest_commit_sha":null,"homepage":"https://netbeast.github.io/bigfoot/","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/netbeast.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-05-20T10:08:02.000Z","updated_at":"2024-01-13T23:56:46.000Z","dependencies_parsed_at":"2023-02-13T02:20:23.700Z","dependency_job_id":null,"html_url":"https://github.com/netbeast/bigfoot","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netbeast%2Fbigfoot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netbeast%2Fbigfoot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netbeast%2Fbigfoot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netbeast%2Fbigfoot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netbeast","download_url":"https://codeload.github.com/netbeast/bigfoot/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225812458,"owners_count":17527990,"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":["bigfoot","discovery","golang","iot","mqtt","node","python","ssdp","virtual-devices"],"created_at":"2024-11-21T22:30:06.433Z","updated_at":"2024-11-21T22:30:07.002Z","avatar_url":"https://github.com/netbeast.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The Bigfoot project\n\nA toolbet for IoT software tools that work together.\n\n1. Discover devices automatically\n2. Have pre-made or many compatible user interfaces\n3. Simple, lightweight APIs\n\n## How does it work?\n\n![concept](assets/img/concept.png)\n\n# Get started\n\nThis guide will allow you to mock up your first connected device in less than a minute.\n\n1. **Download [Yeti Smart Home](https://getyeti.co/)**\n\nAny Bigfoot-compatible software would work. Bigfoot is currently fairly young, so\n this is the first end user software tool that supports it. \n You can also contribute IoT open source software as part of the \n [Netbeast Dashboard](https://github.com/netbeast/dashboard) to implement Bigfoot.\n\n2. **Choose a sample scaffold from the Bigfoot Project**.\n\n```\ngit clone https://github.com/netbeast/bigfoot-node\ncd bigfoot-node/samples/mock-device\nnpm install\nnpm start\n```\n\nThis is a sample in node.js. There are also samples in \n[bigfoot-golang](https://github.com/netbeast/bigfoot/golang) and \n[python](https://github.com/netbeast/bigfoot/python). We are looking for collaborators \nto create samples in other languages such as lua. Please send us a pull request!\n\n3. **Explore devices in Yeti**\n\nDone 👏🏽\n\n# Discovery\nAllow your device to be discovered by Yeti or any other Bigfoot client.\n\n```js\nvar Server = require('node-ssdp').Server\n\nserver = new Server({\n  sourcePort: 1900,\n  udn: 'my-unique-string-identidier', \n})\n\nserver.addUSN('bigfoot:all')\n\nserver.start()\n\nprocess.on('exit', function() {\n  server.stop() // advertise shutting down and stop listening\n})\n```\n\nCheck out the repo for examples in \n[golang](https://github.com/netbeast/bigfoot/golang), \n[python](https://github.com/netbeast/bigfoot/python) or other languages.\n\nCongratulations, your device is alive!\n\n![found](assets/img/found.png)\n![values](assets/img/json-tree.png)\n\nAt the right you have the bare values of your device. It still has no \nfunctionality, so it will fail when you try to control it. \n\nLet's keep learning...\n\n### Ping\n\nThis is intended to be the most lightweight method to check that connectivity \nto your accessory works. If you implement an interface through HTTP \n\\(as described in [skills](/skills.md)\\) we'd only need to specify the port \nwhere the service is running as the **location** parameter:\n\n```js\nconst Ssdp = require('node-ssdp')\nconst express = require('express')\nconst app = express()\n\n// respond with \"hello world\" when a GET request is made to the homepage\napp.get('/', function (req, res) {\n  res.send('hello world')\n})\n\nconst httpServer = app.listen(3000, function () {\n  const addr = httpServer.address().address\n  const port = httpServer.address().port\n  console.log('👾  Bigfoor ping sample started on %s:%s', addr, port)\n\n  ssdpServer = new Ssdp.Server({\n    location: `${addr}:${port}`,\n    sourcePort: 1900,\n  })\n  ssdpServer.addUSN('bigfoot:all')\n  ssdpServer.start()\n})\n\nprocess.on('exit', function() {\n  ssdpServer.stop() // advertise shutting down and stop listening\n  app.stop() // close express server\n})\n```\n\nAs you'd notice already, our device is still pretty dumb. We can only see it \nappears in our Yeti \\(Bigfoot compatible\\) device. This is because we had not \nspecified any skill or topic that it can work as. So let's move on now.\n\n# Skills\nWith skills we plan to refer the capabilities of what an accessory can do. For example, the simplest\ninterface we can implement is a webview for Bigfoot compatible software:\n\n```js\n// node/samples/webapp\nconst Ssdp = require('node-ssdp')\nconst express = require('express')\nconst ip = require('ip')\nconst app = express()\n\n// Serve a web application to use as user interface or show data\napp.use(express.static('public'))\n\nconst httpServer = app.listen(3000, function () {\n  const addr = httpServer.address().address\n  const port = httpServer.address().port\n  console.log('👾 Bigfoot webapp example started on %s:%s', addr, port)\n\n  ssdpServer = new Ssdp.Server({\n    location: `http://${ip.address()}:${port}`,\n    udn: 'Bigfoot_very-unique-bigfoot',\n    sourcePort: 1900,\n  })\n  ssdpServer.addUSN('bigfoot:web')\n  ssdpServer.start()\n})\n\nprocess.on('exit', function() {\n  ssdpServer.stop() // advertise shutting down and stop listening\n  app.stop() // close express server\n})\n```\n\nAfter discovery or a request for your skills descriptor you must be able to \ncommunicate the things you are able to do, and let the other parties be aware \nof them. Skills are grouped in _topics_, so when you declare a topic every \nother Bigfoot compatible machine understands how to communicate with it \nimmediately.\n\nTo declare an interface you'd only need to specify the topic on the USN:\n\n\n```js\nssdpServer.addUSN('bigfoot:bulb')\n// or \nssdpServer.addUSN('bigfoot:app')\n```\n\nAnd Bigfoot compatible devices are going to interpret it as different devices.\n\n### Available topics\n* `App`: exposes an app through a webserver, so the developer can implement its own interface\n* `Bridge`: a device that can find and talk to other devices\n* `Bulb`: to control lightning systems\n* `Music` : things that can consume \n* `Thermostat`: a heat / cold system\n* `Switch`: a plug or system with two states \\(on/off\\)\n* `Sensor`: an accessory with a read-only state, with keys and values to display\n\n## Implementing a topic\n\nTo understand Bigfoot messages you must only implement a protocol to listen to \nthe primitives and then specify it under `location`. The switch topic is the \nsimplest because you only have to understand `ON / OFF` set requests and to \nreturn the state. This will be done by HTTP POST and GET methods respectively.\n\n```js\n// node/samples/mock-device\nconst Ssdp = require('node-ssdp')\nconst express = require('express')\nvar bodyParser = require('body-parser')\nconst ip = require('ip')\nconst app = express()\n\nlet state = {\n  power: 1,\n  color: '#ffff00',\n  brightness: 80,\n  temperature: 50,\n}\n\napp.use(bodyParser.json())\n\napp.get('/', function (req, res) {\n  // Here you can return the switch state\n  console.log('\\n State requested:')\n  console.log(state)\n  res.json(state)\n})\n\napp.post('/', function (req, res) {\n  // Maybe perform some validation, change any device internal handling and then\n  // return back the state\n  state = req.body.state || state\n  console.log('\\n State changed:')\n  console.log(state)\n  res.json(state)\n})\n\nconst httpServer = app.listen(3000, function () {\n  const addr = httpServer.address().address\n  const port = httpServer.address().port\n  console.log('👾 Bigfoot device mock started on %s:%s', addr, port)\n\n  ssdpServer = new Ssdp.Server({\n    suppressRootDeviceAdvertisements: true,\n    location: `http://${ip.address()}:${port}`,\n    sourcePort: 1900,\n  })\n  ssdpServer.addUSN('bigfoot:bulb')\n  ssdpServer.start()\n})\n\nprocess.on('exit', function() {\n  ssdpServer.stop() // advertise shutting down and stop listening\n  app.stop() // close express server\n})\n```\n\n**Topics** stand for a _kind_ of device and groups a set of variables or dimensions\n to be used. It is a shortcut for the **skills of an accessory**. For example if \n the topic of your thing is _light_ or _bulb_ the rest of the parties will \n immediately know that you must support a certain **state**.\n \n ### State\n \n\u003e Said of accessory values that can change without necessary user input. They reflect the nature of the appliance;\nWhether a bulb is on or off, a thermometer reads 30ºC or a movement sensor detects presence. \n\n\n```js\n/* @flow */\nexport type BulbState = {\n  power: 0 | 1,\n  brightness: number, // percentage 0-100\n  hue?: number, // degrees 0-360\n  saturation?: number, // percentage 0-100\n  color?: string, // hex conversion of the values above\n}\n```\n\n\\*\\_ [Flow](https://flow.org/) is used to describe data types and interfaces \nthroughout the codebase\n\nThese are the topics supported by Netbeast Dashboard so far:\n\n```js\n/* @flow */\nexport type BulbState = {\n  power: 0 | 1,\n  brightness: number, // percentage 0-100\n  hue?: number, // degrees 0-360\n  saturation?: number, // percentage 0-100\n  color?: string, // hex conversion of the values above\n}\n\nexport type SwitchState = { power: PowerState }\n\nexport type MusicState = {\n  status: 'playing' | 'paused',\n  volume: number, // Not sure still that this is a percentage\n  track: Url,\n  position?: number,\n  playlist?: Array\u003cObject\u003e,\n  // rest to be defined\n}\n\nexport type ThermostatState = {\n  power: 0 | 1,\n  temperature: number,\n  units: 'celsius', 'farenheit',\n  mode?: string,\n}\n```\n\n## Accessory properties\n\u003e Accessory values that require user input through a software client to change, or simply don't. This can be true for the accessory name, icon, label, room they belong, etc. The device MAC address or unique ID are typical immutable properties.\n\n### Changing the accessory name\nBy accessing the route `/accessory`, it should return all its qualities (both properties and state). For instance, this is\nhow Yeti serializes a Philips Hue bulb:\n\n```json\n    {\n      \"id\": \"[UNIQUE IMMUTABLE STRING]\",\n      \"name\": \"Front Lamp\",\n      \"topic\": \"Bulb\",\n      \"brand\": \"PhilipsHue\",\n      \"room_label\": \"Bedroom\",\n      \"bridge\": {\n        \"id\": \"[UNIQUE IMMUTABLE STRING]\",\n        \"ip\": \"192.168.1.101:80\",\n        \"userId\": \"[SECRET UNIQUE STRING]\"\n      },\n      \"state\": {\n        \"brightness\": 98,\n        \"color\": \"#f90025\",\n        \"colormode\": \"hue\",\n        \"power\": 0,\n        \"temperature\": 6535.9477124183\n      }\n   }\n```\n\nIf a Bigfoot accessory comes with a certain name, that's what will be portrayed in Yeti Smart Home,\nor what should be displayed in other clients. By implementing both `GET` and `POST` at the route\n`/accessory` you will have an appliance with a custom name, that is synced across clients.\n\nYou can add a \"bigfoot\" field with information about the supported protocols and versioning:\n\n```json\n\"bigfoot\": {\n  \"version\": \"0.1.0\",\n  \"network_ssid\": \"netbeast\",\n  \"network_pass\": [SECRET STRING]\n}\n```\n\n## Create a bridge\nYou can use special topics as `app` or `bridge` to connect with accessories that \nare outside current compatible protocols with the target Bigfoot client (i.e. Yeti)\n\n🚧 This section is in construction\n\n## Roadmap\n\n* [x] Define the scope of the project\n* [x] [Website](https://netbeast.github.io/bigfoot/)\n* [x] [Open channels for collaborators](https://netbeast-community.slack.com/signup)\n* [ ] Write strategies\n  * [x] Get Started\n  * [x] Discovery\n  * [x] Ping\n  * [x] State Mutations\n  * [ ] Properties `/accessory`\n  * [ ] Pairing devices\n  * [ ] Reactive events\n  * [ ] Notifications\n* [ ] Node.js \n  * [x] Code samples\n  * [x] Working samples with virtual devices\n  * [x] Working samples with real devices\n* [ ] Go\n  * [x] Code samples\n* [ ] Python\n  * [x] Code samples\n\n## But you are still offering a protocol?\n\nNot at all. Bigfoot project aims to gather a set of strategies over existing \nprotocols and industry standards to make it easier for developers and \nmanufacturers to create IoT experiences together. As React brought us that to \nrepresentation interfaces, Bigfoot wants you to be able to create React-like \nhardware responses in a network environment with a set of simple and functional \nAPIs.\n\nBigfoot _topics_ is a suggested data structure that works out of the box with \nother tools in the belt. Because, you know, we need things working together :) \n\nAnyway, those _topics_ are borrowed from many other smart home devices, IoT \nservices and other established protocols. We are going to build _translators_ \nso you can use this schema as a middleware utility. But this is \n**not opinionated** and completely optional. As a matter of fact they will have \na `raw` method alternative to access all the params obscured by any tools, in \ncase you want access to the internals of the things you are working with.\n\n# Contributing\n\nBigfoot is an Open Source Project. This means that:\n\n\u003e Individuals making significant and valuable contributions are given \ncommit-access to the project to contribute as they see fit. This project is \nmore like an open wiki than a standard guarded open source project.\n\nRead the [Design Principles](PRINCIPLES.md) to understand the resoning behind our decision making.\nSee the [CONTRIBUTING.md](CONTRIBUTING.md) guide for more details.\n\n# Sponsors\n\nThis project is a reality today thanks to its contributors and sponsors. \nWe are proud to be part of the Toptal Open Source grant program, and compatible with Yeti\n\n\u003ca href=\"https://getyeti.co\" target=\"_blank\"\u003e\n   \u003cimg alt=\"works with yeti\" src=\"assets/img/works-with-yeti.png\" height=\"80px\" /\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://www.toptal.com/\" target=\"_blank\"\u003e\n  \u003cimg\n    alt=\"Toptal OSS\"\n    height=\"80px\"\n    src=\"https://bs-uploads.toptal.io/blackfish-uploads/branding_page/content/logo_example_file/logo_example/412/logo-ef4e3458c482141a5c668b5b0ef49a21.png\" /\u003e\n\u003c/a\u003e\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetbeast%2Fbigfoot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetbeast%2Fbigfoot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetbeast%2Fbigfoot/lists"}