Skip to content
This repository has been archived by the owner on Jul 5, 2023. It is now read-only.

Latest commit

 

History

History
421 lines (302 loc) · 13.7 KB

main.md

File metadata and controls

421 lines (302 loc) · 13.7 KB
Raw

Kalmon

Table of Contents

Introduction

Kalmon is a configurable sensor hub package. It was created to be reusable, configurable and well-integrated with a fair amount of systems.

Since Kalmon is built ontop of MySensors, it should work with a handful of open source domotics systems.

Agreements and Specifications

  • The serial baud rate is set to 115200.

MySensor Serial Protocol Additions

This section describes additions to the MySensor Serial Protocol, for which documentation can be found here.

Users and Integrators are encouraged to read the MySensors Serial Protocol documentation thoroughly before reading any further.

Custom Sensor Types

The MySensors Serial Protocol supports about thirty sensor types. These are sent to the gateway when presenting a new sensor in the form of an unsigned eight-bit char. We have started defining custom sensor types starting from 128. The constant names are prefixed with C for CUSTOM.

Name Value Description
CS_ACCELEROMETER 128 Accelerometer. Added to support the ADXL-345 module.

Custom Value Types

The MySensors Serial Protocol supports about fourty value types. These are sent to the gateway when submitting a sensor value in the form of an unsigned eight-bit char. We have started defining custom value types starting from 128. The constant names are prefixed with C for CUSTOM.

Name Value Description
CV_AVAILABLE_MEMORY 128 Available memory in bytes.
CV_ACCELERATION_X 129 Acceleration X value.
CV_ACCELERATION_Y 130 Acceleration Y value.
CV_ACCELERATION_Z 131 Acceleration Z value.

Node Information & Stats

A MySensors node has support for sending the battery level to the gateway. When this is done a child_sensor_id of 255 is used by default.

As the public API is limited to using the MySensor::send() method, we are forced to use the C_SET message types. As such, we have chosen to submit any and all custom node-related info & stats using the message type C_SET and child sensor id NODE_SENSOR_ID or 255.

Currently, the following node information and statistics are sent:

  • Available memory:

    Example message:

    5;255;1;0;128;1064

    Parsing this message would yield:

    Node ID         => 5
Child Sensor ID => 255  # NODE_SENSOR_ID
Message Type    => 1    # C_SET
Ack Required    => 0    # false
Value Type      => 128  # CV_AVAILABLE_MEMORY
Value           => 1064 # Available memory in bytes

Commands

A few commands can be executed, mostly related to debugging and configuration. These commands can currently only be executed over a serial connection. Wireless command execution is in the works.

Command arguments are space-delimited, and input ends when a newline character is encountered.

The following commands are currently defined:

Command Format Description
21 $cmd\n Print device stats
22 $cmd\n Perform a soft reset
41 $cmd\n Load configuration from EEPROM
42 $cmd\n Save configuration to EEPROM
43 $cmd $key\n Get the value of a configuration variable
44 $cmd $key $value\n Set the value of a configuration variable

Configuration

A variety of different configuration options are supported which can be read and written using certain commands.

Please keep in mind that not saving the configuration after you have made changes will cause those changes to be lost upon the next reboot.

The following configuration options are currently defined:

Name Key Type Default Description
DEBUG 0 bool true The global debug flag.
LOOP_DELAY 8 uint16_t 250 The time the device should be idle per loop, in milliseconds.
SERIAL_BAUD_RATE 9 uint16_t 9600 Serial baud rate. Deprecated.
SERIAL_INPUT_BUFFER_SIZE 10 uint16_t 32 The buffer size for serial input, in bytes.
SENSOR_UPDATE_INTERVAL 11 uint16_t 15 Interval between sensor updates, in seconds. If set to 0, disables sensor updates. If the device is woken from sleep, the sensor update timer is reset, meaning the interval time has to pass every time the device wakes up before a sensor update is sent.
AWAKE_DURATION 12 uint16_t 25 How long the device should stay awake, in seconds. This setting only matters if SLEEP_DURATION is also set.
SLEEP_DURATION 13 uint16_t 1800 How long the device should remain asleep, in seconds. If set to 0 disables sleeping.
INTERRUPT_OPTIONS 14 uint16_t 0 Interrupt configuration, mainly for power saving. This value is a bitmask. See the power savings section.
MODULE_1_CONFIGURATION 24 char[n] NULL Configuration for module #1. For more information, see the modules section.
MODULE_2_CONFIGURATION 25 char[n] NULL Configuration for module #2. For more information, see the modules section.
MODULE_3_CONFIGURATION 26 char[n] NULL Configuration for module #3. For more information, see the modules section.
MODULE_4_CONFIGURATION 27 char[n] NULL Configuration for module #4. For more information, see the modules section.
MODULE_5_CONFIGURATION 28 char[n] NULL Configuration for module #5. For more information, see the modules section.
MODULE_6_CONFIGURATION 29 char[n] NULL Configuration for module #6. For more information, see the modules section.
MODULE_7_CONFIGURATION 30 char[n] NULL Configuration for module #7. For more information, see the modules section.
MODULE_8_CONFIGURATION 31 char[n] NULL Configuration for module #8. For more information, see the modules section.

Power savings

Intervals and durations for sensor updates, sleeping and being awake can be configured using the SENSOR_UPDATE_INTERVAL, SLEEP_DURATION and AWAKE_DURATION options, respectively.

External interrupts can be used to wake the device, if required. These can be configured using the INTERRUPT_OPTIONS option. The value here is a bitmask, with bit 0 enabling the INT0 interrupt, bit 1 enabling the INT1 interrupt, and the rest of the bits specifying the interrupt modes. The values that can be used are outlined below:

Bit 4 Bit 0
Enable INT0 Any 1
Enable INT1 1 Any
Bit 7 / Bit 3 Bit 6 / Bit 2 Bit 5 / Bit 1
Mode LOW 0 0 0
Mode CHANGE 0 0 1
Mode FALLING 0 1 0
Mode RISING 0 1 1

To maximize power conservation, one can set the option SLEEP_DURATION to 0 when enabling external interrupts. This will cause the device to only be woken by the configured interrupts.

Modules

External modules can be attached, mixed and matched to suit your needs. Examples of such modules are a sonar, accelerometer, humidity sensor, and so on. To configure modules, simply use the configuration commands to insert module configuration into one of the available slots.

The following modules are currently defined:

DHT11

DHT11 Digital Temperature Humidity Sensor Module

Presented as humidity sensor S_HUM and temperature sensor S_TEMP, values sent as humidity value V_HUM and temperature value V_TEMP.

Configuration

1,${pin}

Parameters

  • pin:

    • digital input pin

HCSR04

HC-SR04 Ultrasonic Sensor Distance Measuring Module

Presented as distance sensor S_DISTANCE, values sent as distance value V_DISTANCE.

Configuration

2,${trig_pin},${echo_pin}

Parameters

  • trig_pin:

    • trigger pin

  • echo_pin:

    • echo pin

KY038

Keyes Microphone Sound Detection Sensor Module

Presented as custom sensor S_CUSTOM, values sent as var1 value V_VAR1.

Configuration

3,${pin}

Parameters

  • pin:

    • analog input pin

Notes

Not accurate at all. If I could go back in time, I wouldn't have bought 4.

MNEBPTCMN

Meeeno MN-EB-PTCMN Photosensitive Sensor Module

Presented as light level sensor S_LIGHT_LEVEL, values sent as light level value V_LIGHT_LEVEL.

Configuration

4,${pin}

Parameters

  • pin:

    • analog input pin

Notes

It's easy to get a reading, you just don't know how to scale that reading unless you perform some assisted calibration.

ADXL345

ADXL345 Digital 3-Axis Gravity Acceleration Sensor Module

Additional documentation: here

Presented as accelerometer sensor CS_ACCELEROMETER, values sent as acceleration values CS_ACCELERATION_X, CS_ACCELERATION_Y and CS_ACCELERATION_Z.

If activity or inactivity detection are enabled, also presents a motion sensor S_MOTION, with values sent as tripped status V_TRIPPED.

Supports link mode, where activity interrupts are prevented until inactivity is detected, and vice versa.

Supports an auto-sleep mode, where power consumption is reduced by a huge margin. Highly recommended for low-power projects.

Configuration

5,${activity_threshold},${inactivity_threshold},${inactivity_time},${sensitivity_range},${data_rate},${power_mode}

Parameters

  • activity_threshold:

    • threshold (6.25mg / LSB) for activity detection
    • enables activity detection if not set to 0

  • inactivity_threshold:

    • threshold (6.55mg / LSB) for inactivity detection
    • enables inactivity detection if not set to 0

  • inactivity_time:

    • inactivity time
    • required for inactivity detection
    • defaults to 5 if set to 0

  • sensitivity_range:

    • configures the sensitivity
    • contains the value sent to the DATA_FORMAT register
    • highly recommended to read the additional documentation linked above
    • currently not used

  • data_rate:

    • configures the data rate
    • contains the value sent to the BW_RATE register
    • highly recommended to read the additional documentation linked above
    • currently not used

  • power_mode:

    • configures the power mode

    • contains the value sent to the POWER_CTL register

    • highly recommended to read the additional documentation linked above

    • defaults to 0x08 / 8 (measurement mode)

    • suggested values:

      Dec Hex Description
      8 0x08 Measurement mode
      40 0x28 Measurement mode + link mode
      56 0x38 Measurement mode + link mode + auto-sleep mode

Generic Voltage

This module setting can be used to measure generic analog voltages.

Presented as power sensor S_POWER, values sent as voltage value V_VOLTAGE.

Supports setting a coefficient, as well as setting the number of samples.

Configuration

6,${sample_count},${coefficient}

Parameters

  • sample_count:

    • amount of samples to take
    • defaults to 1 if set to 0

  • coefficient:

    • number (float) to multiply the resulting voltage by
    • recommended for those using voltage dividers to measure larger voltages
    • defaults to 1.0 if set to 0