Grid

A table of cells on one virtual pin. The sketch sends a comma-separated list, row by row. Color rules paint cells from those numbers.

Sample pin: V5

Set it up on the server

Sign in to the Box IO dashboard and open the project that uses this device key.
Turn on Edit.
In Edit, add Grid.
Set Virtual pin to 5.
Set Rows and Columns. Both must be from 1 to 16. A 2 by 2 grid has 4 cells.
Choose Read only, or Read and write if the dashboard should send edits back to the sketch.
Set the default cell color, then add color rules. Each rule has a low, a high, a color, and either all cells or certain cell numbers.
Save the layout, then open Live.
Flash the sketch below with the same device key, host, and port 5923. Keep BoxIO.run() in loop().

Properties

Sketch values are always strings, including numbers: BoxIO.setProperty(V2, "max", "200").

Property	Where to set it	Format	Example	Effect
`rows`	Dashboard or sketch	Whole number 1 to 16	`2`	Row count. A sketch setProperty replaces the dashboard size.
`cols`	Dashboard or sketch	Whole number 1 to 16	`2`	Column count.
`mode`	Dashboard	readonly or readwrite	`readonly`	Read and write lets a cell edit send the full grid back. The dashboard mode stays in charge when the widget already has one.
`colorOff`	Dashboard or sketch	#RRGGBB	`#1a2333`	Color for a cell whose value is blank or matches no rule.
`colorRules`	Dashboard or sketch	low-high:#hex:cells joined by semicolons	`0-25:#2ee0c5:all;35-100:#ff5d73:0,1`	First matching rule wins. cells is the word all, or zero-based indexes separated by commas.
`label`	Dashboard or sketch	Plain text	`Pump`	Caption above the widget. On a round or oval button this is the caption, not the word on the button face.
`hideLabel`	Dashboard	On or off	`checked`	Hides the caption. Button face text, meter numbers, and label text stay visible.
`fontSize`	Dashboard	Whole number 8 to 160, or blank for automatic size	`28`	Text size in pixels inside the widget.
`opacity`	Dashboard	10% to 100%	`70%`	Lets an overlapping widget show through. 100% is solid.

Formatting

Send one virtualWrite for the whole grid. Values are row-major: cell 0 is the top left, then across the row, then the next row. A 2 by 2 grid is 21,22,40,18.
A JSON array also works: [21,22,40,18]. Commas are the usual form.
Color rule string: 0-25:#2ee0c5:all;35-100:#ff5d73:0,1. Low and high are inclusive. 0,1 means only cells 0 and 1. Cell numbers start at 0.
In Read and write, leaving a cell sends every cell joined by commas, including blanks, to BOX_WRITE on that pin.
An Uno URL buffer is smaller. Keep grids modest on AVR. ESP32 can send about 32 cells.

Sketch

Paste the device key over bx_paste_your_device_key_here. Wi-Fi boards include BoxIOEsp32.h. Ethernet boards use the same calls with an EthernetClient.

#define BOXIO_AUTH "bx_paste_your_device_key_here"
#define WIFI_SSID  "your-ssid"
#define WIFI_PASS  "your-password"
#define BOXIO_HOST "localhost"
#define BOXIO_PORT 5923

#include <BoxIOEsp32.h>

void setup() {
  BoxIO.begin(BOXIO_AUTH, WIFI_SSID, WIFI_PASS, BOXIO_HOST, BOXIO_PORT);
BoxIO.setProperty(V5, "label", "Grid Lab");
  BoxIO.setProperty(V5, "rows", "2");
  BoxIO.setProperty(V5, "cols", "2");
  BoxIO.setProperty(V5, "colorOff", "#1a2333");
  BoxIO.setProperty(V5, "colorRules", "0-25:#2ee0c5:all;35-100:#ff5d73:all");
  int cells[] = {21, 22, 40, 18};
  BoxIO.virtualWrite(V5, cells, 4);
}

void loop() {
  BoxIO.run();
static uint32_t last = 0;
  if (millis() - last < 1000) return;
  last = millis();
  static int n = 0;
  n = (n + 3) % 180;
  int cells[] = {n % 50, 22, 40, 18};
  BoxIO.virtualWrite(V5, cells, 4);
}

BOX_WRITE(V5) {
  // Full CSV when the widget is Read and write.
  Serial.println(param.asStr());
}

What you should see

Four cells appear. Numbers from 0 through 25 are teal. Numbers from 35 through 100 are red. Other numbers keep the default cell color. Switch the widget to Read and write before expecting BOX_WRITE to run.