Merge branch 'release/3.0.0'

MaJerle · Jul 5, 2020 · 4ecb3d2 · 4ecb3d2
2 parents 81dcae8 + 3037109
commit 4ecb3d2
Show file tree

Hide file tree

Showing 198 changed files with 132,546 additions and 2,416 deletions.
diff --git a/.gitignore b/.gitignore
@@ -380,7 +380,6 @@ log_file.txt
 .metadata/
 .mxproject
 .settings/
-template/
 project.ioc
 mx.scratch
 *.tilen majerle
diff --git a/LICENSE b/LICENSE
@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2018 Tilen Majerle
+Copyright (c) 2020 Tilen MAJERLE
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -1,25 +1,37 @@
-# 1-Wire over UART
+# Lightweight onewire library
+
+LwOW is lightweight, platform independent library for Onewire protocol for embedded systems.
+Its primary focus is UART hardware for physical communication for sensors and other slaves.
 
 More about 1-Wire over UART can be found on link below.
 
 https://www.maximintegrated.com/en/app-notes/index.mvp/id/214
 
+<h3>Read first: <a href="http://docs.majerle.eu/projects/lwow/">Documentation</a></h3>
+
 ## Features
 
-- 1-Wire protocol fits UART specifications at `9600` and `115200` bauds
-- Hardware is responsible for timing characteristics
-- Works with operating system due to hardware timing management
-- Allows DMA on the high-performance microcontrollers
-- Different device drivers included
-	- `DS18x20` temperature sensor
-- User friendly MIT license
+* Written in ANSI C99
+* Platform independent, uses custom low-level layer for device drivers
+* 1-Wire protocol fits UART specifications at ``9600`` and ``115200`` bauds
+* Hardware is responsible for timing characteristics
+    * Allows DMA on the high-performance microcontrollers
+* Different device drivers included
+    * DS18x20 temperature sensor is natively supported
+* Works with operating system due to hardware timing management
+    * Separate thread-safe API is available
+* API for device scan, reading and writing single bits
+* User friendly MIT license
 
-## Documentation
+## Contribute
 
-Full API documentation with description and examples is available and is regulary updated with the source changes
+Fresh contributions are always welcome. Simple instructions to proceed::
 
-http://majerle.eu/documentation/ow/html/index.html
+1. Fork Github repository
+2. Respect [C style & coding rules](https://github.com/MaJerle/c-code-style) used by the library
+3. Create a pull request to develop branch with new features or bug fixes
 
-## Contribution
+Alternatively you may:
 
-I invite you to give feature request or report a bug. Please use issues tracker.
+1. Report a bug
+2. Ask for a feature request
diff --git a/dev/VisualStudio/onewire_uart_dev.sln → dev/VisualStudio/lwow_dev.sln b/dev/VisualStudio/onewire_uart_dev.sln → dev/VisualStudio/lwow_dev.sln
@@ -3,7 +3,7 @@ Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 16
 VisualStudioVersion = 16.0.28803.452
 MinimumVisualStudioVersion = 10.0.40219.1
-Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "onewire_uart_dev", "onewire_uart_dev.vcxproj", "{21B0EEA6-96AD-4699-8C90-79FFD626E9B7}"
+Project("{8BC9CEB8-8B4A-11D0-8D11-00A0C91BC942}") = "lwow_dev", "lwow_dev.vcxproj", "{21B0EEA6-96AD-4699-8C90-79FFD626E9B7}"
 EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
@@ -13,8 +13,8 @@ Global
 		Release|x86 = Release|x86
 	EndGlobalSection
 	GlobalSection(ProjectConfigurationPlatforms) = postSolution
-		{21B0EEA6-96AD-4699-8C90-79FFD626E9B7}.Debug|x64.ActiveCfg = Debug|Win32
-		{21B0EEA6-96AD-4699-8C90-79FFD626E9B7}.Debug|x64.Build.0 = Debug|Win32
+		{21B0EEA6-96AD-4699-8C90-79FFD626E9B7}.Debug|x64.ActiveCfg = Debug|x64
+		{21B0EEA6-96AD-4699-8C90-79FFD626E9B7}.Debug|x64.Build.0 = Debug|x64
 		{21B0EEA6-96AD-4699-8C90-79FFD626E9B7}.Debug|x86.ActiveCfg = Debug|Win32
 		{21B0EEA6-96AD-4699-8C90-79FFD626E9B7}.Debug|x86.Build.0 = Debug|Win32
 		{21B0EEA6-96AD-4699-8C90-79FFD626E9B7}.Release|x64.ActiveCfg = Release|x64

diff --git a/dev/VisualStudio/onewire_uart_dev.vcxproj → dev/VisualStudio/lwow_dev.vcxproj b/dev/VisualStudio/onewire_uart_dev.vcxproj → dev/VisualStudio/lwow_dev.vcxproj
@@ -72,7 +72,7 @@
   <PropertyGroup Label="UserMacros" />
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|Win32'">
     <LinkIncremental>true</LinkIncremental>
-    <IncludePath>..\..\snippets\include;..\..\onewire_uart\src\include;..\inc;.;$(IncludePath)</IncludePath>
+    <IncludePath>..\..\snippets\include;..\..\lwow\src\include;..\inc;.;$(IncludePath)</IncludePath>
   </PropertyGroup>
   <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|x64'">
     <LinkIncremental>true</LinkIncremental>
@@ -137,10 +137,10 @@
   </ItemDefinitionGroup>
   <ItemGroup>
     <ClCompile Include="..\..\snippets\scan_devices.c" />
-    <ClCompile Include="..\..\onewire_uart\src\devices\ow_device_ds18x20.c" />
-    <ClCompile Include="..\..\onewire_uart\src\ow\ow.c" />
-    <ClCompile Include="..\..\onewire_uart\src\system\ow_ll_win32.c" />
-    <ClCompile Include="..\..\onewire_uart\src\system\ow_sys_win32.c" />
+    <ClCompile Include="..\..\lwow\src\devices\lwow_device_ds18x20.c" />
+    <ClCompile Include="..\..\lwow\src\lwow\lwow.c" />
+    <ClCompile Include="..\..\lwow\src\system\lwow_ll_win32.c" />
+    <ClCompile Include="..\..\lwow\src\system\lwow_sys_win32.c" />
     <ClCompile Include="main.c" />
   </ItemGroup>
   <Import Project="$(VCTargetsPath)\Microsoft.Cpp.targets" />

diff --git a/...alStudio/onewire_uart_dev.vcxproj.filters → dev/VisualStudio/lwow_dev.vcxproj.filters b/...alStudio/onewire_uart_dev.vcxproj.filters → dev/VisualStudio/lwow_dev.vcxproj.filters
@@ -5,9 +5,6 @@
       <UniqueIdentifier>{4FC737F1-C7A5-4376-A066-2A32D752A2FF}</UniqueIdentifier>
       <Extensions>cpp;c;cc;cxx;def;odl;idl;hpj;bat;asm;asmx</Extensions>
     </Filter>
-    <Filter Include="Source Files\OW">
-      <UniqueIdentifier>{500e5c58-a0a4-4bef-841f-93caaed7962e}</UniqueIdentifier>
-    </Filter>
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="main.c">
@@ -16,17 +13,17 @@
     <ClCompile Include="..\..\snippets\scan_devices.c">
       <Filter>Source Files</Filter>
     </ClCompile>
-    <ClCompile Include="..\..\onewire_uart\src\ow\ow.c">
-      <Filter>Source Files\OW</Filter>
+    <ClCompile Include="..\..\lwow\src\devices\lwow_device_ds18x20.c">
+      <Filter>Source Files</Filter>
     </ClCompile>
-    <ClCompile Include="..\..\onewire_uart\src\devices\ow_device_ds18x20.c">
-      <Filter>Source Files\OW</Filter>
+    <ClCompile Include="..\..\lwow\src\lwow\lwow.c">
+      <Filter>Source Files</Filter>
     </ClCompile>
-    <ClCompile Include="..\..\onewire_uart\src\system\ow_ll_win32.c">
-      <Filter>Source Files\OW</Filter>
+    <ClCompile Include="..\..\lwow\src\system\lwow_ll_win32.c">
+      <Filter>Source Files</Filter>
     </ClCompile>
-    <ClCompile Include="..\..\onewire_uart\src\system\ow_sys_win32.c">
-      <Filter>Source Files\OW</Filter>
+    <ClCompile Include="..\..\lwow\src\system\lwow_sys_win32.c">
+      <Filter>Source Files</Filter>
     </ClCompile>
   </ItemGroup>
 </Project>
diff --git a/dev/VisualStudio/ow_config.h → dev/VisualStudio/lwow_opts.h b/dev/VisualStudio/ow_config.h → dev/VisualStudio/lwow_opts.h
@@ -1,49 +1,45 @@
 /**
- * \file            ow.h
- * \brief           OneWire-UART main include file
+ * \file            lwow_opts.h
+ * \brief           OW application options
  */
- 
+
 /*
- * Copyright (c) 2019 Tilen MAJERLE
- *  
+ * Copyright (c) 2020 Tilen MAJERLE
+ *
  * Permission is hereby granted, free of charge, to any person
  * obtaining a copy of this software and associated documentation
  * files (the "Software"), to deal in the Software without restriction,
  * including without limitation the rights to use, copy, modify, merge,
- * publish, distribute, sublicense, and/or sell copies of the Software, 
- * and to permit persons to whom the Software is furnished to do so, 
+ * publish, distribute, sublicense, and/or sell copies of the Software,
+ * and to permit persons to whom the Software is furnished to do so,
  * subject to the following conditions:
- * 
+ *
  * The above copyright notice and this permission notice shall be
  * included in all copies or substantial portions of the Software.
- * 
+ *
  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
  * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
  * AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
- * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
+ * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
  * OTHER DEALINGS IN THE SOFTWARE.
  *
  * This file is part of OneWire library.
  *
  * Author:          Tilen MAJERLE <tilen@majerle.eu>
- * Version:         v2.0.0
+ * Version:         v3.0.0
  */
-#ifndef OW_HDR_CONFIG_H
-#define OW_HDR_CONFIG_H
+#ifndef LWOW_HDR_OPTS_H
+#define LWOW_HDR_OPTS_H
 
-#ifdef __cplusplus
-extern "C" {
-#endif /* __cplusplus */
+/* Rename this file to "lwow_opts.h" for your application */
 
-#define OW_CFG_OS               1
-
-#include "ow/ow_config_default.h"
-
-#ifdef __cplusplus
-}
-#endif /* __cplusplus */
+/*
+ * Open "include/lwow/lwow_opt.h" and
+ * copy & replace here settings you want to change values
+ */
+#define LWOW_CFG_OS               1
 
-#endif /* OW_HDR_CONFIG_H */
+#endif /* LWOW_HDR_OPTS_H */
diff --git a/dev/VisualStudio/main.c b/dev/VisualStudio/main.c
@@ -1,14 +1,14 @@
 #include "windows.h"
-#include "stdio.h"
+#include <stdio.h>
 
-#include "ow/ow.h"
-#include "ow/devices/ow_device_ds18x20.h"
+#include "lwow/lwow.h"
+#include "lwow/devices/lwow_device_ds18x20.h"
 #include "scan_devices.h"
 
 /* Create new 1-Wire instance */
-extern const ow_ll_drv_t ow_ll_drv_win32;
-ow_t ow;
-ow_rom_t rom_ids[20];
+extern const lwow_ll_drv_t lwow_ll_drv_win32;
+lwow_t ow;
+lwow_rom_t rom_ids[20];
 size_t rom_found;
 
 /**
@@ -18,12 +18,12 @@ int
 main(void) {
     printf("Starting OneWire application..\r\n");
 
-    ow_init(&ow, &ow_ll_drv_win32, NULL);       /* Initialize 1-Wire library and set user argument to 1 */
+    lwow_init(&ow, &lwow_ll_drv_win32, NULL);   /* Initialize 1-Wire library and set user argument to 1 */
 
     /* Get onewire devices connected on 1-wire port */
     while (1) {
         printf("Scanning 1-Wire port...\r\n");
-        if (scan_onewire_devices(&ow, rom_ids, OW_ARRAYSIZE(rom_ids), &rom_found) == owOK) {
+        if (scan_onewire_devices(&ow, rom_ids, LWOW_ARRAYSIZE(rom_ids), &rom_found) == lwowOK) {
             printf("Devices scanned, found %d device%s!\r\n", (int)rom_found, "s" + (rom_found == 1));
         } else {
             printf("Device scan error\r\n");
@@ -35,22 +35,22 @@ main(void) {
             for (size_t c = 0; c < 5; c++) {
                 printf("Start temperature conversion\r\n");
 
-                ow_ds18x20_start(&ow, NULL);    /* Start conversion on all devices */
+                lwow_ds18x20_start(&ow, NULL);  /* Start conversion on all devices */
                 Sleep(1500);                    /* Release thread for 1 second */
 
                 /* Read temperature on all devices */
-                ow_protect(&ow, 1);
+                lwow_protect(&ow, 1);
                 for (size_t i = 0; i < rom_found; ++i) {
-                    if (ow_ds18x20_is_b(&ow, &rom_ids[i])) {
+                    if (lwow_ds18x20_is_b(&ow, &rom_ids[i])) {
                         float temp;
-                        uint8_t resolution = ow_ds18x20_get_resolution_raw(&ow, &rom_ids[i]);
-                        if (ow_ds18x20_read_raw(&ow, &rom_ids[i], &temp)) {
-                            printf("Sensor %u temperature is %d.%d degrees (%u bits resolution)\r\n",
+                        uint8_t resolution = lwow_ds18x20_get_resolution_raw(&ow, &rom_ids[i]);
+                        if (lwow_ds18x20_read_raw(&ow, &rom_ids[i], &temp)) {
+                            printf("Sensor %3u temperature is %d.%03d degrees (%u bits resolution)\r\n",
                                 (unsigned)i, (int)temp, (int)((temp * 1000.0f) - (((int)temp) * 1000)), (unsigned)resolution);
                         }
                     }
                 }
-                ow_unprotect(&ow, 1);
+                lwow_unprotect(&ow, 1);
             }
         }
     }

diff --git a/docs/api-reference/devices/ds18x20.rst b/docs/api-reference/devices/ds18x20.rst
@@ -3,4 +3,4 @@
 DS18x20 temperature sensor
 ==========================
 
-.. doxygengroup:: OW_DEVICE_DS18x20
+.. doxygengroup:: LWOW_DEVICE_DS18x20
diff --git a/docs/api-reference/index.rst b/docs/api-reference/index.rst
@@ -7,8 +7,8 @@ List of all the modules:
 
 .. toctree::
 	:maxdepth: 2
-	:glob:
 
-	*
-	*/index
-
+	lwow
+	opt
+	port/index
+	devices/index
diff --git a/docs/api-reference/lwow.rst b/docs/api-reference/lwow.rst
@@ -0,0 +1,6 @@
+.. _api_lwow:
+
+LwOW
+====
+
+.. doxygengroup:: LWOW
diff --git a/docs/api-reference/opt.rst b/docs/api-reference/opt.rst
@@ -0,0 +1,12 @@
+.. _api_lwow_opt:
+
+LwOW configuration
+==================
+
+This is the default configuration of the middleware.
+When any of the settings shall be modified, it shall be done in dedicated application config ``lwow_opts.h`` file.
+
+.. note::
+	Check :ref:`getting_started` to create configuration file.
+
+.. doxygengroup:: LWOW_OPT
diff --git a/docs/api-reference/ow.rst b/docs/api-reference/ow.rst
diff --git a/docs/api-reference/ow_config.rst b/docs/api-reference/ow_config.rst
diff --git a/docs/api-reference/ow_ll.rst b/docs/api-reference/ow_ll.rst
diff --git a/docs/api-reference/ow_sys.rst b/docs/api-reference/ow_sys.rst
diff --git a/docs/api-reference/port/index.rst b/docs/api-reference/port/index.rst
@@ -0,0 +1,12 @@
+.. _api_lwow_port:
+
+Platform specific
+=================
+
+List of all the modules:
+
+.. toctree::
+	:maxdepth: 2
+
+	ll
+	sys
diff --git a/docs/api-reference/port/ll.rst b/docs/api-reference/port/ll.rst
@@ -0,0 +1,6 @@
+.. _api_lwow_ll:
+
+Low-level driver
+================
+
+.. doxygengroup:: LWOW_LL
diff --git a/docs/api-reference/port/sys.rst b/docs/api-reference/port/sys.rst
@@ -0,0 +1,15 @@
+.. _api_lwow_sys:
+
+System functions
+================
+
+System function are used in conjunction with thread safety.
+These are required when operating system is used and multiple threads
+want to access to the same OneWire instance.
+
+.. tip::
+	Check :ref:`um_thread_safety` and :ref:`um_porting_guide` for instructions on how to port.
+
+Below is a list of function prototypes and its implementation details.
+
+.. doxygengroup:: LWOW_SYS