For suitable output, we recommend to use Google Chrome (15+) or Microsoft Edge (79+).
Sensor Devices (SNS)
Standardized procedures for sensors and various devices
Provides classes that standardize procedures for sensors and various devices.
If you are using sensors or devices included in TWELITE PAL, also refer to the
Board (BRD) documentation. Some operations specific to TWELITE PAL may be required and are included in the board definition.
Procedures for Handling Sensors
For sensors like temperature sensors, procedures such as sensor activation → waiting time → value reading are often common.
Make sure to call Wire.begin() before using I2C sensors. After waking from sleep, reinitialization of Wire is done automatically, so no special code is required (Note: if Wire.end() is explicitly called in user code, reinitialization must be described in wakeup()).
void setup() {
auto&& brd = the_twelite.board.use<PAL_AMB>();
..
Wire.begin();
brd.sns_SHTC3.begin();
brd.sns_LTR308ALS.begin();
}
Procedures after starting the reading differ by sensor type. For example, both sensors in <PAL_AMB> manage elapsed time. To notify the sensor object of the elapsed time, use the process_ev() method.
void loop() {
auto&& brd = the_twelite.board.use<PAL_AMB>();
// mostly process every ms.
if (TickTimer.available()) {
// wait until sensor capture finish
if (!brd.sns_LTR308ALS.available()) {
brd.sns_LTR308ALS.process_ev(E_EVENT_TICK_TIMER);
}
if (!brd.sns_SHTC3.available()) {
brd.sns_SHTC3.process_ev(E_EVENT_TICK_TIMER);
}
..
In the above example, TickTimer triggers every 1 ms to notify the elapsed time. E_EVENT_TICK_TIMER conveys the 1 ms passage to the sensor object.
When sufficient time has passed due to wake-up from sleep, use E_EVENT_START_UP instead. The sensor object will then quickly become ready for reading.
None of these procedures guarantee synchronization with real-world time. If actual elapsed time is insufficient, the sensor may return errors or unexpected values.
Common Sensor Methods
setup()
void setup(uint32_t arg1 = 0, uint32_t arg2 = 0)
Initializes the sensor.
begin(), end()
void begin(uint32_t arg1 = 0, uint32_t arg2 = 0)
void end()
Starts or stops sensor acquisition.
process_ev()
void process_ev(uint32_t arg1, uint32_t arg2 = 0)
For sensors that require a wait period, pass E_EVENT_TICK_TIMER or E_EVENT_START_UP to arg1 to notify time progress. If sufficient time has passed after this call, available will become true, and sensor values can be read.
available()
Returns true when the sensor is ready for reading.
probe()
(Only for supported sensors) Returns true when the sensor is connected.
The first communication attempt immediately after probe() may fail.
1 - SHTC3
Temperature and Humidity Sensor
This is a temperature and humidity sensor that uses the I2C bus.
Available only when the board behavior <PAL_AMB> is loaded. Procedures for common methods other than begin() are executed within the board behavior.
Processing Flow
Wire.begin(): Initialize the bus.begin(): Start sensor operation- Wait a few milliseconds
.available() becomes true.get_temp(), .get_humid(): Read the values
Required Procedures for Operation
Wire Bus
Ensure the Wire is active using Wire.begin() before calling the begin() method.
Procedure After Wake-up from Sleep
Ensure the Wire bus is active just before entering sleep (it will be automatically recovered after waking up).
Methods
get_temp(), get_temp_cent()
double get_temp()
int16_t get_temp_cent()
Reads the temperature. get_temp() returns the value in °C, and get_temp_cent() returns the temperature multiplied by 100 as an integer.
On error, a value between -32760 and -32768 is returned.
get_humid(), get_humid_per_dmil()
double get_humid()
int16_t get_humid_per_dmil()
Reads the humidity. get_humid() returns the value in %, and get_humid_per_dmil() returns the humidity multiplied by 100 as an integer.
On error, a value between -32760 and -32768 is returned.
Common Methods
setup()
Allocates memory and performs initialization for the sensor.
begin(), end()
Starts sensor data acquisition. It requires approximately 5ms of wait time before values can be read.
end() is not supported.
process_ev()
void process_ev(uint32_t arg1, uint32_t arg2 = 0)
For sensors requiring wait-time processing, pass E_EVENT_TICK_TIMER or E_EVENT_START_UP to arg1 to notify time progression. After calling this method and enough time has passed, the sensor becomes available and its value can be read.
available()
Returns true when the sensor meets the read condition.
probe()
Returns true when the sensor is connected.
2 - SHT3x
Temperature and Humidity Sensor
This is a temperature and humidity sensor using the I2C bus.
Processing Flow
Wire.begin(): Initialize the bus.setup(): Initialize the sensor.begin(): Start the sensor- Wait for a few milliseconds
.available() becomes true.get_temp(), .get_humid(): Read values
Required Procedures for Operation
Wire Bus
Before calling the setup() method, initialize the Wire with Wire.begin().
Procedure After Waking from Sleep
Ensure the Wire bus is active just before entering sleep (Wire will be automatically recovered after waking).
Code Example
##include <TWELITE>
##include <SNS_SHT3X>
SNS_SHT3X sns_sht3x; // Declare the object
Include #include <SNS_SHT3X> and declare an object of the SNS_SHT3X class.
Initialization
void setup() {
Wire.begin();
sns_sht3x.setup();
}
Starting Sensor Reading
void loop() {
if(eState == E_STATE::INIT) {
sns_sht3x.begin();
eState = E_STATE::CAPTURE;
}
}
To begin reading sensor values, call .begin(). It takes a few milliseconds to complete.
※ The above loop() assumes a state-machine design using the eState variable. (Reference)
Waiting for Sensor Reading
void loop() {
if(eState == E_STATE::CAPTURE) {
if (sns_sht3x.available()) {
// Sensor values are ready
}
}
}
Check .available() to determine whether the sensor values are ready.
Reading Sensor Values
void loop() {
if(eState == E_STATE::CAPTURE) {
if (sns_sht3x.available()) {
Serial << crlf << "SHT3X:"
<< " T=" << sns_sht3x.get_temp() << 'C'
<< " H=" << sns_sht3x.get_humid() << '%';
}
}
}
Once the sensor values are ready, you can read them.
.get_temp() and .get_humid() use floating point operations. You can also retrieve values as integers scaled by 100.
auto temp = div100(sns_sht3x.get_temp_cent());
auto humd = div100(sns_sht3x.get_humid_per_dmil);
Serial << crlf << "SHT3X:"
<< format(" T=%c%d.%02d", temp.neg ? '-' : ' ', temp.quo, temp.rem)
<< format(" H=%c%d.%02d", humd.neg ? '-' : ' ', humd.quo, humd.rem);
In this example, div100() is used to split the x100 values into integer and fractional parts.
Methods
get_temp(), get_temp_cent()
double get_temp()
int16_t get_temp_cent()
Reads the temperature. get_temp() returns °C, while get_temp_cent() returns the value scaled by 100 as an integer.
On error, it returns a value between -32760 and -32768.
get_humid(), get_humid_per_dmil()
double get_humid()
int16_t get_humid_per_dmil()
Reads the humidity. get_humid() returns %RH, while get_humid_per_dmil() returns the value scaled by 100 as an integer.
On error, it returns a value between -32760 and -32768.
Common Methods
setup()
void setup(uint32_t arg1 = 0UL)
Allocates memory and initializes the sensor.
You can specify the I2C address in the lower 8 bits of arg1. If unspecified, it defaults to 0.
##include <SNS_SHT3X>
SNS_SHT3X sns_sht3x;
bool b_found_sht3x = false;
void setup() {
sns_sht3x.setup();
if (!sns_sht3x.probe()) {
delayMicroseconds(100); // just in case, wait for devices to listen further I2C comm.
sns_sht3x.setup(0x45); // alternative ID
if (sns_sht3x.probe()) b_found_sht3x = true;
} else {
b_found_sht3x = true;
}
}
In this example, it first tries to initialize with the default I2C ID. If no response, it retries with address 0x45.
begin(), end()
Begins sensor reading. It takes a few milliseconds before values become ready, during which .available() returns false.
end() is not supported.
process_ev()
void process_ev(uint32_t arg1, uint32_t arg2 = 0)
For sensors that require waiting, provide E_EVENT_TICK_TIMER or E_EVENT_START_UP in arg1 to notify the passage of time. If enough time has elapsed after calling this method, .available() will return true and the sensor value can be read.
available()
Returns true when the sensor is ready to be read.
probe()
Returns true if the sensor is connected.
sns_stat()
Stores various information about the sensor device.
- The stored value is undefined for this device.
sns_opt()
Returns the value passed to setup(uint32_t arg1).
- The lower 8 bits store the specified I2C device address.
3 - LTR-308ALS
Illuminance sensor
This is an illuminance sensor that uses the I2C bus.
Available only when the board behavior <PAL_AMB> is loaded. Common method procedures other than begin() are executed within the board behavior.
Processing Flow
Wire.begin(): Initialize the bus.begin(): Start sensor operation- Wait for 50ms
.available() becomes true.get_luminance(): Read the value
Required Procedures for Operation
Wire Bus
Before calling the .begin() method, ensure the Wire is initialized using Wire.begin().
Procedures When Waking from Sleep
Ensure the Wire bus is active just before entering sleep (it will automatically recover Wire after waking from sleep).
Method
get_luminance()
Returns the illuminance [lx] as an integer value.
Returns -1 in case of an error.
Common Methods
setup()
Allocates memory area for the sensor and performs initialization.
begin(), end()
Starts sensor acquisition. A wait time of about 50ms is required before reading the sensor value.
end() is not supported.
process_ev()
void process_ev(uint32_t arg1, uint32_t arg2 = 0)
For sensors that require wait time processing, provide E_EVENT_TICK_TIMER or E_EVENT_START_UP in arg1 to notify elapsed time. After this method is called and the required time has elapsed, it will become available and the sensor value can be read.
available()
Returns true when the sensor satisfies the read condition.
probe()
Returns true when the sensor is connected.
4 - MC3630
Accelerometer
This is an accelerometer that uses the SPI bus.
Available only when the board behavior <PAL_MOT> or <PAL_NOTICE> <CUE> is loaded. Procedures for common methods other than begin() and available() are executed within the board behavior.
Operation Flow
.begin(): Start sensor operationPIN_SNS_INT interrupt or available(): FIFO queue reaches the specified number of samples.get_que(): Retrieve data from the FIFO queue
Required Procedures for Operation
SPI Bus
No special setup is required.
Sleep Procedure
To allow wake-up via PIN_SNS_INT interrupt, configure the following before entering sleep:
pinMode(PAL_MOT::PIN_SNS_INT, WAKE_FALLING);
Procedure Upon Wake-up
Call the .wakeup() method. This process is handled within the <PAL_MOT> board behavior.
If the internal FIFO queue in the IC becomes full and is not read, data acquisition will stop, and no new values will be stored.
Data Structure
Each sample is stored in a queue smplque of axis_xyzt structures. The x, y, and z members represent the X, Y, and Z axes, respectively.
struct axis_xyzt {
int16_t x;
int16_t y;
int16_t z;
uint16_t t;
};
Each axis value is stored with 1G equivalent to 1000. The t value represents the sample index, starting from 0 and incrementing with each sample.
Methods
read()
Reads data from the semiconductor’s FIFO queue. The return value is the number of bytes read. Use .get_que() to access the queue and retrieve the number of samples stored.
read() is executed after waking from sleep in <PAL_MOT>.
get_que()
smplque<axis_xyzt>& get_que()
Retrieves acceleration samples. The queue is a smplque of axis_xyzt. Once available is true, promptly clear the queue.
Common Methods
setup()
setup() is not used for this sensor.
begin(), end()
void begin(uint32_t conf)
void end()
Initializes the sensor with the specified conf.
conf[0:15] (bit 0–15): Sampling mode, conf[16:23] (bit 16–23): Acceleration range, conf[24:31] (bit 24–31): Number of samples before triggering interrupt.
| conf[0:15] Sample Mode | Description |
|---|
MODE_LP_1HZ_UNOFFICIAL | 1Hz Low Power (unofficial) |
MODE_LP_2HZ_UNOFFICIAL | 2Hz Low Power (unofficial) |
MODE_LP_7HZ_UNOFFICIAL | 7Hz Low Power (unofficial) |
MODE_LP_14HZ | 14Hz Low Power (default) |
MODE_LP_28HZ | 28Hz Low Power |
MODE_LP_54HZ | 54Hz Low Power |
MODE_LP_105HZ | 105Hz Low Power |
MODE_LP_210HZ | 210Hz Low Power |
MODE_LP_400HZ | 400Hz Low Power |
MODE_ULP_25HZ | 25Hz Ultra Low Power |
MODE_ULP_50HZ | 50Hz Ultra Low Power |
MODE_ULP_100HZ | 100Hz Ultra Low Power |
MODE_ULP_190HZ | 190Hz Ultra Low Power |
MODE_ULP_380HZ | 380Hz Ultra Low Power |
Unofficial settings are not documented in the MC3630 datasheet and behavior is undefined. Please verify operation on your own. Our support team does not provide assistance for issues or questions regarding unofficial settings.
| conf[16:23] Acceleration Range | Description |
|---|
RANGE_PLUS_MINUS_8G | ±8G (default) |
RANGE_PLUS_MINUS_4G | ±4G |
RANGE_PLUS_MINUS_2G | ±2G |
RANGE_PLUS_MINUS_1G | ±1G |
process_ev()
void process_ev(uint32_t arg1, uint32_t arg2 = 0)
process_ev() is not used for this sensor.
available()
Returns true when data has been read into the internal queue.
probe()
probe() is not used for this sensor.
wakeup()
Reinitializes the SPI bus after waking from sleep and reads acceleration data.
5 - BMx280
Environmental sensor
This is a pressure, temperature, and humidity (humidity only for BME280) sensor using the I2C bus.
Process Flow
Wire.begin(): Initialize the bus.setup(): Initialize the sensor.begin(): Start sensor operation- Wait for several milliseconds
.available() becomes true.get_press(), .get_temp(), .get_humid(): Read values
Procedures Required for Operation
Wire Bus
Before calling the setup() method, ensure Wire is operational by calling Wire.begin().
Procedures for Sleep Wake-up
Before entering sleep, keep the Wire bus operational (Wire will automatically recover after waking from sleep).
Code Example
##include <TWELITE>
##include <SNS_BME280>
SNS_BME280 sns_bme280; // Declare the object
You need to include #include <SNS_SHT3X> and declare an SNS_SHT3X class object.
Initialization
void setup() {
Wire.begin();
sns_bme280.setup();
}
Start Getting Sensor Values
void loop() {
if(eState == E_STATE::INIT) {
sns_bme280.begin();
eState = E_STATE::CAPTURE;
}
}
Call .begin() to start getting sensor values. It takes several milliseconds to complete.
Note: The above loop() is designed to branch processing based on the state variable eState. (Reference)
Waiting for Sensor Value Acquisition
void loop() {
if(eState == E_STATE::CAPTURE) {
if (sns_bme280.available()) {
// Sensor values ready to read
}
}
}
You can check if sensor values are ready by .available().
Reading Sensor Values
void loop() {
if(eState == E_STATE::CAPTURE) {
if (sns_bme280.available()) {
Serial << crlf << "BMx280:"
<< " P=" << int(sns_bme280.get_press()) << "hPa";
<< " T=" << sns_bme280.get_temp() << 'C'
<< " H=" << sns_bme280.get_humid() << '%';
}
}
}
Once sensor values are ready, you can read them.
.get_temp(), get_humid() involve floating-point operations. You can also get values as integers multiplied by 100.
auto temp = div100(sns_bme280.get_temp_cent());
auto humd = div100(sns_bme280.get_humid_per_dmil);
Serial << crlf << "BMx280:"
<< " P=" << int(sns_bme280.get_press()) << "hPa";
<< format(" T=%c%d.%02d", temp.neg ? '-' : ' ', temp.quo, temp.rem)
<< format(" H=%c%d.%02d", humd.neg ? '-' : ' ', humd.quo, humd.rem);
Here, div100() is used to split the value multiplied by 100 into integer and fractional parts.
Methods
get_press()
Reads pressure. The unit is hectopascal (hPa), usually around 1000.
get_temp(), get_temp_cent()
double get_temp()
int16_t get_temp_cent()
Reads temperature. get_temp() returns °C as a double, and get_temp_cent() returns temperature multiplied by 100 as an integer.
Returns values between -32760 and -32768 on error.
get_humid(), get_humid_per_dmil()
double get_humid()
int16_t get_humid_per_dmil()
Reads humidity. get_humid() returns % as a double, and get_humid_per_dmil() returns humidity multiplied by 100 as an integer.
Returns values between -32760 and -32768 on error.
Common Methods
setup()
void setup(uint32_t arg1 = 0UL)
Allocates memory and initializes the sensor.
The lower 8 bits of arg1 can store the I2C address. If not specified, it defaults to 0.
##include <SNS_BME280>
SNS_BME280 sns_bme280;
bool b_found_bme280 = false;
void setup() {
...
sns_bme280.setup();
if (!sns_bme280.probe()) {
delayMicroseconds(100); // device needs small time for further I2C comm.
sns_bme280.setup(0x77); // alternative ID
if (sns_bme280.probe()) b_found_bme280 = true;
} else {
b_found_bme280 = true;
}
...
The code first tries the default I2C ID to check device response; if no response, tries 0x77 as an alternative.
begin(), end()
Starts sensor acquisition. It takes several milliseconds to read sensor values; wait until available() returns true.
end() is not supported.
process_ev()
void process_ev(uint32_t arg1, uint32_t arg2 = 0)
For sensors with wait time processing, pass E_EVENT_TICK_TIMER or E_EVENT_START_UP in arg1 to notify elapsed time. After this call, if enough time has passed, available() will return true and sensor values can be read.
available()
Returns true when sensor reading conditions are met.
probe()
Returns true when the sensor is connected.
sns_stat()
Contains various sensor device information.
- The lower 8 bits store the chip model of BME280/BMP280.
0x60 means BME280, and 0x58 means BMP280.
sns_opt()
Stores the value passed to setup(uint32_t arg1).
- The lower 8 bits store the specified I2C device address.
6 - PCA9632
LED Driver
This is the LED driver used in NOTICE PAL.
Processing Flow
Wire.begin(): Initialize the bus.setup(): Initialize the class object.reset(): Initialize the driver- Execute various operations
About PCA9632
It is a 4-channel LED driver.
- Each channel can be set to OFF, ON, PWM, or BLINK mode
- Each channel supports independent brightness control via PWM
- All channels set to blink will share the same blink pattern
- Individual brightness control (via PWM) is available even in blink mode
Required Procedures for Operation
Wire Bus
Ensure the Wire is initialized via Wire.begin() before calling the setup() method.
Procedure Upon Wake from Sleep
Ensure the Wire bus is active right before entering sleep (Wire will be automatically recovered after waking up).
Code Example
##include <TWELITE>
##include <SNS_PCA9632>
SNS_PCA9632 pca;
Include #include <SNS_PCA9632> and declare an instance of the SNS_PCA9632 class.
Initialization & Reset
void setup() {
Wire.begin();
pca.setup();
pca.reset();
}
Lighting Up
...
pca.set_led_duty_all(
127,
127,
127,
127
);
pca.set_led_status(
SNS_PCA9632::LED_PWM,
SNS_PCA9632::LED_NOP,
SNS_PCA9632::LED_PWM,
SNS_PCA9632::LED_NOP);
In the example above, LED1 and LED3 are lit using PWM control.
Be cautious of the current consumed by the driver when lighting up LEDs.
Methods
Constructor, setup()
SnsPCA9632(uint8_t i2c_addr = DEFAULT_I2C_ADDRESS)
void setup(uint8_t i2c_addr = DEFAULT_I2C_ADDRESS)
The constructor allows specifying the i2c_addr.
If the class object is defined globally, the constructor is not called automatically, so ensure to call setup().
reset()
Initializes the device.
Writes the following values to registers starting at address 0x0:
{0x81, 0x35, 0x7F, 0x7F, 0x7F, 0x7F, 0x7F, 0x0B, 0x00}
set_mode2()
bool set_mode2(uint8_t u8var = 0x35)
Writes the specified value to the MODE2 register.
set_power_mode()
bool set_power_mode(bool b_pow_on)
Set b_pow_on to true for normal operation, or false to enter sleep mode.
set_blink_cycle(), set_blink_cycle_ms()
bool set_blink_cycle(uint8_t u8var)
bool set_blink_cycle_ms(uint16_t u16ms)
Sets the blink (group PWM) cycle.
If u8var is specified, the cycle is (u8var+1)/24 seconds.
If u16ms is specified, it sets the cycle in milliseconds.
set_blink_duty()
bool set_blink_duty(uint8_t u8duty);
Sets the duty ratio of the blink (group PWM). The lit duration becomes u8duty/256, where 0 is OFF and 255 is fully ON.
set_led_duty()
bool set_led_duty(uint8_t port, uint8_t duty)
Sets the brightness (PWM duty ratio).
port specifies the target LED (SNS_PCA9632::LED1..4).
duty specifies a value from 0 to 255, with a brightness ratio of duty/256.
set_led_duty_all()
bool set_led_duty_all(uint8_t p1, uint8_t p2, uint8_t p3, uint8_t p4)
Sets the brightness (PWM duty ratio) for all LEDs.
p1, p2, p3, p4 correspond to LED1..4. Each takes a value from 0 to 255, with a brightness ratio of duty/256.
set_led_status()
bool set_led_status(uint8_t u8led1, uint8_t u8led2, uint8_t u8led3, uint8_t u8led4)
Sets the ON/OFF status for all LEDs.
u8led1..4 specify the state of LED1 to LED4.
Available states:
| Description |
|---|
SNS_PCA9632::LED_OFF | OFF |
SNS_PCA9632::LED_ON | ON |
SNS_PCA9632::LED_PWM | PWM brightness control |
SNS_PCA9632::LED_BLINK | Blink control (group PWM) |
SNS_PCA9632::LED_NOP | Do not change the current state |
probe()
Returns true if the device is present on the I2C bus.
show_registers()
Displays values of registers (0x0–0x8).
7 - SHT4x
Temperature and Humidity Sensor
This is a temperature and humidity sensor that uses the I2C bus.
Available only when the board behavior <ARIA> is loaded. Procedures for common methods other than begin() are executed within the board behavior.
Processing Flow
Wire.begin(): Initialize the bus.begin(): Start sensor operation- Wait a few milliseconds
.available() becomes true.get_temp(), .get_humid(): Read the values
Required Procedures for Operation
Wire Bus
Ensure the Wire is active using Wire.begin() before calling the begin() method.
Procedure After Wake-up from Sleep
Ensure the Wire bus is active just before entering sleep (it will be automatically recovered after waking up).
Methods
get_temp(), get_temp_cent()
double get_temp()
int16_t get_temp_cent()
Reads the temperature. get_temp() returns the value in °C, and get_temp_cent() returns the temperature multiplied by 100 as an integer.
On error, a value between -32760 and -32768 is returned.
get_humid(), get_humid_per_dmil()
double get_humid()
int16_t get_humid_per_dmil()
Reads the humidity. get_humid() returns the value in %, and get_humid_per_dmil() returns the humidity multiplied by 100 as an integer.
On error, a value between -32760 and -32768 is returned.
Common Methods
setup()
Allocates memory and performs initialization for the sensor.
begin(), end()
Starts sensor data acquisition. It requires approximately 5ms of wait time before values can be read.
end() is not supported.
process_ev()
void process_ev(uint32_t arg1, uint32_t arg2 = 0)
For sensors requiring wait-time processing, pass E_EVENT_TICK_TIMER or E_EVENT_START_UP to arg1 to notify time progression. After calling this method and enough time has passed, the sensor becomes available and its value can be read.
available()
Returns true when the sensor meets the read condition.
probe()
Returns true when the sensor is connected.