InqPortal(u8* config, u16 size, u32 serialBaud)
This is used to instantiate an InqPortal object. Only one is allowed in a project. It has three parameters.
u8* config (optional) – This is where you can optionally supply an address of a C++ struct containing parameters that you wish to be persisted between system boots.
u16 size (required if config is defined) – This is the size of your custom C++ struct.
u32 serialBaud (optional) – Arduino IDE Serial Monitor baud rate (default = 115200)
Usage w/o params Usage w/ params
bool autoSend(u32 interval, bool sendAll)
When published variables (defined by using publishRO/publishRW) are changed by the clients (Admin or your custom pages) they are changed in the Sketch and all other instances of clients immediately. Published variables changed by Sketch logic must be checked by autoSend() periodically. There are two parameters.
u32 interval (required) – The time interval in milliseconds that autoSend() checks the published variables.
bool sendAll (optional) – At each interval, InqPortal will send all published variables every time. If set to false (default), only published variables that have changed will be sent. The default is false to save processing time and WiFi bandwidth. Set to to true for cases like supplying data required to populate UI that must have a periodic feed (ie Histogram).
Notes
- If autoSend() is not explicitly called by the Sketch, InqPortal will call it with autoSend(1000, false); when begin() is called. To override these defaults, simply call it before calling the begin() method.
- autoSend() is a convenience method for beginners and/or for projects with low bandwidth requirements. ie say a Weather station where updates to the UI might be in minutes or even more.
- The interval can be set more often when wanting a more responsive UI at the expense of higher processing and WiFi bandwidth. It can also be set to a longer interval when responsiveness is not that important. ie say the Weather station example.
- For advanced and/or extremely high data rates (say less than 100 milliseconds) you can set the interval to zero which turns off autoSend() functionality. In this situation, the Sketch coding must explicitly send out all changes desired explicitly. (see sendAll, sendChanged and send)
rc begin(const char* defaultSoftSSID, const char* defaultSoftPW,
const char* defaultStationSSID, const char* defaultStationPW,
const char* defaultHostName, u16 port)
This starts the InqPortal server and is generally placed toward the end of your setup() Sketch method. begin() has six optional parameters.
const char* defaultSoftSSID (optional) – Default SSID published from the built-in router. This is configurable by the Admin, so it does not have to be defined. If not defined, the SSID will default to InqPortal-Xxxxx. Either way, it can be overridden by the Admin at runtime.
const char* defaultSoftPW (optional) – Password used to access the built-in router. Can be set to NULL for an open access point. If a password is given it must contain at least 8 characters. This can be configured in the Admin at runtime.
const char* defaultStationSSID (optional) – SSID of your router. This is configurable by the Admin and can be hard-coded here for your use so you do not have to configure using the Admin.
const char* defaultStationPW (optional) – Password of your router. This is configurable by the Admin and can be hard-coded here for your use so you do not have to configure using the Admin.
const char* defaultHostName (optional) – When connected to your router, this will be the computer name given to your router so you can browse to the friendly name on your network. If not defined, the defaultSoftSSID will be used. Note: Some older routers do not support this DNS functionality.
u16 port (optional, defaults to 80) – This is the port that the web server will use. Normally browsers expect web servers to use port 80.
Returns – Return code – List is defined in Inq.h
void heading(const char* webID, const char* adminLbl)
The heading() method is merely a way of segregating a number of published variables as seen in the Admin and when creating a starter page. They have no other functional purpose. heading() has two parameters.
const char* webID (required) – This must be a unique ID of all headings and published variables. It must also start with a capital letter.
const char* adminLbl (required) – Any descriptive label of your choosing.
void LOG(u8 level, const char* format, …)
LOG messages are displayed in the Arduino IDE Serial Monitor and the InqPortal Admin Log tab. The log level is an identifier, category or classification… however, you prefer to think about it. The InqPortal Admin can set the range of LOG messages to process. If the level falls outside of the set range, the LOG message will be ignored. This saves processing power on your ESP8266 and network bandwidth and… human overload. The levels do not have to be unique. You can have many log messages with the same level. After the level parameter, the LOG method uses the same syntax as the standard C/C++ printf() method. If you are unfamiliar, with this method, please check out any Internet resource. LOG has two required parameters and as many additional parameters as you need.
u8 level (required) – A log level is simply an identifier for the current LOG message. Log level can have values between 1 and 255. InqPortal and supporting software uses values between 201 and 255. This leaves you and your project with values between 1 and 200.
Suggestion: Say you don’t need to see InqPortal messages. You could set the max level to 200. This would cause all InqPortal messages to be suppressed. Now with the remaining 1 to 200 you might use the higher numbers to set log messages that you always want to see (like data or hardware detected errors). You could then use the lower levels for things like messages that you would only care about under certain circumstances like trying to debug some problem. The lower the number, the more it might be display and a nuisance if it was always being processed. You could then set the Admin’s minimum log level above it and they too would be suppressed.
format (required) – See C/C++ printf method documentation.
… (optional) – Variable number of parameters as defined by the format parameter. See C/C++ printf method documentation.
Warning: Log, like the C/C++ printf has no error validation during compile time. A mismatch of “%” variables in format with parameters in the optional list often leads to a ESP8266 reboot.
bool onInterval(FuncInterval funcInterval, u32 interval, void* tag)
This is used to set up a recurring callback. Your funcInterval method will be called every interval milliseconds. This does not use interrupts and is at the same priority level as your Sketch loop() method. It does not require any kind of thread safe coding techniques or have duration limitations like interrupts. It is commonly millisecond accurate, however lower-level (WiFi and others) have precedence. Also, if your loop() or other onInterval callbacks are using the CPU, it will not be exactly on schedule.
This helps organize your Sketch code. The equivalent code to achieve the same functionality in your Sketch would tend to clutter your code. This also segregates the logic instead of being some convoluted if-else tree within a very long loop() method. The interval can also be modified from within the callback or from other places in your Sketch.
The same method (onInterval) can be called with the same funcInterval callback to change the interval or tag. In this case, funcInterval is being used as an ID to identify the interval you wish to modify.
onInterval has three parameters:
FuncInterval funcInterval (required) – This is your supplied method that will be called every interval. It has a prototype of: typedef void (*FuncInterval)(void* tag);
u32 interval (required) – This is the interval for the scheduled callback in milliseconds. It also has two constants that can be used from within the callback or from other locations in your Sketch.
- PAUSE – This causes the interval to be paused, but kept. It will remain paused until you call onInterval again with a new interval.
- DELETE – It is possible to delete the instance of an interval altogether. Be aware that creating and deleting many intervals can cause memory fragmentation. Consider using PAUSE.
void* tag (optional) – This is purely for your references purposes. It will be passed to the callback.
void publishRO(<multiple versions>), void publishRW(<multiple versions>)
- void publishRO(const char* webID, float* address, const char* adminLbl, float(*get)())
- void publishRW(const char* webID, float* address, const char* adminLbl, float(*get)(), void(*set)(float))
All other numeric types have the same exact prototypes as the two above… just change float to s8, u8, s16, u16, s32, u32, float, or double. Just using one of the valid types of variables will select the correct C++ overloaded method.
The character buffer versions must be handled differently. InqPortal must know the total size of the character array. Note the addition of the third parameter length.
- void publishRO(const char* webID, char* address, u16 length, const char* adminLbl, char*(*get)())
- void publishRW(const char* webID, char* address, u16 length, const char* adminLbl, char*(*get)(), void(*set)(char*))
The publishRO()/publishRW() series of methods allows you to publish one of your Sketch variables so that browser clients can view and/or change them. The only difference in the above versions is the type of variable it works with. These are the only ones supported. They have the following parameters.
const char* webID (required) – This parameter will be the web client alias ID of the variable when published to your clients. The browser pages will reference this id. Simply setting an HTML element’s id to this will typically permit the browser to display and/or update the Sketch variable without coding on your part.
<type>* address (required) – This parameter is a pointer to your Sketch variable address. Typically this is achieved by simply prefixing your variable with an ampersand &. In the case of a character array, it is simply the variable. <type> can be an s8, u8, s16, u16, s32, u32, float, double, or char[].
const char* adminLbl – (optional) This parameter is to supply a friendly description label that will be placed on the InqPortal Admin App tab. This parameter will also populate a label on any pages using the Create Starter Page feature.
<function for type>get– (optional) This parameter permits you to supply a callback function for your variable. Each type of variable has a different function prototype (described below). If you supply a callback function, InqPortal will call your callback expecting you to return a value of the proper type. This allows you to generate the value by request of a client versus generating and sending it by Sketch side logic.
typedef s8 (*get)();
typedef u8 (*get)();
typedef s16 (*get)();
typedef u16 (*get)();
typedef s32 (*get)();
typedef u32 (*get)();
typedef float (*get)();
typedef double (*get)();
typedef char* (*get)();<function for type>set– (optional) This parameter permits you to supply a callback function for your variable. Each type of variable has a different function prototype (described below). Supplying a NULL (default) will cause InqPortal to accept all proposed values. If you supply a callback function, InqPortal will call your callback expecting you to set your variable. The main purpose is to allow you to validate the incoming value from the client and adjust or refuse the value. Simply setting the address‘d variable with the validated response desired will be returned to the client.
typedef void (*set)(s8);
typedef void (*set)(u8);
typedef void (*set)(s16);
typedef void (*set)(u16);
typedef void (*set)(s32);
typedef void (*set)(u32);
typedef void (*set)(float);
typedef void (*set)(double);
typedef void (*set)(char*);void saveConfig()
This is used to save your custom persisted data. It is not necessary to call this if you use the autoSend option above. You must use saveConfig() if you set autoSend(0); You use this any time a variable in your custom struct is changed.
bool send(const char* format, …)
This is used to send your data to your browser clients. It uses a variable number of parameters. If your programming background include C/C++/C#, you might recognize this parameter signature. It is similar to the Serial.printf() method. send() uses a similar formatting scheme to printf() and has the same benefits and pitfalls as the printf() method. The number and types of parameters you must supply after the format parameter is defined by what you have specified in the format string.
const char* format (required) – This is a special string of characters that will specify what parameters are expected. Any conflict between format and the parameter list often causes a reboot of the ESP8266… just like printf() would. Here are the list of reserved characters. Any other characters are ignored and no parameter is expected.
- [ – Open square brace. Signifies the beginning of an array. No parameter is expected.
- ] – Closed square brace. Signifies the end of an array. No parameter is expected.
- l – Lowercase L. Each value sent to the browsers must have a label to define the value being sent. Therefore each value being sent will have two letters in the format string and two parameters in the following list. The first one will always be this “l”. The next parameter expected in the list must be a string. It also must start with a capital letter.
- d – Lowercase D. This indicates the next parameter must be a signed integer. (char, integer, long, s8, s16, s32)
- u – Lowercase U. This indicates the next parameter must be an unsigned integer. (byte, unsigned integer, unsigned long, u8, u16, u32)
- s – Lowercase S. This indicates the next parameter must be a character array.
- f – Lowercase F. This indicates the next parameter must be a floating point number. (float)
- e – Lowercase E, This indicates the next parameter must be a double precision, floating point number. (double)
Returns – false if a label uses a lowercase first letter, otherwise it returns true.
Examples – These will work.
- send(“ls”, “Kilroy”, “… was here!”);
- send(“l=s,l=e”, “Label”, “This is a message”, “PI”, atan(1.0) * 4.0); // If it helps your readability, you can use this. The = and , characters are ignored.
- send(“lslf”, “Label”, “This is a message”, “PI”, atan(1.0) * 4.0); // This is the same thing.
Failures – These will fail in different ways. Sometimes they’ll just not show up at the client side, sometimes they’ll reset the ESP8266. In other words, you just have to be careful with the syntax and recognize that if you just added a send() and it breaks your program, it was likely one of these type of errors that caused it.
- send(“lsld”, “O”, “K!”); // More parameters defined in format than are present in the list.
- send(“lsls”, “O”, “K!”, “PI”, 3.14159); // Second parameter pair is expecting a value that will be a string. This line is providing a float in the list.
void sendAll()
sendAll() sends all published variables to the client.
void sendChanged()
sendChanged() sends only published variables that have been changed.