Basic Overview of Wattmon

This section will describe how the Wattmon works, right down from the hardware level till the higher levels such as creating graphs and exporting data.

Hardware Layer

Wattmon is an embedded system, running a microcontroller and having several different hardware buses:  RS-485, RS-232 and Onewire, along with several analog and digital inputs and outputs.  The system also has two network interfaces: Ethernet (10 mbit) and a USB Host port that supports certain cellular dongles over PPP.  The microcontroller is a PIC32 from Microchip which has 128kb of RAM and 512kb of flash on which the firmware resides.  A microSD card is required to run the scripts and log data, and the system won't work if the SD card is removed.  A real-time clock with backup battery ensures the system time stays up-to-date.

Firmware Layer

Wattmon runs is a custom operating system written in C and using the FreeRTOS task scheduler.  It has an interpreter that can process uPHP, our scripting language based on PHP.  It runs a Web server, CRON-like scheduler and tasks to manage the network, USB, OneWire, Modbus polling, Action handling and other system functions required for a typing embedded system.  The firmware reads configuration files at power up off the microSD card and initialises the system accordingly.   Here are a few of the most important functionalites:

The Modbus polling task reads the device configuration file,loads drivers, and starts polling the devices.

The crontab file loads and starts periodic scripts to take care of data collection and processing

The runonce task executes to set up important boot time variables and configuration.

The USB host attempts to connect to a dongle and if found, initialises it and establishes a connection to the Internet

Once the system is booted (usually in less than 2 seconds) the OS can be accessed via HTTP or Telnet.  

WattmonOS - The Application Layer

WattmonOS is a collection of scripts stored on the SD card.  This includes the boot script (runonce.cgi), and three period scripts (cronsec, cronmin, and cronday) that take care of data collection and processing and run from the cron scheduler.  In addition, ip.cgi takes care of exporting data to an external server if required.

All executable scripts have a .cgi extension and will be parsed upon execution.  There are three ways to execute a script:  

  • By opening a URL
  • Through a cron scheduler (or another script)
  • Through the Telnet shell

WattmonOS is a combination of HTML and uPHP scripts that provide a modern front end using Bootstrap and Angular.js.  Once logged in, users can modify configuration settings,edit files using the inbuilt File Manager, and view logged data using the dynamic graphic tools.  

All of this is very generic and can be used for a variety of purposes ranging from data collection to PLC-like processing.  Using the existing interface, it is possible to create very different types of setups, but by extending the application using custom scripting it is possible to vastly extend the functionality. 

Assuming you are using the canned WattmonOS package, the following information will help you get familiarised quickly. 

Device Types

Devices are synonymous with Modbus Devices and are defined by a device configuration file in the /dev/ folder.  Each device type requires a unique device type, i.e. 2027.  Under Control Panel > Device Types, a list of all device types is shown.  Each device type will have one or more registers and one or more roles, linking to those registers.  A register is a 16-bit value that is read from the modbus device, and a device type role is a definition of that register which allows it to be used by Wattmon.  For example, some devices  may have simple 16-bit registers such as a voltage value.  A role could simply map to that register.  However a more complex value from a device, such as an IEEE754 float would require two registers.  This role definition would point to the first register and be set to a floating point type, so Wattmon would know to use both register values and process the result into a float before making the value accessible to the system.


A role is a variable that has a specific type and purpose.  Each role can be linked to one device or system variable and can then be used by the data collector, the action task or in a script.  A role needs to be defined before it can be associated - this is done in the Roles page of the Control Panel.  There are certain important things that need to be defined for each role, namely the Role Name, the role type and the role function.  For example, a role that will be used to read a current from a device would be set to Read Only Value, and not say Digital Input.  Its type would be set to Current and not Watts or Voltage.


The Devices page shows all installed devices in the system.  Use the Manually add a device button to add a new modbus device.  By specifying the Modbus ID of the slave and the Device Type in the drop down list, Wattmon will know what to do and start automatically polling the device.  

Due to memory constraints, Wattmon can handle up to 8 devices.

The next step is to configure the device - this is where you actually link the role you created with the available roles in the device.  At this point the values from the device will be usable by Wattmon and/or displayed on the home page.

Data Collection

Data is logged in CSV files in the /logs/ folder.  A new CSV file is created every day, and data is stored at one-minute intervals (it can be buffered in memory for several minutes before writing to help extend the SD card life).  Under Control Panel > Data Collection, you can edit the data log.  There are three different types of values that can be logged:

  • System Variables - these are calculated by WattmonOS from the various roles and their associated types.  For example, battery_percent is calculated by summing all inbound and outbound current 
  • Device Variables - these are the actual role values from the various devices
  • Global Variables - if a custom script generates some calculated values and stores them in the $_GLOBALS array, these can also be logged

Wattmon can log up to about 30 data points totally.  It may be able to log more, but that would depend on the system configuration and other modules loaded - for example the USB stack takes up RAM so if it is not used, then the total number of points could be increased.


The Control Panel > Graphs  section lets you set up graphs that will draw on the CSV data and display it in a visual graph by day or month, making it easy to see trends at a glance.

Every graph that is created can be accessed from the menu at the left of the page.

Exporting Data

For companies that have many different sites and wish to view their data in a consolidated way, Wattmon can be set to export the CSV data to a server periodically.  This could be the subscription-based portal or a custom server.  In Control Panel > Data Export the interval and export options can be configured.


Wattmon can be used for simple automation tasks using Actions.  Actions can be triggered by one or more conditions, or executed periodically.  They differ from scripts because they require no programming other than through a simple web interface to set up and run independently of the scripting language.  Triggers can include system variables and device variables.  For example it is possible to set up an action to switch on a grid charger when the battery percent goes below a fixed point, or send an email when one or more conditions occur.  Actions can be created and managed using the Actions page under Control Panel.

 This is just a brief summary of the various features of the system and is intended purely to give you an overview of how devices, roles and data collection all tie together.  If you have further questions please don't hesitate to get in touch with us.

To continue, proceed to the WattmonMEGA product page to read about our product or dig deeper using our documentation wiki.