Prerequisite: Project Settings
Second prerequisite: Also, we assume you have done some Arduino programming and are familiar with how to compile and view output via the Serial Monitor.
In this series of posts, we will start with the most trivial InqPortal application and flesh it out with most all of the basic features. The images below will only show the pertinent code, but this same FirstPortal project is included in the Examples for InqPortal… complete with full comments and links to details on this website. By the end of this post, we will be able to connect to our FirstPortal server, and configure it to most routers. Starting with a New project, add the three following lines to your Sketch.
It doesn’t get much simpler than this. Adding the include file brings in the InqPortal library software. The second line creates the InqPortal server object and the third line (begin() statement) starts the server. Some discussion about the begin() statement will be helpful here. All parameters for the begin() statement are optional. We show the first four here. The first (“FirstPortal“) is defining the default SSID for our server. It will also be our ESP8266 server’s default Host Name (more about this later). The second parameter is the default password for our server. Setting it to NULL, just says its an open network that anyone can get to without a password. These first two parameters are what permits you to connect directly to your FirstPortal server as if it was a router. The third and fourth parameters are to permit your FirstPortal server to connect to your local area network. All these values can be overridden in your FirstPortal Admin (more about this in a moment).
Best Practices – While developing your project, you typically won’t want to constantly configure your server in the Admin, so you’ll want to populate these first four parameters in code. If the project is a one-off just for you, you may also want to set these parameters. However, once you are ready to deploy your project to your customers you may want to clear some or all of these parameters in your code and have your customers configure them for their own local area network via the Admin. Many commercial IoT devices are configured in this way by connecting directly to the device’s SSID via some computer or smart phone and configuring it for their home’s router. InqPortal Admin has been optimized to work just as well on a cell phone as your 27″ desktop computer screen.
Now… connect your ESP8266 via a USB cable to your development machine, open your Serial Monitor, set the baud rate to 115200 and compile the project. Once it starts, you’ll see the following output. For those used to development in the Arduino IDE, you might have noticed, you do not need to setup the Serial interface. InqPortal controls this and sets the default baud rate to 115200. As you’ll see later on, you’ll be able to watch logging information in the Serial Monitor as well as the InqPortal Admin remotely from any browser.
Note: The ESP8266 processors are faster than Arduino boards and often the Serial Monitor won’t connect fast enough to catch all of InqPortal‘s output. If this is the case, you can simply press the reset button on your board.
As can been seen in the Serial Monitor, InqPortal outputs a significant amount of information. At the top, you’ll see InqPortal‘s version number and some important information about your specific ESP8266 board and how you have it configured. If you have configured it as was suggested in the Project Settings. There are several key points we want to talk about. The File System shows it has started and the size of the hard disk (~ 3MB). Once you load files in to the file system, you’ll also see a list of files here. The second arrow highlights what you need to do if you want to connect to your FirstPortal server by connecting to its SSID. Likewise the third arrow highlights that it has successfully connected to your configured router and that you can browse to either the IP address OR in some cases can use the friendly host name for your server. Note: Some older routers (I have at least one) do not support using this host name. If you can’t reach with the friendly name, try using the IP address in your browser.
More on Built-In and LAN Access Points
If you have any smart devices, you probably recognize what’s going on here. In my house I have Smart Plugs, Web Cams, TVs and even a vacuum cleaner that uses this methodology. It is quite possible these products are using an ESP8266 processor to provide this functionality. The ESP8266 processor has the ability to simultaneously behave like a router (Built-In Access Point) and also connect to your home router (LAN Access Point). This allows you, as the developer, to build an application that can connect to anyone’s home router. No more hard coding the credentials in your Sketches.
Built-In Access Point
The Built-In Access Point is the feature of InqPortal that is acting like a router. You can connect any WiFi enabled device to it as if it were a router. Open (say…) your laptop’s WiFi connections and find the SSID of FirstPortal. As can be seen, configuring FirstPortal in the Sketch results in the Serial Monitor output showing the Access Point and your laptop’s showing it is available as a WiFi Access Point.
Connect to it. On some devices, like Android, it will complain that there is no Internet. Just tell it to keep connected. Now you can open your browser and browse to the network address 10.10.10.10/admin.html. When connecting directly to your server, the server address will always be 10.10.10.10 for all InqPortal servers. There is no conflict with multiple InqPortal devices in the same area as each is its own network and 10.10.10.10 is always unique on that network. You will see the following page.
The above shows that we have connected to our InqPortal Admin, and the first two fields configure this Built-In Access Point. You can change the SSID and/or Password. Obviously, if you change either one of these and click the Update button, you’ll be disconnected and you’ll have to find the new WiFi connection with your laptop and/or give it the new password. In this example, we have set the password to NULL in the Sketch. This results in an open SSID as shown by the <open> tag in the Password field. Toward the middle of the Admin page, is a reminder of the 10.10.10.10 address and having the highlighted background indicates it is the current connection method for this browser.
Remember: Changes made in the Admin have precedence over defaults set in the Sketch. To clear the changes made in the Admin, you must reset your Arduino compiler menu item Tools / Erase Flash: “All Flash Contents”. The server will clear all Admin changes and return to the Sketch’s defaults.
Note: The most common purpose for the Built-In Access Point is so that you can configure your InqPortal project to connect to an available router. However, the Built-In connectivity isn’t just for configuring the LAN Access Point. Say you want to make a robot or a remote control car. You can control it directly from your smart phone when your out and about… No need to be near a router.
LAN Access Point
In the following example, our laptop is connected to our local area network. In my case Inqdom. We have browsed to our InqPortal server’s friendly hostname by using http://firstportal/admin.html. Some things to be aware if you are having trouble browsing to your InqPortal server.
- Some older routers simply won’t recognize your InqPortal server’s attempt to give the router its hostname. In that case, you’ll have to use the IP address given by the Serial Monitor or as displayed when you connect directly. The only other method that I can think of is to check for client connections in your router’s Admin software. I decided to just buy a new $25 portable router that I can take on the road and it accepts the hostname just fine.
- The first time you put the friendly name in a browser (Chrome, Edge, Firefox have been tested) you must include the http:// prefix. Otherwise, your browser thinks you want to do a search and your off to the races looking for firstportal on the Internet. I’ve noticed, after your browser has been told once, it’ll remember that is a destination. Note – It doesn’t show the prefix in the entry window.
The Admin shows your configured LAN Access Points. Yes, NEW in Version 5.0 InqPortal will store up to five LAN Access Points. The list of stored LAN Access Points will fall in the LAN Access Points section. The first one is always the one your InqPortal server is currently connected. Any other APs will be below it. Each has a button (the green button with the SSID name) in the left column. The button allows you to either connect to a different AP or to forget that AP. The input field in the right column is to change the password. The <secure> placeholder (in the above example) simply signifies the password is configured.
Also NEW in Version 5.0 is the ability to scan for Access Points. Using the image below, click InqPortal‘s menu and select the Scan for Access Points menu item. After a few seconds, you be presented with a list of other Access Points near you ranked by signal strength. Simply enter a valid password and your server will connect to that Access Point. Remember: If your browser is currently connected to your server via the old connection, you will be disconnected. Inq (Master of the obvious)
And one more NEW feature in version 5.0… InqPortal now supports a traveling project. When your server loses a connection, it will start searching for another in your list of configured Access Points. For instance say you have it configured for your home and work Access Points. You drive between with it either still powered or powered off. When you turn it back on, it will first search for the last AP it was connected to and if not found, it’ll look for the strongest configured entry… thus, automatically re-connecting to your home or work Access Points. How cool is that? Just like your smart phone.
Think: Be careful with configuring more than one AP in the same area. Remember, this is a server. If it’s not at the address you expect, it may have switched over to one of the other configured APs and gotten a different IP address from the new router. If your server gets disconnected, it may start an internal scan looking for another configured AP. Scanning does not assure you that it gets all the APs in the same area (Simply look at Window’s scan… sometimes it finds an AP. Sometimes it doesn’t). It might not find your primary (stronger) AP and fallback to your secondary. Once connected, it’ll stay with the secondary until you manually reconnect to your primary in the Admin OR the secondary router goes down… hopping back and forth.
LAN Host Name
The LAN Host Name is configurable by default in your Sketch as well as in the Admin. If you don’t configure it explicitly in the Sketch, it will default to the Built-In Access Point’s SSID. As shown above, the SSID is bracketed by <FirstPortal>. When you explicitly set it or configure it in the Admin, the <> are not shown.
In the next topic, we’ll start investigating some of the functionality of the InqPortal Admin… starting with adding a website.