feat: add mutex support for I2C operations and update hooks

.gitignore

@@ -55,6 +55,8 @@ dkms.conf
 
 # Ignore build output
 build/
+CMakeFiles/
+CMakeCache.txt
 
 # Submodules
-note-c
+note-c

README.md

@@ -72,6 +72,46 @@ CONFIG_BLUES_NOTECARD_LOGGING=y
 
 > **Note:** The `CONFIG_NEWLIB_LIBC` option is required by `note-c` and must be enabled in your `prj.conf` along with the `CONFIG_BLUES_NOTECARD` option.
 
+## Thread Safety
+
+The component automatically provides thread-safe access to the Notecard in multi-threaded Zephyr applications.
+The underlying note-c library protects the Notecard from concurrent access using internal mutexes,
+so no additional locking is required for normal use.
+
+### I2C Bus Sharing
+
+If you have other I2C peripherals on the same bus as the Notecard, register your I2C mutex with note-c using `NoteSetFnI2CMutex()` to minimize the time spent under lock.
+
+For your convenience, we have provided a default implementation of I2C mutex APIs to coordinate access (example shown below):
+
+```c
+#include "hooks/hooks.h"
+
+// Access your I2C peripherals
+note_platform_i2c_lock();
+i2c_write(my_peripheral_device, data, len);
+note_platform_i2c_unlock();
+```
+
+This ensures the note-c library won't attempt I2C communication while you're accessing your other peripherals.
+
+In order to enable/disable the provided I2C bus mutex (e.g. when using your own mutex), use Kconfig:
+
+```sh
+CONFIG_BLUES_NOTECARD_I2C_MUTEX=y  # Enabled by default
+```
+
+Or via menuconfig:
+
+```text
+Symbol: BLUES_NOTECARD_I2C_MUTEX [=y]
+Type  : bool
+Defined at modules/note-zephyr/notecard/hooks/Kconfig:22
+  Prompt: Enable I2C mutex protection
+```
+
+> **Note:** IMPORTANT: The I2C mutex is enabled by default.
+
 ## Getting started with examples
 
 To try the [examples](examples/README.md) standalone, without importing `note-zephyr` as a module, the easiest thing to do is to follow the instructions for [development](#development) below. This will install the dependencies for Blues' Feather MCU boards and allow you to build the examples.

notecard/hooks/CMakeLists.txt

@@ -3,4 +3,5 @@ zephyr_library_sources(
 	time.c
 	print.c
 	hooks.c
+	mutex.c
 )

notecard/hooks/Kconfig

@@ -18,3 +18,9 @@ config BLUES_NOTECARD_LOGGING
 	default y
 	help
 	  Enable Notecard debug logging
+
+config BLUES_NOTECARD_I2C_MUTEX
+	bool "Enable I2C mutex protection"
+	default y
+	help
+	  Enable mutex protection for I2C operations

notecard/hooks/hooks.c

@@ -17,6 +17,12 @@ static int note_hooks_register(void)
 
 	NoteSetFnDebugOutput(note_debug_print);
 
+	NoteSetFnNoteMutex(note_platform_note_lock, note_platform_note_unlock);
+
+#ifdef CONFIG_BLUES_NOTECARD_I2C_MUTEX
+	NoteSetFnI2CMutex(note_platform_i2c_lock, note_platform_i2c_unlock);
+#endif
+
 	return 0;
 }
 

notecard/hooks/hooks.h

@@ -21,4 +21,10 @@ void note_time_delay(uint32_t ms);
 /* Print Utility Hooks */
 size_t note_debug_print(const char *text);
 
+/* Mutex Hooks */
+void note_platform_note_lock(void);
+void note_platform_note_unlock(void);
+void note_platform_i2c_lock(void);
+void note_platform_i2c_unlock(void);
+
 #endif /* _NOTE_CORE_HOOKS_H_ */

notecard/hooks/mutex.c

@@ -0,0 +1,34 @@
+/**
+ * Copyright (c) 2025 Blues Inc.
+ *
+ * MIT License. Use of this source code is governed by licenses granted
+ * by the copyright holder including that found in the LICENSE file.
+ */
+
+#include <zephyr/kernel.h>
+
+static K_MUTEX_DEFINE(g_notecard_mutex);
+
+void note_platform_note_lock(void)
+{
+	k_mutex_lock(&g_notecard_mutex, K_FOREVER);
+}
+
+void note_platform_note_unlock(void)
+{
+	k_mutex_unlock(&g_notecard_mutex);
+}
+
+#ifdef CONFIG_BLUES_NOTECARD_I2C_MUTEX
+static K_MUTEX_DEFINE(g_i2c_mutex);
+
+void note_platform_i2c_lock(void)
+{
+	k_mutex_lock(&g_i2c_mutex, K_FOREVER);
+}
+
+void note_platform_i2c_unlock(void)
+{
+	k_mutex_unlock(&g_i2c_mutex);
+}
+#endif /* CONFIG_BLUES_NOTECARD_I2C_MUTEX */