For suitable output, we recommend to use Google Chrome (15+) or Microsoft Edge (79+).
PAL Common Definitions
Common definitions for the TWELITE PAL series
TWELITE PAL hardware shares common components, and board behaviors define a shared interface for those components.
Constants
The following constants are defined:
static const uint8_t PIN_BTN = 12; // button (as SET)
static const uint8_t PIN_LED = 5; // LED
static const uint8_t PIN_WDT = 13; // WDT (shall tick every 60sec)
static const uint8_t PIN_D1 = 1; // DIP SW1
static const uint8_t PIN_D2 = 2; // DIP SW2
static const uint8_t PIN_D3 = 3; // DIP SW3
static const uint8_t PIN_D4 = 4; // DIP SW4
static const uint8_t PIN_SNS_EN = 16;
static const uint8_t PIN_SNS_INT = 17;
These can be accessed like PAL_AMB::PIN_BTN.
Hardware Initialization
pinMode(PIN_BTN, INPUT_PULLUP);
pinMode(PIN_LED, OUTPUT_INIT_HIGH);
pinMode(PIN_WDT, OUTPUT_INIT_HIGH);
pinMode(PIN_D1, INPUT_PULLUP);
pinMode(PIN_D2, INPUT_PULLUP);
pinMode(PIN_D3, INPUT_PULLUP);
pinMode(PIN_D4, INPUT_PULLUP);
Pins are initialized as shown in the code above.
Watchdog Timer
The external watchdog timer is reset at startup, after waking from sleep, and after a certain amount of time has passed since startup.
To prevent the watchdog timer from timing out, configure TWELITE to wake within 60 seconds (when using the calibrated internal CR timer).
Methods
set_led()
void set_led(uint8_t mode, uint16_t tick)
Controls LED (D1).
Do not call this method unless LED control is handled by the board behavior.
mode takes the following parameters. tick specifies the ON duration [ms], but see the explanation of mode for details.
| Mode | Description |
|---|
LED_TIMER::BLINK | Blinks the LED. Toggles ON/OFF every tick ms. After waking from sleep, it resets and starts ON. |
LED_TIMER::ON_RX | Turns on the LED for tick ms when a packet is received. |
LED_TIMER::ON_TX_COMP | Turns on the LED for tick ms when transmission completes. |
Settings are preserved across sleep cycles.
led_one_shot()
void led_one_shot(uint16_t tick)
Turns on the LED for a specified duration. Cannot be used simultaneously with set_led().
get_D1() .. D4(), get_DIPSW_BM()
inline uint8_t get_D1()
inline uint8_t get_D2()
inline uint8_t get_D3()
inline uint8_t get_D4()
inline uint8_t get_DIPSW_BM()
get_D1() through get_D4() return 0 when the DIP switch is in the HIGH (up) position, and 1 when in the LOW (down) position.
get_DIPSW_BM() returns the DIP switch setting as a value from 0 to 15, calculated as: SW1==LOW = 1, SW2==LOW = 2, SW3==LOW = 4, and SW4==LOW = 8.
The logic here is inverted from the actual HIGH(1)/LOW(0) levels of D1–D4.
This is because a DIP switch in the LOW(0) position is considered “set” and assigned a value of 1.
These values are only read at system startup and do not reflect subsequent changes to the DIP switch positions.
1 - <PAL_NOTICE>
For NOTICE PAL
This board behavior is for the NOTICE PAL.
In addition to the common definitions, this behavior enables access to onboard sensors.
- LED driver PCA9632
- Accelerometer MC3630
void setup() {
auto&& brd = the_twelite.board.use<PAL_NOTICE>();
}
Member Objects
sns_PCA9632
Object for the PCA9632 device. The board definition handles Wire initialization and device setup. Use the control methods described later to interact with the device.
CR2032 coin cells cannot continuously supply high current. This board sets maximum brightness to approximately 50% PWM duty by default, but even this may stress the battery. Adjust the number of LEDs lit, brightness, or blinking pattern to meet your power constraints.
If using a coin battery, pulsed lighting (e.g., flashing briefly every second) can reduce peak current draw.
For example, turning on the LED for about 20ms every 1 second can still appear bright enough while minimizing the current (e.g., 5mA * 20ms per second = 0.1mA average).
sns_MC3630
Object for the MC3630 sensor. Handles SPI setup, device initialization, and interrupt processing. Use the methods provided in sns_MC3630.
PCA9632 Definitions
static const uint8_t LED_OFF = SnsPCA9632::LED_OFF;
static const uint8_t LED_ON = SnsPCA9632::LED_PWM;
static const uint8_t LED_BLINK = SnsPCA9632::LED_BLINK;
static const uint8_t LED_NOP = SnsPCA9632::LED_NOP;
static const uint8_t LED_R = SnsPCA9632::LED1;
static const uint8_t LED_G = SnsPCA9632::LED2;
static const uint8_t LED_B = SnsPCA9632::LED3;
static const uint8_t LED_W = SnsPCA9632::LED4;
static const uint8_t LED_REG_MAX_PWM = 127;
static const uint8_t LED_REG_BOOST_PWM = 255;
LED States
| Definition | Description |
|---|
PAL_NOTICE::LED_OFF | Off |
PAL_NOTICE::LED_ON | On (PWM brightness control) |
PAL_NOTICE::LED_BLINK | Blinking |
PAL_NOTICE::LED_NOP | No change |
LED Identifiers
| Definition | Description |
|---|
PAL_NOTICE::LED_R | Red LED |
PAL_NOTICE::LED_G | Green LED |
PAL_NOTICE::LED_B | Blue LED |
PAL_NOTICE::LED_W | White LED |
Register Brightness Settings
| Definition | Description |
|---|
PAL_NOTICE::LED_REG_MAX_PWM | Standard brightness PWM register value (approx. 50%) |
PAL_NOTICE::LED_REG_BOOST_PWM | Boost brightness PWM register value |
PCA9632 Control Methods
Master Switch
void set_led_master_sw_on() { digitalWrite(PIN_SNS_EN, LOW); }
void set_led_master_sw_off() { digitalWrite(PIN_SNS_EN, HIGH); }
NOTICE PAL includes a FET switch after the PCA9632 output. LEDs will not light unless this switch is turned ON.
LED State Control
void set_led_r_blink()
void set_led_r_on()
void set_led_r_off()
void set_led_g_on()
void set_led_g_blink()
void set_led_g_off()
void set_led_b_on()
void set_led_b_blink()
void set_led_b_off()
void set_led_w_on()
void set_led_w_blink()
void set_led_w_off()
These functions set individual LEDs to ON, OFF, or BLINK state.
void set_leds(uint8_t r, uint8_t g, uint8_t b, uint8_t w)
void set_leds_off()
set_leds() controls the state of all LEDs. Each parameter must be one of: PAL_NOTICE::LED_OFF, PAL_NOTICE::LED_ON, PAL_NOTICE::LED_BLINK, or PAL_NOTICE::LED_NOP.
LED Brightness Control
void set_led_brightness_r_reg(uint8_t duty)
void set_led_brightness_g_reg(uint8_t duty)
void set_led_brightness_b_reg(uint8_t duty)
void set_led_brightness_w_reg(uint8_t duty)
void set_leds_brightness_reg(uint8_t r, uint8_t g, uint8_t b, uint8_t w)
void set_led_brightness_r1000(uint16_t duty, bool boost = false)
void set_led_brightness_g1000(uint16_t duty, bool boost = false)
void set_led_brightness_b1000(uint16_t duty, bool boost = false)
void set_led_brightness_w1000(uint16_t duty, bool boost = false)
void set_leds_brightness1000(
uint16_t r, uint16_t g, uint16_t b, uint16_t w, bool boost = false)
Controls PWM duty cycle (brightness) of LEDs.
set_led_brightness_?_reg() and set_leds_brightness_reg() directly specify 0–255 register values, where brightness is duty/256.
set_led_brightness_?1000() and set_leds_brightness1000() accept values from 0 to 1000. 0 means off, higher values increase brightness. When boost=false, a value of 1000 maps to register value 127; when boost=true, it maps to 255.
As NOTICE PAL is powered by a coin cell, the standard maximum is set to approximately 50% duty cycle.
Actual brightness depends on register value resolution, even if specified on a 0–1000 scale.
Blink Control
void set_blink_cycle_ms(uint16_t x)
void set_blink_duty1000(uint16_t x)
LEDs set to PAL_NOTICE::LED_BLINK blink based on the specified cycle and duty.
- Per-LED blinking patterns are not supported.
- Brightness during blink is set by the current PWM duty configuration.
set_blink_cycle_ms() sets blink cycle in milliseconds.
set_blink_duty1000() sets ON duration as cycle * x / 1000.
Actual brightness depends on register value resolution, even if specified on a 0–1000 scale.
LED Test
Briefly lights up all four LEDs. After this, the master switch is left ON (set_led_master_sw_on()).
2 - <PAL_AMB>
For Ambient Sensor PAL
This board behavior is for the
Ambient Sensor PAL.
In addition to the common definitions, this behavior enables access to onboard sensors.
- Temperature and Humidity Sensor SHTC3
- Ambient Light Sensor LTR308ALS
void setup() {
auto&& brd = the_twelite.board.use<PAL_AMB>();
}
Member Objects
sns_SHTC3
Object for the SHTC3 sensor.
sns_LTR308ALS
Object for the LTR-308ALS sensor.
3 - <PAL_MAG>
For Open-Close Sensor PAL
This board behavior is for the Open-Close Sensor PAL.
void setup() {
auto&& brd = the_twelite.board.use<PAL_MAG>();
}
The sensor on the Open-Close Sensor PAL is a magnetic sensor with two interrupt input lines only.
const uint8_t PAL_MAG::PIN_SNS_NORTH = 16;
const uint8_t PAL_MAG::PIN_SNS_OUT1 = 16;
const uint8_t PAL_MAG::PIN_SNS_SOUTH = 17;
const uint8_t PAL_MAG::PIN_SNS_OUT2 = 17;
PAL_MAG::PIN_SNS_NORTH triggers an interrupt when the sensor detects the north pole; PAL_MAG::PIN_SNS_SOUTH also triggers an interrupt upon detecting the north pole.
Configure the following before entering sleep:
pinMode(PAL_MAG::PIN_SNS_OUT1, PIN_MODE::WAKE_FALLING);
pinMode(PAL_MAG::PIN_SNS_OUT2, PIN_MODE::WAKE_FALLING);
On wake-up, check the GPIO that triggered the wake-up:
uint8_t b_north =
the_twelite.is_wokeup_by_dio(PAL_MAG::PIN_SNS_NORTH);
uint8_t b_south =
the_twelite.is_wokeup_by_dio(PAL_MAG::PIN_SNS_SOUTH);
4 - <PAL_MOT>
For Motion Sensor PAL
This board behavior is for the Motion Sensor PAL.
In addition to the common definitions, this behavior enables access to onboard sensors.
void setup() {
auto&& brd = the_twelite.board.use<PAL_MOT>();
}
Member Objects
sns_MC3630
Object for the MC3630 sensor.