Mongoose OS Wifi Provision Library

This library is now DEPRECATED in favor of the Wifi Captive Portal library I created for Mongoose OS. I will still accept PR and fix any bugs that are reported, but as this was my first ever lib for Mongoose OS, I now realize there was a lot of things probably not necessary in this lib. It should still work fine, and could be a great resource for those learning mos, but I will personally no longer be using this lib.

I strongly recommend taking a look at the WiFi Captive Portal library instead:

https://github.com/tripflex/wifi-captive-portal

Table of Contents

• Mongoose OS Wifi Provision Library
  • Table of Contents
  • Author
  • Overview
  • Why?
  • Features
  • Install/Use
  • Configurations
  • MJS
    • Examples
  • C
  • WiFi AP Need to Know
  • Roadmap
  • Suggestions and Code Review
  • License

Author

• Myles McNamara
• You!

Overview

This library is meant to help with provisioning (setting up) a device with WiFi Credentials, handling timeouts, max connection attempts, and letting you know whether or not the SSID/Password are correct.

Are you familiar with Mongoose OS and/or C programming?

Why?

I created this library because the default/core Mongoose OS WiFi library, which this library does depend on, does not do that good of a job when it comes to validating WiFi values that are set. If correct SSID and Password are set, it works great ... but as we all know with IoT devices, the end user will be the one setting it up, and chances are there will be multiple instances where the type the SSID or Password incorrectly, and there's no real easy way of dealing with that.

This library is my solution to this problem, not only solving it, but also adding additional features and handling for provisioning WiFi on a device.

Features

• MJS Support
• Test WiFi settings on device boot (when provision.wifi.boot.enable is set true)
• Testing on boot delay in seconds from provision.wifi.boot.delay when existing STA is connected (test is immediate when no existing STA connected)
• Fail test after total connection attempts (provision.wifi.attempts) and timeout provision.wifi.timeout (in seconds)
• Reconnects to existing station (if one was connected) after testing, when provision.wifi.reconnect is true (default: true)
• Test STA values are stored separate from WiFi Library STA values (in provision.wifi.sta - matches wifi lib structure)
• Automatically copy test STA values to wifi.sta after succesful connection test, when provision.wifi.success.copy is true (default: true)
• Disable AP on successful connection test provision.wifi.success.disable_ap when true (default: false)
• Reboot device on successful connection test provision.wifi.success.reboot when true (default: false)
• Reboot device on failed connection test provision.wifi.fail.reboot when true (default: false)
• Clear test STA values on success test provision.wifi.success.clear, or fail provision.wifi.fail.clear, when true (default: false)

Install/Use

To use this library in your Mongoose OS project, just add it under the libs in your mos.yml file:

  - origin: https://github.com/tripflex/provision-wifi

Configurations

This library adds a provision.wifi object to the mos configuration, with the following settings:

To see all of the available configurations please look at the mos.yml file. There are descriptions for each one of the settings.

MJS

api_provision_wifi.js

To use this library in your JavaScript files, make sure to load it at top of the file:

load('api_provision_wifi.js');

You will then have access to the ProvisionWiFi javascript object, with the following:

ProvisionWiFi.run();

• Run WiFi test based on values previously set in provision.wifi.sta (no callback)

ProvisionWiFi.Test.run( callback_fn, userdata );

• Run WiFi test based on values previously set in provision.wifi.sta, calling callback_fn after completion

ProvisionWiFi.Test.SSIDandPass( ssid, pass, callback_fn, userdata );

• Set provision.wifi.sta.ssid and provision.wifi.sta.pass, calling callback_fn after completion

ProvisionWiFi.onBoot.enable();

• Enable testing on device boot

ProvisionWiFi.onBoot.disable();

• Disable testing on device boot

ProvisionWiFi.STA.copy();

• Copy test station values to wifi.sta

ProvisionWiFi.STA.clear();

• Clear any existing station values in provision.wifi.sta

ProvisionWiFi.Results.success();

• Returns whether or not last test was a success

ProvisionWiFi.Results.ssid();

• Returns last SSID that was tested

ProvisionWiFi.Results.isRunning();

• Returns whether or not test is currently running

Callback Parameters If you use a callback function (ProvisionWiFi.Test.run or ProvisionWiFi.Test.SSIDandPass) the callback function will be passed 3 arguments: success, ssid, userdata

success will be an integer (since boolean not supported in mjs), 1 means succesful connection test, 0 means failed. ssid will be the SSID that was tested against userdata is whatever you passed in userdata

Examples

ProvisionWiFi.Test.SSIDandPass( "TestSSID", "TestPassword", function( success, ssid, userdata ){

    if( success ){
        // Hey look those credentials worked!
    } else {
        // Oh no, probably wrong/bad credentials!
    }

}, null );

ProvisionWiFi.Test.run( function( success, ssid, userdata ){

    if( success ){
        // Hey look those credentials worked!
    } else {
        // Oh no, probably wrong/bad credentials!
    }

}, null );

let lastTestSuccess = ProvisionWiFi.Results.success();
let lastTestSSID = ProvisionWiFi.Results.ssid();

if( lastTestSSID == 'TestSSID' && lastTestSuccess ){
    // Hey it worked!
} else {
    // Doh! Fail!
}

C

mgos_provision_wifi.h

WiFi AP Need to Know

• The AP should NOT go down while testing
• If provision.wifi.reconnect is true (default), there was an existing STA that was connected to before testing, and the test failed, the AP will go down for ~5 seconds or so while wifi is reinitialized.

Roadmap

• RPC Helper library (for making RPC calls to provision wifi)
• Your idea!
• Optimizing and reducing code base size

Suggestions and Code Review

PLEASE PLEASE if you're familiar with Mongoose OS (mos) or C programming in general, I need your help with this project!

My C and Mongoose OS experience is pretty limited (mos only month or two), but being a full time geek and developer I was able to figure out how to get this working (for most part) ... but i'm sure there's numerous ways to optimize the code base, or correct/better way to do things either in C or Mongoose OS specifically, and i'm completely open to constructive criticism!

Even if you're not 100% sure, neither am I, so open up an issue and let's discuss it!

License

Apache 2.0