“Dzhmil” sketch settings (version 1.7)

The settings are constants at the top of the sketch (main.cpp). After changing a value, re-upload the sketch to the controller. Verify every change in real-world tests: reaction-zone and filter parameters directly affect the user's safety.

1. Obstacle reaction zones

Parameter	Default	Unit	Description and effect
`CENTER_ALERT_DISTANCE_MM`	1050	mm	Distance at which the center sensor starts warning. Higher: earlier warning, but more unnecessary alerts in tight spaces. Lower: less time to react. Keep it above VIBRO_VERY_FAR_BORDER_MM, otherwise the “very far” rhythm is never used.
`SIDE_ALERT_DISTANCE_MM`	900	mm	Same for the left and right sensors. Decrease it if walls in narrow corridors cause constant alerts.
`DIRECTION_GROUP_MARGIN_MM`	300	mm	If several sensors see obstacles within this margin of the nearest one, their motors vibrate together. Higher: several motors vibrate together more often (less precise direction). Lower: only the side of the nearest obstacle vibrates.
`ALERT_HYSTERESIS_MM`	80	mm	Margin when leaving a zone: the signal stops only when the obstacle has moved beyond the zone border by more than this value. Higher: steadier at the border, but the signal stops later. Lower: the motors may twitch at the zone border.

2. Vibration rhythm by distance

The main cue for the user is the length of the pause: the closer the obstacle, the shorter the pause. The zone borders must decrease: VERY_FAR > FAR > MEDIUM > CLOSE.

Parameter	Default	Unit	Description and effect
`VIBRO_VERY_FAR_BORDER_MM`	850	mm	Border between the “very far” zone (beyond this border) and the “far” zone.
`VIBRO_FAR_BORDER_MM`	700	mm	Border between the “far” zone and the “medium distance” zone.
`VIBRO_MEDIUM_BORDER_MM`	550	mm	Border between the “medium distance” zone and the “close” zone.
`VIBRO_CLOSE_BORDER_MM`	400	mm	Border between the “close” zone and the “very close” zone.
`PATTERN_VERY_FAR`	120 / 1200	ms (pulse / pause)	“Very far” zone: sparse single pulse.
`PATTERN_FAR`	120 / 800	ms (pulse / pause)	“Far” zone: noticeably more frequent pulses.
`PATTERN_MEDIUM`	140 / 450	ms (pulse / pause)	“Medium distance” zone.
`PATTERN_CLOSE`	170 / 180	ms (pulse / pause)	“Close” zone.
`PATTERN_VERY_CLOSE`	300 / 60	ms (pulse / pause)	“Very close” zone: almost continuous vibration.

3. Sensors and filtering

Parameter	Default	Unit	Description and effect
`SENSOR_TIMING_BUDGET_US`	50000	µs	Duration of one sensor measurement. Higher: less noise and better performance in sunlight and at long range, but slower updates. Must not exceed SENSOR_CONTINUOUS_PERIOD_MS (50000 µs = 50 ms).
`SENSOR_CONTINUOUS_PERIOD_MS`	70	ms	Interval between measurements. Lower: faster reaction, but more I2C bus load and higher power consumption. Must not be shorter than the measurement time (SENSOR_TIMING_BUDGET_US).
`SENSOR_MAX_VALID_DISTANCE_MM`	5000	mm	Readings beyond this value are treated as invalid. Normally not changed.
`FILTER_WINDOW`	3	pcs	Number of latest measurements in the median filter (odd number: 3 or 5). Higher: more robust against noise, but slower reaction.
`FILTER_MIN_SAMPLES`	2	pcs	How many measurements confirm an obstacle. 2 = two in a row (delay ≈ 140 ms). 1 gives the fastest reaction, but a single false measurement can trigger vibration (not recommended). Must not exceed FILTER_WINDOW.
`MAX_BAD_READS`	3	pcs	How many invalid measurements in a row are needed before the sensor is considered “empty” (no obstacle). Until then the previous value is kept.
`SENSOR_STALL_MS`	500	ms	If a sensor delivers no new data for longer than this, it is considered hung and its last value is no longer used.
`SENSOR_READ_INTERVAL_MS`	10	ms	How often the sensors are checked for new data. Normally not changed.
`I2C_CLOCK_HZ`	100000	Hz	I2C bus speed. 100 kHz is more reliable with long wires; 400 kHz is faster but more sensitive to wiring and interference.

4. Battery monitoring (1S2P)

Parameter	Default	Unit	Description and effect
`BATTERY_DIVIDER_R_TOP_KOHM`	47	kΩ	Upper divider resistor (from battery positive to GPIO34). Must match the installed resistor.
`BATTERY_DIVIDER_R_BOTTOM_KOHM`	100	kΩ	Lower divider resistor (from GPIO34 to GND).
`BATTERY_CALIBRATION_FACTOR`	1.00	—	Calibration factor: multimeter voltage ÷ Serial voltage.
`BATTERY_LOW_VOLTAGE`	3.50	V	“Low charge” threshold (1 pair of pulses). Voltage of a single Li-ion cell under light load. Must be higher than BATTERY_CRITICAL_VOLTAGE.
`BATTERY_CRITICAL_VOLTAGE`	3.30	V	“Critical charge” threshold (2 pairs of pulses). Must be higher than BATTERY_CUTOFF_WARNING.
`BATTERY_CUTOFF_WARNING`	3.15	V	“Very critical charge” threshold (3 pairs of pulses): charge immediately. The TP4056 module protection cuts off the battery only at about 2.4–2.5 V, so the warning is given much earlier.
`BATTERY_HYSTERESIS_V`	0.10	V	To return to a better level, the voltage must rise above the threshold by this amount. Prevents warning “flicker” near a threshold.
`BATTERY_FILTER_ALPHA`	0.30	0–1	Voltage smoothing: share of the new measurement. Lower: smoother but slower to react. With measurements every 5 s, 0.30 averages over roughly 15–20 s.
`BATTERY_READ_INTERVAL_MS`	5000	ms	How often the voltage is measured. A measurement is taken only while the motors are not vibrating.
`BATTERY_FIRST_WARNING_DELAY_MS`	5000	ms	Time after startup (or after the charge level worsens) until the first warning sounds.
`LOW_BATTERY_WARNING_INTERVAL_MS`	60000	ms	Repeat period of the “low charge” warning.
`CRITICAL_BATTERY_WARNING_INTERVAL_MS`	15000	ms	Repeat period of the “critical charge” warning.
`VERY_CRITICAL_WARNING_INTERVAL_MS`	5000	ms	Repeat period of the “very critical charge” warning.
`LOW_BATTERY_WARNING_PAIRS` `CRITICAL_BATTERY_WARNING_PAIRS` `VERY_CRITICAL_BATTERY_WARNING_PAIRS`	1 / 2 / 3	pairs	Number of pulse pairs for each level: low / critical / very critical.
`BATTERY_PAIR_PULSE_ON_MS`	130	ms	Duration of one pulse within a pair.
`BATTERY_PAIR_INNER_OFF_MS`	110	ms	Pause between the two pulses inside a pair.
`BATTERY_PAIR_GAP_MS`	450	ms	Pause between pairs.
`BATTERY_ADC_SAMPLES`	16	pcs	Number of ADC readings averaged per measurement (with a pause of BATTERY_ADC_SAMPLE_DELAY_MS = 2 ms between them). Higher: less noise, but the program is blocked longer during the measurement (≈ 32 ms).

5. Service signals and diagnostics

Parameter	Default	Unit	Description and effect
`MOTOR_SELF_TEST_ON_MS`	180	ms	Vibration time of each motor during the self-test at startup (order: left → center → right).
`MOTOR_SELF_TEST_OFF_MS`	150	ms	Pause between motors during the self-test.
`SENSOR_ERROR_PULSES`	9	pcs	Number of short pulses on all motors if at least one sensor failed to start at power-up.
`SENSOR_ERROR_ON_MS` `SENSOR_ERROR_OFF_MS`	120 / 120	ms	Pulse duration / pause in the sensor error signal.
`LOG_ALERT_EVENTS`	true	true / false	Print to Serial the moments when the signal turns on and off for each sensor (useful for finding the cause of false alerts).
`LOG_BATTERY`	true	true / false	Print the battery status to Serial at every measurement.
`DISTANCE_PRINT_INTERVAL_MS`	300	ms	How often distances are printed to the Serial Monitor.

6. Hardware (pins and addresses)

Change these values only if the wiring has changed.

Parameter	Default	Unit	Description and effect
`I2C_SDA`	21	GPIO	I2C data line (SDA) of the sensors.
`I2C_SCL`	22	GPIO	I2C clock line (SCL) of the sensors.
`XSHUT_LEFT` `XSHUT_CENTER` `XSHUT_RIGHT`	25 / 26 / 27	GPIO	Shutdown pins of the left, center and right sensors; used to assign unique I2C addresses at startup.
`MOTOR_LEFT` `MOTOR_CENTER` `MOTOR_RIGHT`	16 / 17 / 18	GPIO	Control outputs of the left, center and right vibration motors (to the PWMA/PWMB inputs of the TB6612FNG drivers). At startup the self-test runs left → center → right; check that the physical motors vibrate in this order.
`BATTERY_ADC_PIN`	34	GPIO	ADC input for the battery voltage (midpoint of the divider). Use an ADC1 pin (GPIO32–39).
`ADDR_LEFT` `ADDR_CENTER` `ADDR_RIGHT`	0x30 / 0x31 / 0x32	I2C address	I2C addresses assigned to the sensors at startup. Change only if they conflict with other I2C devices.
`MOTOR_ON` `MOTOR_OFF`	HIGH / LOW	level	Logic levels that switch a motor on and off. Swap them if the driver works inversely.