The Admin Settings tab is used to configure settings on your InqPortal server. The primary settings here are those to make connections to your InqPortal server. If you need help getting to the Admin, this Connecting section of the Tutorial can help you get attached and working in the Admin. The Settings tab also shows you the current status of several important system metrics. The tab is broken up into four sections below.
Built-in Access Point
This section is for changing your server’s configuration for devices that you want to make connections directly to your ESP8266 InqPortal as if it were a router. You can setup your server’s SSID and Password via the begin() method of the server within your Sketch. see (reference) or (tutorial). You would probably like to code these to identify what the server is doing… ie My Weather Station. You might want to code the password as well. If you leave the SSID blank, InqPortal will give it a default name of InqPortal-xxxxxx. The xxxxxx will be a unique identifier. This way if you fire up more than one at the same time, they’ll have different SSID’s exposed.
Once you have your server running, you can access the WiFi connections method of your browsing device… laptop, tablet, phone, etc and find the WiFi router with the SSID you defined in the begin() method. Connect to it with the proper credentials. Now… open up your favorite browser as long as it is Google Chrome, Microsoft Edge or Mozilla FireFox. Internet Explorer will not work and no others have been tested. I have seen users using Safari, but it has not been comprehensively validated. But, I look forward to any evaluations if you decide to risk it. – Inq
Browse to 10.10.10.10/Admin.html. The 10.10.10.10 is hard-coded into every InqPortal and is not configurable. If you have multiple InqPortal servers in your area, there is no conflict as this address is only available on the network SSID you are connected, so the 10.10.10.10 is always unique to that server. Once you get into the Admin on your server you can now make changes to any of the settings via the Settings tab.
You will see the SSID you defined or the default SSID given by InqPortal. If you defined a password in the Sketch, you will see the tag <secure> in the Password field. The password never comes out to the Admin. As in the above example, the password was set to NULL in the begin() method and thus shows the tag <open>… meaning no password is required to log onto this “router”. You can now change these values and hit the Enter key or the Update button.
Now for a few rules and things to think about…
- Passwords can be blank or if defined, they must have at least 8 characters. There are no requirements for numbers, capital letters or special characters.
- These changes are persisted immediately on sending. If you reboot they will be required the next time you connect to the potentially new SSID.
- If the SSID and Password are configured by the Admin and persisted, these persisted values have precedence over the values defined in the Sketch begin() method. If you forget the password…
- You can set the Arduino IDE Erase Flash: “All Flash Contents” and wipe all the Flash which includes the persisted area. This will then permit the Sketch defaults to be used.
- If you can get to the InqPortal Admin via your LAN Access Point connections, you can reconfigure the Built-In Access Point.
- I have many people that wonder why they lose connection when they hit the enter key. You’re not going to be one of those people, right! You have changed the SSID and/or the password. The connection you are communicating with your server has changed and is no longer valid. The server has no way to reach out and tell your laptop nor does your browser have any way to tell your laptop to connect to the new SSID with a new password. It requires human intervention.
- Recommendation – It is generally easier to iterate your development (add code/compile/test/add code/compile/test… etc) using a browser accessing your server via a LAN connection. I have seen a few laptops occasionally honor the Windows connect automatically checkbox option, but 99% of the time, they stubbornly wait for you to reconnect to your ESP8266 server even if the credentials are correct. The LAN version always re-syncs after booting and the Admin will automatically re-connect and continue where you left off when you hit the compile button.
LAN Access Points
If you are looking at the Admin, it obviously means you are already connected either through the Built-in Access Point connection or through an already established LAN Access Point connection. If the LAN Access Points section is shown you have at least one connection configured. If you don’t see it, you don’t have any configured. To get started configuring a LAN AP, you’ll need to scan to find those available around you.
Scanning for LAN Access Points
To get started adding a LAN AP, select the Scan for Access Points in the Admin menu. The process will take several seconds and return access points in your area.
The list of Access Points always shows the ones you have configured at the top and are identified by the green style button of the SSID name and the Password field will show either a <secure> or <open> tag to let you know how it is configured. The first one is always the one your InqPortal is currently connected. Others in the list are un-configured access points and they are listed in order of strength (strongest at the top). The second number in the label (if shown) is the WiFi channel that router uses. Now you can configure the desired access point by adding a password or if it is an open access point, simply delete the <not configured> tag and click the Update button. Your InqPortal server will start the connection process which usually takes several seconds.
Remember – If you are configuring through a connection on another LAN Access Point. You will be disconnected. Your device, say… your laptop is connected to the SSID of the router that the InqPortal was connected to. You’ll need to establish a connection to the new SSID if you want to reconnect to your InqPortal.
If you want to connect to another Access Point (instead of the first one) or if you want to forget the credentials of one, simply right click on the green button and select the desire option.
Failover and Auto Scanning
New in version 5 of InqPortal. If the LAN Access Point you are connected to goes down because the router was powered off or it simply went out of range, InqPortal will start an Access Point Scan and see if there are any routers within range that you have previously configured. If more than one exists, it will choose the strongest signal. It will then connect to it. If the original router comes back on-line InqPortal will not disconnect from the secondary and reconnect to the primary. This features allows InqPortal to act more like a Windows laptop or smart phone. As you travel, it will find the router you previously configured in that area. InqPortal will store up to five configurations.
Pitfalls
I’ve included some pitfalls in the following. When I first stumbled into them, I first assumed it was something wrong with InqPortal. Some were… and I fixed those bugs. However, many of them turned out to be issues with something else. There are a lot of moving parts when it comes to connecting to WiFi. It is especially challenging when the UI your using is connected to the connection you’re making the changes to. Kind of like picking yourself up by your boot straps. Some of them, I found ways around. Others required human patience and action.
- Public routers, like your favorite coffee hang-out or public library have free access and you certainly can connect your laptop and your InqPortal server to the SSID. But these public access points have peer-to-peer communications disabled. You won’t be able to reach your InqPortal from your laptop.
- It is very difficult to create a bullet-proof UI when it comes to configuring the LAN Access Points. You must realize that first and foremost that you are configuring the connections via a connection between your browser client Admin and your ESP8266. When the ESP8266 scans for available access points, it must disconnect from the Admin and sequentially go through all WiFi channels and see what access points are on those channels. After it completes the scan, it must reconnect your browser and Admin so it can display the results to you.
- The ESP8266 can only run one channel. If you are say… configuring LAN Access Points through a connection on the Built-In Access Point (SoftAP) and the LAN AP you are configuring is on another channel, the connection you are using must sever and be reconnected to your browser on the other channel. All transparently to you.
- The worse case is when you kill your computer’s connection to your ESP8266 server via selecting a new SSID in devices WiFi settings. Say… your reconnecting your computer back to your local area network router. Both the ESP8266 and your Admin client are left dangling in the wind. Without you putting the new address in the browser, it can’t get there. To give a transparent user experience hiding all these lost and recovered connections is certainly non-trivial.
- All routers have their own set of idiosyncrasies. We haven’t tested all of them.
- Point being – Sometimes you might have to hit the browser refresh button or pause and realize which router your InqPortal is currently connected to and which one your laptop is connected to and guess what? – You can’t get there from here.
Other Settings
LAN Host Name
When your InqPortal server connects to your router, it will give this host name to your router so that other devices on your local area network can connect to it by the friendly name. The host name can be configured in the Sketch begin() method or can be configure here in the Admin. If it has not been explicitly configured, a default name will be generated and be enclosed in <Lone_Wolf> as in this example. It will be based on the Built-In Access Point. Note: Although SSIDs can have space in them, Host Names can’t. The default name creator will replace spaces with underbars as in this example. Like above, there are pitfalls:
- The most common pitfall, I still do on a regular basis. You enter your cool application name either in the Sketch begin() method or in the Admin: SuperWidget and go to your browser and correctly type in SuperWidget/Admin.html expecting to see the Admin popup. Instead, you get a Google Search looking for SuperWidget. The Browser simply thinks you want to do a search. To correct this, add the prefix: http://SuperWidget/Admin.html. That will tell the browser it is an address… not a search string. The good thing is once you tell it once, they seem to remember it from then on. So you can go back to just typing in SuperWidget/MyPageOrAnother.html from then on. But… if you use more than one browser (I routinely test on Chrome, Edge and FireFox)… you have to tell each of them the first time.
- Some routers are not capable of this DNS capability. I know, because I have one. Usually these are older, commodity routers. I’d suggest you just get a new one. I got a little $25 travel router that has DNS and lots of other nice features. If that is not an option, you’ll have to use its IP address that you can get either from the Admin’s Information section (see below) or from your router’s administrative pages.
- Some routers hang on to these names longer than others. If you name it one thing and then change the name, and then immediately try to browse the the new server from say: http://Lone_Wolf/Admin.html to http://SuperWidget/Admin.html you might get a number of bad responses. I’ve seen some routers pick up the change immediately… others taking ten minutes or so and others far longer.
- Same thing goes if you set multiple InqPortal servers trying to give the same name. All bets are off which one you might get.
Log Level Range
InqPortal uses the LOG (see LOG Reference) method to output messages. It works the same way as using Serial.printf() method. The difference – It sends a diagnostic message to the Arduino IDE Serial Monitor and to the Log tab of the InqPortal Admin. It has one other advantage. It is possible to disable messages via the Log Level Range. You no longer have to delete or comment out debug messages and recompile. The first parameter of every LOG method is a Log Level ID. These can range between 1 and 255. You set any (or many) LOG messages to any value. Note: InqPortal uses 201 through 255. You can still use these, but you’ll see yours and InqPortals if they’re in the Log Level Range. And as you might expect, you can set the range of messages you want to log. The default is all: 1 through 255.
Information
Built-in Server Address – This is the address you will use if you have connected your device directly to the Built-in Access Point. You would then browse to any of your pages using this address, say… 10.10.10.10/MyPage.html. If your browser Admin is connected via this connection, the background will show a light green highlight. If it has been disconnected from this connection the background will have a pale red highlight.
LAN Server Address – This is the address your router’s DHCP assigned to your InqPortal server when it connected. This is the alternative address you can use if the LAN Host Name does not work for you. You would then browse to say… 192.168.100.98/MyPage.html. If your browser Admin is connected via this connection, the background will show a light green highlight as in this example. If it has been disconnected from this connection the background will have a pale red highlight.
Server Start Time – This will show you the time your server was booted. In earlier versions of InqPortal it would attempt to connect to an NTP server to get a baseline. This had a couple of disadvantages. (1) What if the server doesn’t have access to the Internet? and (2) Extra code space requirements. In this version, the Admin client does some handshaking with the server and this time shown is relative to the displaying device. It takes into account the clients time zone and Daylight Savings settings. It also works whether the server has access to the Internet or not. The one disadvantage is if you are viewing the Admin from two different devices, and those devices are not set accurately with some NTP server, then the Admins might show different start times.
Boot Count – As the name implies, this will show you how many times the server has been booted. Maybe you powered it off to moved it to its chosen spot. Or you had a power failure. This also can be used as one of the diagnostic tools of server health. If you are performing some unattended, long term testing, say… overnight. You might come back the next day and find this has been incremented once or worse… hundreds of times. You’ll instantly know… you have a problem.
Boot Reason – This is the system supplied reason for the last boot. The most common is External System for a powering up of the server, or you compiled and uploaded your binary via the Arduino IDE. You would also get this for a power failure. The second most common is Software/System restart which occurs when you upload your binary server code using the OTA feature. There are various other error conditions including Exception that you really don’t want to see.
Disk Size (bytes) – This gives the size of the Flash memory that has been set aside to be used as a hard disk to hold your web content like your Markup (html), style sheets (css), JavaScript (js) files and other resources like fonts, and images.
Files Use (bytes) – This will show how much space is currently being used by your uploaded files.
Fragmented (%) – This tells you how much of your disk is fragmented. This means how much space is being used by file fragments. There is a manual Defragment Disk option in the Admin menu. Normally, it should not be used until the system tells you, you need to run the option. Defragmentation is only necessary when the combined good file space and fragmented space is equal to the Disk Size. This only occurs when files are being added or updated. There is no need during normal web serving duties.
Loop Frequency (Hz) – On true computers that have real operating systems, there is the concept of CPU utilization. Everyone is familiar with it. On microprocessors, the MPU is always at 100%, so that metric has little value. However, there is the concept of how many cycles the Arduino coding loop() method gets called per second. When this number is high, there is very little going on with your Sketch, InqPortal and the low-level functions. As processes use more time, this number drops. It can be a good gauge of how the MPU is being used. As you can see in the above example, when idle, this number fluctuates around 130 kHz using the 80 Mhz clock speed. In the turbo 160 MHz speed, this number is about 270 kHz. There is a great deal of power available. Until this number gets below 1 Hz, your program should be fine. Below 1Hz starts getting into the area where the ESP8266’s Watch-Dogs might raise their ugly heads. Tracking this in InqPortal might help point you to bottlenecks in your logic when things start getting overloaded.
Free Memory (bytes) – This is memory used by your Sketch directly as well as by InqPortal and the lower level WiFi and file management subsystems. You will see it rise and fall as actions occur on your project. It is beyond the scope of this topic, but there are two issues that actively start eating this memory. These are Memory Leaks and Fragmentation. Developers on the low level libraries and InqPortal have expended great effort to eliminate these issues. Excessive memory usage can occur in minutes or it might take days. One of the most frustrating aspects of this type of bug is, it appears to happen randomly and can finally reboot at any place in your code. Tracking this in InqPortal might help point you to searching your code for potential leaks and fragmentation.
Supply Voltage (V) – From a server performance standpoint, monitoring this value might allow you to see a trend in the voltage that causes the processor to stop or reboot. Low voltage, either from a bad power supply, weakening battery or an overdraw of power from sensors and actuators running off your ESP8266 can all cause the processor to reboot. The nominal value is 3.3 volts. However, it might be difficult to rely on this value. We have seen multiple different boards showing a large range of voltages yet still work perfectly. One board might show a voltage number fluctuating around 2.9V while another hung off the same USB port may show numbers fluctuating around 3.7V. In other words, you’ll need to establish a baseline for each ESP8266. YMMV!
This entry may not be visible on your InqPortal Admin. It must be enabled by using adding the line ADC_MODE(ADC_VCC); to your Sketch. This is a standard method call from the ESP8266 code base. There is only one analog pin on ESP8266 boards. This command can only be included if you have no plans for the analog pin in your project. Using this line of code will cause the ESP8266 to take over the analog to digital converter to measure the incoming voltage. InqPortal will gather this value and allow you to monitor it from the browser based Admin.
Data Processed (bytes) – This is a basic statistic of your server since booting. This includes all data that the InqPortal processed including, HTTP requests for URLs/files, the output of serving those files, and Web Socket data coming and going.
Data Rate (bytes/sec) – This is another basic statistic. This is the rate of all incoming and outgoing data and is in bytes/second. It is the average over the last second of time.
Data Loss (bytes) – This is another diagnostic value of how much data was thrown away because the buffers were near full and any extra would cause an exception and reboot. Incoming WebSocket data will not affect this number nor will the receiving or serving of web content. Those sub-systems are self regulating and won’t overload the system. This only increments as a result of WebSocket output data that your server side application is sending. In other words, you’re sending too much data at too high of a rate. Nominally under idle conditions, the Data Rate (see above) is well below 100 bytes/second. We have see rates as high as 200,000 bytes/second run for days without data loss YMMV.
WebSockets – This is a tally of how many client applications are currently connected to your server. For performance reasons, we have decided to use WebSockets for communication between clients and servers. The ESP8266 has a hardware limit of five connections. We reserve one connection to always being available for uploading files, OTA and serving URLs/files. This leaves up to four simultaneous clients. This includes InqPortal Admins and any of your client UI applications that use the client-side InqPortal library (InqPortal.js). Thus the fraction shown on the Admin shows <number of Admins> / <total number of WebSocket connections> / <total allowed>.