{"id":13414312,"url":"https://github.com/tripflex/captive-portal-wifi-setup","last_synced_at":"2025-05-15T17:32:57.095Z","repository":{"id":147531739,"uuid":"174651347","full_name":"tripflex/captive-portal-wifi-setup","owner":"tripflex","description":"Mongoose OS WiFi Setup Library (Captive Portal)","archived":false,"fork":false,"pushed_at":"2020-11-27T22:12:25.000Z","size":28,"stargazers_count":3,"open_issues_count":1,"forks_count":5,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-07-31T21:52:53.119Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tripflex.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,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-03-09T05:12:48.000Z","updated_at":"2023-03-23T23:55:21.000Z","dependencies_parsed_at":"2024-01-13T17:13:36.650Z","dependency_job_id":"b2de2cdd-acfd-4607-ad08-55d109740e2b","html_url":"https://github.com/tripflex/captive-portal-wifi-setup","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/tripflex%2Fcaptive-portal-wifi-setup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripflex%2Fcaptive-portal-wifi-setup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripflex%2Fcaptive-portal-wifi-setup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tripflex%2Fcaptive-portal-wifi-setup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tripflex","download_url":"https://codeload.github.com/tripflex/captive-portal-wifi-setup/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254388347,"owners_count":22063034,"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":[],"created_at":"2024-07-30T21:00:18.758Z","updated_at":"2025-05-15T17:32:56.776Z","avatar_url":"https://github.com/tripflex.png","language":"C","funding_links":[],"categories":["Awesome Mongoose OS [![Awesome](https://awesome.re/badge.svg)](https://awesome.re)"],"sub_categories":["Community Libraries"],"readme":"# Mongoose OS WiFi Setup\n\n[![Gitter](https://badges.gitter.im/cesanta/mongoose-os.svg)](https://gitter.im/cesanta/mongoose-os?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge)\n\n- [Mongoose OS WiFi Setup](#mongoose-os-wifi-setup)\n  - [Captive Portal Stack](#captive-portal-stack)\n  - [Author](#author)\n  - [Features](#features)\n  - [Settings](#settings)\n      - [`cportal.setup.copy` Setting](#cportalsetupcopy-setting)\n      - [`cportal.setup.disable` Setting](#cportalsetupdisable-setting)\n      - [`cportal.setup.enable` Setting](#cportalsetupenable-setting)\n      - [`cportal.redirect_file` Setting](#cportalredirect_file-setting)\n  - [Installation/Usage](#installationusage)\n    - [Full Captive Portal Stack](#full-captive-portal-stack)\n    - [Only this library](#only-this-library)\n    - [Use specific branch of library](#use-specific-branch-of-library)\n  - [Required Libraries](#required-libraries)\n  - [How it works](#how-it-works)\n  - [Events](#events)\n    - [Handling/Triggering Events in mJS](#handlingtriggering-events-in-mjs)\n  - [Available Functions/Methods](#available-functionsmethods)\n    - [C Functions](#c-functions)\n    - [Usage in mJS](#usage-in-mjs)\n  - [Changelog](#changelog)\n  - [License](#license)\n\nThis library is for testing, saving, and setting up Mongoose OS device's WiFi.  The main feature of this library is the ability to test WiFi credentials, and then save or update them in the configuration.\n\n## Captive Portal Stack\n\nThis is the **WiFi Setup** library from the [Captive Portal WiFi Full Stack](https://github.com/tripflex/captive-portal-wifi-stack), a full stack (frontend web ui \u0026 backend handling) library for implementing a full Captive Portal WiFi with Mongoose OS\n\n## Author\nMyles McNamara ( https://smyl.es )\n\n## Features\n- Test WiFi SSID and Passwords\n- Automatically save SSID and Password after validating SSID and Password\n- Automatically disable AP after successful WiFi test\n- Automatically reboot the device after saving and successful test\n- Set which STA index to save configuration to `wifi.sta` `wifi.sta1` or `wifi.sta2`\n- Set custom timeout for testing connection and credentials (`30` seconds by default `cportal.setup.timeout`)\n- Mongoose OS successful, failed, and started test events\n- Callback for failed/successful test for use in `C` or `mJS`\n- Disable Captive Portal setting after successful test\n- Support for testing Enterprise WPA2 Networks\n- Support for enabling DNS-SD after successful test\n\n## Settings\nCheck the `mos.yml` file for latest settings, all settings listed below are defaults\n\n```yaml\n  - [ \"cportal.setup.copy\", \"i\", 0, {title: \"Copy SSID and Password to this STA ID after succesful test ( 0 - wifi.sta | 1 - wifi.sta1 | 2 - wifi.sta2 )\"}]\n  - [ \"cportal.setup.timeout\", \"i\", 30, {title: \"Timeout, in seconds, before considering a WiFi connection test as failed\"}]\n  - [ \"cportal.setup.disable\", \"i\", 2, {title: \"Action to perform after successful test and copy/save values -- 0 - do nothing, 1 - Disable AP (wifi.ap.enable), 2 - Disable AP and Captive Portal (cportal.enable)\"}]\n  - [ \"cportal.setup.enable\", \"i\", 0, {title: \"Settings to enable after successful test and copy/save values -- 0 - do nothing, 1 - Enable DNS SD (dns_sd.enable)\"}]\n  - [ \"cportal.setup.reboot\", \"i\", 0, {title: \"0 to disable, or value (in seconds) to wait and then reboot device, after successful test (and copy/save values)\"}]\n\n```\n#### `cportal.setup.copy` Setting\nSet this equal to the STA ID you want to save the values to (if you want to save them after successful test).  Use `-1` to disable saving after successful test.\n\n#### `cportal.setup.disable` Setting\nAction to perform after successful test and copy/save values (if not set to `0`)\n - `0` - Do Nothing\n - `1` - Disable AP `wifi.ap.enable`\n - `2` - Disable AP `wifi.ap.enable` and Captive Portal `cportal.enable`\n\n#### `cportal.setup.enable` Setting\nAction to perform after successful test and copy/save values (if not set to `0`)\n - `0` - Do Nothing\n - `1` - Enable DNS-SD `dns_sd.enable`\n\n#### `cportal.redirect_file` Setting\nThis setting if for if you want to use your own custom HTML file as the \"redirect\" file sent that includes a `meta` refresh tag.  This setting is optional, and when not defined, a dynamically generated response will be sent, that looks similar to this:\n\n## Installation/Usage\n\n### Full Captive Portal Stack\nIf you want all of the features this library was built for, you should install the [Captive Portal WiFi Stack](https://github.com/tripflex/captive-portal-wifi-stack) library instead of just this one:\n\nAdd this lib your `mos.yml` file under `libs:`\n\n```yaml\n  - origin: https://github.com/tripflex/captive-portal-wifi-stack\n```\n\n### Only this library\n\nAdd this lib your `mos.yml` file under `libs:`\n\n```yaml\n  - origin: https://github.com/tripflex/captive-portal-wifi-setup\n```\n\n### Use specific branch of library\nTo use a specific branch of this library (as example, `dev`), you need to specify the `version` below the library\n\n```yaml\n  - origin: https://github.com/tripflex/captive-portal-wifi-setup\n   version: dev\n```\n\n## Required Libraries\n*These libraries are already defined as dependencies of this library, and is just here for reference (you're probably already using these anyways)*\n- [wifi](https://github.com/mongoose-os-libs/wifi)\n  \n## How it works\nThis library adds `C` functions you can use to test wifi credentials (see below).  For a complete solution, use the Captive Portal WiFi Stack which adds easy methods for calling this (web ui, etc).\n\n## Events\n\n```C\n#define MGOS_CAPTIVE_PORTAL_WIFI_SETUP_EV_BASE MGOS_EVENT_BASE('C', 'P', 'S')\n\nenum mgos_wifi_captive_portal_event\n{\n    /**\n     * Fired when WiFi Setup/Config testing is Started\n     * \n     * ev_data: struct mgos_config_wifi_sta *sta\n     */\n    MGOS_CAPTIVE_PORTAL_WIFI_SETUP_TEST_START = MGOS_CAPTIVE_PORTAL_WIFI_SETUP_EV_BASE,\n    /**\n     * Fired when succesful connection test for Wifi\n     * \n     * ev_data: struct mgos_config_wifi_sta *sta\n     */\n    MGOS_CAPTIVE_PORTAL_WIFI_SETUP_TEST_SUCCESS,\n    /**\n     * Fired when failed connection test Wifi\n     * \n     * ev_data: struct mgos_config_wifi_sta *sta\n     */\n    MGOS_CAPTIVE_PORTAL_WIFI_SETUP_TEST_FAILED\n};\n```\n\n### Handling/Triggering Events in mJS\nYou can add event handling in mJS by adding this to one of your `.js` files:\n\n```javascript\nlet CaptivePortalWiFiSetup = {\n    START: Event.baseNumber(\"CPS\")\n};\n\nCaptivePortalWiFiSetup.SUCCESS = CaptivePortalWiFiSetup.START + 1;\nCaptivePortalWiFiSetup.FAILED = CaptivePortalWiFiSetup.START + 2;\n\nfunction CaptivePortalWiFiEvent(ev, evdata, arg) {\n    if (ev === CaptivePortalWiFiSetup.START) {\n      // Test started\n    } else if (ev === CaptivePortalWiFiSetup.SUCCESS) {\n      // Successful test\n    } else if (ev === CaptivePortalWiFiSetup.FAILED) {\n      // Failed test\n    }\n}\n\nEvent.addGroupHandler(CaptivePortalWiFiSetup.START, CaptivePortalWiFiEvent, null);\n```\n\n## Available Functions/Methods\n\n### C Functions\n```C\n/**\n * @brief Start WiFi Credential/Connection test for Standard OPEN/WEP/WPA2 networks\n * \n * @param ssid \n * @param pass \n * @param cb \n * @param userdata \n * @param user \n * @return true \n * @return false \n */\nbool mgos_captive_portal_wifi_setup_test(char *ssid, char *pass, wifi_setup_test_cb_t cb, void *userdata );\n```\n```C\n/**\n * @brief Start WiFi Credential/Connection test for ENTERPRISE WPA2 networks\n * \n * @param ssid \n * @param pass \n * @param user \n * @param cb \n * @param userdata \n * @return true \n * @return false \n */\nbool mgos_captive_portal_wifi_setup_test_ent(char *ssid, char *pass, char* user, wifi_setup_test_cb_t cb, void *userdata );\n```\n\nThe `mgos_captive_portal_wifi_setup_test` will return `true` if the test was started, `false` if it was not\n\nThe `wifi_setup_test_cb_t` is for a callback (optional) after a successful/failed wifi test.\n```C\ntypedef void (*wifi_setup_test_cb_t)(bool result, const char *ssid, const char* password, void *userdata);\n```\n\nIt will return the result `false` for failed `true` for success, the tested SSID, Password, and any userdata if you passed it when originally calling the function.\n\n### Usage in mJS\nTo keep library size to a minimum, no mjs file is included with this library, but you can easily call it using the built in **ffi** for mjs, like this:\n```javascript\nlet testWiFi = ffi('bool mgos_captive_portal_wifi_setup_test(char*,char*,void(*)(bool,char*,char*,userdata),userdata)')\ntestWiFi( \"My SSID\", \"somePassword\", function( success, ssid, pass, userdata){\n  print( 'Test Completed!');\n}, NULL );\n```\n\n## Changelog\n**1.0.3** (November 27, 2020)\n - Fixed `protocol` being set in `mgos_config_wifi_sta` (should only be set on ESP32 devices)\n\n**1.0.2** (June 24, 2019)\n - Fixed 'dicards const' error during build due to `mgos_config_wifi_sta` now using `const` - props @zernyu\n - Fixed setup failed event being called on successful test - props @pohy\n - Added `cportal.setup.enable` to enable settings after successful test\n\n**1.0.1** (March 10, 2019) \n - Added support for Enterprise Networks\n - Updated event base to `CPS`\n\n**1.0.0** (March 9, 2019)\n - Initial release\n\n## License\nApache 2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftripflex%2Fcaptive-portal-wifi-setup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftripflex%2Fcaptive-portal-wifi-setup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftripflex%2Fcaptive-portal-wifi-setup/lists"}