Skip to content

Commit 2592a36

Browse files
BobSaidHiBobSaidHi
committed
Made some improvements, asked for help with better docs
Not sure if it's all for the best, some comments could be better...
1 parent 2af1781 commit 2592a36

1 file changed

Lines changed: 115 additions & 25 deletions

File tree

‎include/CommonConfig.hpp‎

Lines changed: 115 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -38,29 +38,55 @@ namespace LED {
3838

3939
} // namespace LED
4040

41+
// MARK: Run
4142
namespace RUN {
4243
constexpr uint32_t SLEEP_TIME_MINS = 10;
4344
constexpr uint32_t SLEEP_TIME_SECS = SLEEP_TIME_MINS * CONSTS::SECS_PER_MIN;
4445
constexpr uint32_t SLEEP_TIME_MILLIS =
4546
SLEEP_TIME_SECS * CONSTS::MILLIS_PER_SEC;
4647
} // namespace RUN
4748

49+
// MARK: Load
4850
namespace LOAD {
49-
constexpr uint8_t PINS_MASK = 0b0011'1111; // First six pins
51+
/**
52+
* @brief Bitmask for the load control pins.
53+
* @details Only the first 6 pins (0-5) are used for load control.
54+
*/
55+
constexpr uint8_t PINS_Msk = 0b0011'1111;
56+
57+
/**
58+
* @brief Number of load pins available.
59+
*/
5060
constexpr uint_fast8_t NUM_PINS = 6;
51-
constexpr uint_fast8_t NUM_COMBINATIONS =
61+
62+
/**
63+
* @brief Total number of possible pin combinations (2^NUM_PINS).
64+
*
65+
* @details Computed using etl::combinations
66+
*/
67+
constexpr size_t NUM_COMBINATIONS_sizeT =
5268
etl::combinations<NUM_PINS, 0>::value +
5369
etl::combinations<NUM_PINS, 1>::value +
5470
etl::combinations<NUM_PINS, 2>::value +
5571
etl::combinations<NUM_PINS, 3>::value +
5672
etl::combinations<NUM_PINS, 4>::value +
5773
etl::combinations<NUM_PINS, 5>::value +
5874
etl::combinations<NUM_PINS, 6>::value;
75+
constexpr uint_fast8_t NUM_COMBINATIONS =
76+
static_cast<uint_fast8_t>(NUM_COMBINATIONS_sizeT);
77+
78+
static_assert(UINT8_MAX >= NUM_COMBINATIONS_sizeT,
79+
"NUM_COMBINATIONS value too large for uint8_t");
5980

6081
// According to GitHub Copilot, GPT-5.1, Ask mode
6182
static_assert(NUM_COMBINATIONS == (1u << NUM_PINS),
6283
"NUM_COMBINATIONS must be 2^NUM_PINS");
6384

85+
/**
86+
* @brief Resistor values, in milli‑ohms, corresponding to each pin. Note
87+
* that the resistors will be connected in series, so the total resistance
88+
* is the sum of the selected resistors.
89+
*/
6490
constexpr etl::array<uint_fast16_t, NUM_PINS> PIN_VALUES_mOhms = {
6591
500, 1000, 2000, 3000, 5000, 10000}; // in mOhms, in series // TODO
6692
static_assert(PIN_VALUES_mOhms.size() == NUM_PINS,
@@ -69,7 +95,11 @@ namespace LOAD {
6995
"PIN_VALUES value too large");
7096

7197
/**
98+
* MARK: detail
7299
* @brief Detail namespace for combination sum calculations
100+
* @details Contains compile‑time helpers used to build and deduplicate the
101+
* combination sums derived from PIN_VALUES_mOhms.
102+
*
73103
* @author GitHub Copilot, GPT-5.1, Ask mode
74104
* @author BobSaidHi
75105
* @details Prompt: Using C++23 consteval functions and templates, I would
@@ -82,10 +112,16 @@ namespace LOAD {
82112
* and a constexpr array of the deduplicated values?
83113
*/
84114
namespace detail {
85-
// Sum of selected pins for a given bitmask
115+
/**
116+
* @brief Compute the sum of selected pins for a given bitmask.
117+
*
118+
* @param mask Bitmask over NUM_PINS
119+
* @param values Per‑pin resistance values.
120+
* @returns Sum of selected values in milli‑ohms.
121+
*/
86122
consteval uint_fast16_t
87-
sum_for_mask(uint_fast8_t mask,
88-
const etl::array<uint_fast16_t, NUM_PINS> &values) {
123+
sumForMask(uint_fast8_t mask,
124+
const etl::array<uint_fast16_t, NUM_PINS> &values) {
89125

90126
uint_fast16_t sum = 0;
91127
for (std::size_t i = 0; i < NUM_PINS; ++i) {
@@ -96,19 +132,35 @@ namespace LOAD {
96132
return sum;
97133
}
98134

135+
/**
136+
* @brief Build the array of all combination sums for the given values.
137+
*
138+
* @tparam Sequence of indices [0, NUM_COMBINATIONS).
139+
* @param values array of per‑pin resistance values.
140+
* @returns Array where index i holds the sum for bitmask i.
141+
*/
99142
template <std::size_t... Is>
100143
consteval etl::array<uint_fast16_t, NUM_COMBINATIONS>
101-
make_all_combinations(const etl::array<uint_fast16_t, NUM_PINS> &values,
102-
std::index_sequence<Is...>) {
103-
104-
return {sum_for_mask(static_cast<uint_fast8_t>(Is), values)...};
144+
makeAllCombinations(const etl::array<uint_fast16_t, NUM_PINS> &values,
145+
std::index_sequence<Is...>) {
146+
return {sumForMask(static_cast<uint_fast8_t>(Is), values)...};
105147
}
106148

107-
// --- helpers for deduplication ---
149+
/* Helpers for deduplication */
108150

151+
/**
152+
* @brief Return a sorted copy of the input array (ascending).
153+
*
154+
* @details Implements a "simple" O(N^2) sort that is usable in
155+
* consteval context.
156+
*
157+
* @tparam N Number of elements.
158+
* @param input Input array.
159+
* @returns Sorted copy of @p input.
160+
*/
109161
template <std::size_t N>
110162
consteval etl::array<uint_fast16_t, N>
111-
sorted_copy(const etl::array<uint_fast16_t, N> &input) {
163+
makeSortedCopy(const etl::array<uint_fast16_t, N> &input) {
112164
auto result = input;
113165
for (std::size_t i = 0; i < N; ++i) {
114166
for (std::size_t j = i + 1; j < N; ++j) {
@@ -120,10 +172,17 @@ namespace LOAD {
120172
return result;
121173
}
122174

175+
/**
176+
* @brief Count the number of unique values in the input array.
177+
*
178+
* @tparam N Number of elements.
179+
* @param input Input array (not required to be sorted).
180+
* @returns Number of distinct values in @p input.
181+
*/
123182
template <std::size_t N>
124183
consteval std::size_t
125-
count_unique(const etl::array<uint_fast16_t, N> &input) {
126-
auto sorted = sorted_copy(input);
184+
countUnique(const etl::array<uint_fast16_t, N> &input) {
185+
auto sorted = makeSortedCopy(input);
127186
std::size_t count = 0;
128187
bool first = true;
129188
uint_fast16_t last = 0;
@@ -139,10 +198,18 @@ namespace LOAD {
139198
return count;
140199
}
141200

201+
/**
202+
* @brief Create a sorted array containing only the unique values.
203+
*
204+
* @tparam InN Size of the input array.
205+
* @tparam OutN Size of the output array (must equal countUnique()).
206+
* @param input Input array (not required to be sorted).
207+
* @returns Sorted array of unique values from @p input.
208+
*/
142209
template <std::size_t InN, std::size_t OutN>
143210
consteval etl::array<uint_fast16_t, OutN>
144-
unique_sorted(const etl::array<uint_fast16_t, InN> &input) {
145-
auto sorted = sorted_copy(input);
211+
deduplicateSortedArray(const etl::array<uint_fast16_t, InN> &input) {
212+
auto sorted = makeSortedCopy(input);
146213
etl::array<uint_fast16_t, OutN> out{};
147214
std::size_t out_i = 0;
148215
bool first = true;
@@ -161,37 +228,60 @@ namespace LOAD {
161228
} // namespace detail
162229

163230
/**
164-
* @brief get all combinations of values
165-
* @author GitHub Copilot, GPT-5.1, Ask mode
166-
* @author BobSaidHi
231+
* @brief Compute all possible combination sums for the given pin values.
232+
*
233+
* @param values Per‑pin resistance values.
234+
* @returns Array of size NUM_COMBINATIONS with sum for each bitmask.
167235
*/
168236
consteval etl::array<uint_fast16_t, NUM_COMBINATIONS>
169237
getAllCombinations(const etl::array<uint_fast16_t, NUM_PINS> &values) {
170-
return detail::make_all_combinations(
238+
return detail::makeAllCombinations(
171239
values, std::make_index_sequence<NUM_COMBINATIONS>{});
172240
}
173241

242+
/**
243+
* @brief All combination sums derived from PIN_VALUES_mOhms.
244+
*
245+
* Index i corresponds to bitmask i over the NUM_PINS pins.
246+
*/
174247
constexpr etl::array<uint_fast16_t, NUM_COMBINATIONS>
175248
ALL_COMBINATIONS_mOhms = getAllCombinations(PIN_VALUES_mOhms);
176249

177-
// number of unique combination values
178-
constexpr std::size_t NUM_UNIQUE_COMBINATIONS =
179-
detail::count_unique(ALL_COMBINATIONS_mOhms);
250+
/**
251+
* @brief Number of unique combination sums in ALL_COMBINATIONS_mOhms.
252+
*/
253+
constexpr uint_fast8_t NUM_UNIQUE_COMBINATIONS =
254+
detail::countUnique(ALL_COMBINATIONS_mOhms);
180255

181256
static_assert(NUM_UNIQUE_COMBINATIONS <= NUM_COMBINATIONS,
182257
"NUM_UNIQUE_COMBINATIONS must be <= NUM_COMBINATIONS");
183258

184-
// deduplicated, sorted combination values
259+
/**
260+
* @brief Sorted array of unique combination sums (deduplicated).
261+
*/
185262
constexpr etl::array<uint_fast16_t, NUM_UNIQUE_COMBINATIONS>
186263
UNIQUE_COMBINATIONS_mOhms =
187-
detail::unique_sorted<NUM_COMBINATIONS, NUM_UNIQUE_COMBINATIONS>(
264+
detail::deduplicateSortedArray<NUM_COMBINATIONS,
265+
NUM_UNIQUE_COMBINATIONS>(
188266
ALL_COMBINATIONS_mOhms);
189267

190-
// Pin 6 is connected by default in hardware
268+
/**
269+
* @brief Index of the pin that is connected (logical 1) by default.
270+
*
271+
* Used to build the default load state mask.
272+
*/
191273
constexpr uint_fast8_t INVERTED_PIN_INDEX = 5;
274+
275+
/**
276+
* @brief Bitmask for the default‑connected pin.
277+
*/
192278
constexpr uint8_t INVERTED_PIN_MASK = (1 << INVERTED_PIN_INDEX);
193279
static_assert(INVERTED_PIN_MASK == 0b0010'0000,
194280
"INVERTED_PIN_MASK value incorrect");
281+
282+
/**
283+
* @brief Default load state bitmask applied at startup.
284+
*/
195285
constexpr uint8_t DEFAULT_LOAD_STATE = INVERTED_PIN_MASK;
196286

197287
} // namespace LOAD

0 commit comments

Comments
 (0)