Initial commit

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: Continuous Integration
+on:
+  push:
+    branches:
+      - "**"
+  pull_request:
+    branches:
+      - "**"
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    name: ${{ matrix.os }} Test
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build
+        run: |
+          export CFLAGS="-D_FORTIFY_SOURCE=2 -fstack-protector -pedantic -Wall -Wextra -Wbad-function-cast -Wcast-align \
+            -Wcast-qual -Wdisabled-optimization -Wendif-labels -Wfloat-conversion -Wfloat-equal -Wformat=2 -Wformat-nonliteral \
+            -Winline -Wmissing-declarations -Wmissing-noreturn -Wmissing-prototypes -Wnested-externs -Wpointer-arith -Wshadow \
+            -Wsign-conversion -Wstrict-prototypes -Wstack-protector -Wundef -Wwrite-strings -Werror"
+          cmake -DCMAKE_C_FLAGS="$CFLAGS" -DCMAKE_BUILD_TYPE=Release -S . -B _build
+          cmake --build _build/ -v

.gitignore

@@ -0,0 +1,37 @@
+# Object files
+*.o
+*.ko
+*.obj
+*.elf
+
+# Precompiled Headers
+*.gch
+*.pch
+
+# Libraries
+*.lib
+*.a
+*.la
+*.lo
+
+# Shared objects (inc. Windows DLLs)
+*.dll
+*.so
+*.so.*
+*.dylib
+
+# Executables
+*.exe
+*.out
+*.app
+*.i*86
+*.x86_64
+*.hex
+
+# Debug files
+*.dSYM/
+
+# Other
+.DS_Store
+*~
+build/

AUTHORS

@@ -0,0 +1,2 @@
+Connor Imes
+<[email protected]>

CMakeLists.txt

@@ -0,0 +1,74 @@
+cmake_minimum_required(VERSION 3.12...3.28)
+
+project(osp3 VERSION 0.0.1
+             LANGUAGES C)
+
+set(CMAKE_C_STANDARD 99)
+set(CMAKE_C_STANDARD_REQUIRED ON)
+set(CMAKE_C_EXTENSIONS ON)
+add_compile_options(-Wall -Wextra -Wpedantic)
+
+include(GNUInstallDirs)
+configure_file(
+  ${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in
+  ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake
+  @ONLY
+)
+add_custom_target(uninstall COMMAND ${CMAKE_COMMAND} -P ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake)
+
+enable_testing()
+
+
+# Libraries
+
+add_library(osp3 src/osp3.c)
+target_include_directories(osp3 PRIVATE ${PROJECT_SOURCE_DIR}/inc
+                                PUBLIC $<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/inc>
+                                       $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}/osp3>)
+set_target_properties(osp3 PROPERTIES PUBLIC_HEADER "${PROJECT_SOURCE_DIR}/inc/osp3.h"
+                                      VERSION ${PROJECT_VERSION}
+                                      SOVERSION ${PROJECT_VERSION_MAJOR})
+install(TARGETS osp3 LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+                             COMPONENT OSP3_Runtime
+                             NAMELINK_COMPONENT OSP3_Development
+                      ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+                              COMPONENT OSP3_Development
+                      PUBLIC_HEADER DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/osp3
+                                    COMPONENT OSP3_Development)
+
+
+# Subdirectories
+
+add_subdirectory(test)
+add_subdirectory(utils)
+
+
+# pkg-config
+
+set(PKG_CONFIG_PREFIX "${CMAKE_INSTALL_PREFIX}")
+set(PKG_CONFIG_EXEC_PREFIX "\${prefix}")
+if(IS_ABSOLUTE "${CMAKE_INSTALL_INCLUDEDIR}")
+  set(PKG_CONFIG_INCLUDEDIR "${CMAKE_INSTALL_INCLUDEDIR}/osp3")
+else()
+  set(PKG_CONFIG_INCLUDEDIR "\${prefix}/${CMAKE_INSTALL_INCLUDEDIR}/osp3")
+endif()
+if(IS_ABSOLUTE "${CMAKE_INSTALL_LIBDIR}")
+  set(PKG_CONFIG_LIBDIR "${CMAKE_INSTALL_LIBDIR}")
+else()
+  set(PKG_CONFIG_LIBDIR "\${exec_prefix}/${CMAKE_INSTALL_LIBDIR}")
+endif()
+set(PKG_CONFIG_NAME "osp3")
+set(PKG_CONFIG_DESCRIPTION "Library for managing an ODROID Smart Power 3")
+set(PKG_CONFIG_REQUIRES "")
+set(PKG_CONFIG_REQUIRES_PRIVATE "")
+set(PKG_CONFIG_CFLAGS "-I\${includedir}")
+set(PKG_CONFIG_LIBS "-L\${libdir} -losp3")
+set(PKG_CONFIG_LIBS_PRIVATE "")
+configure_file(
+  ${CMAKE_CURRENT_SOURCE_DIR}/pkgconfig.in
+  ${CMAKE_CURRENT_BINARY_DIR}/osp3.pc
+  @ONLY
+)
+install(FILES ${CMAKE_CURRENT_BINARY_DIR}/osp3.pc
+        DESTINATION ${CMAKE_INSTALL_LIBDIR}/pkgconfig
+        COMPONENT OSP3_Development)

LICENSE

@@ -0,0 +1,24 @@
+Copyright (c) 2024, Connor Imes
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the University of Chicago nor the
+      names of its contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE UNIVERSITY OF CHICAGO BE LIABLE FOR ANY
+DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -0,0 +1,147 @@
+# ODROID Smart Power 3 Library and Utilities
+
+A library and tools for an [ODROID Smart Power 3](https://wiki.odroid.com/accessory/power_supply_battery/smartpower3) device with a USB connection.
+
+> NOTE: If you're using a first generation [ODROID Smart Power](https://wiki.odroid.com/old_product/accessory/odroidsmartpower) device, see the [hosp](https://github.com/energymon/hosp) project instead.
+
+This project is tested using a device running SmartPower3 firmware v2.2 (20230518), though may work with devices running v1.7 (20211214) or newer.
+Older firmware versions use a different logging protocol.
+
+
+## Building
+
+### Prerequisites
+
+This project uses [CMake](https://cmake.org/).
+
+On Debian-based Linux systems (including Ubuntu):
+
+```sh
+sudo apt install cmake
+```
+
+On macOS, using [Homebrew](https://brew.sh/):
+
+```sh
+brew install cmake
+```
+
+### Compiling
+
+To build, run:
+
+```sh
+cmake -S . -B build/
+cmake --build build/
+```
+
+To build a shared object library (instead of a static library), add `-DBUILD_SHARED_LIBS=On` to the first cmake command.
+Add `-DCMAKE_BUILD_TYPE=Release` for an optimized build.
+Refer to CMake documentation for more a complete description of build options.
+
+To install, run with proper privileges:
+
+```sh
+cmake --build . --target install
+```
+
+On Linux, installation typically places libraries in `/usr/local/lib` and header files in `/usr/local/include/osp3`.
+
+Install must be run before uninstalling in order to have a manifest.
+To uninstall, run with proper privileges (install must have been run first to create a manifest):
+
+```sh
+cmake --build . --target uninstall
+```
+
+### Linking
+
+To link against `osp3`, use `pkg-config` to get compiler and linker flags.
+E.g., in a Makefile:
+
+```sh
+CFLAGS+=$(shell pkg-config --cflags osp3)
+LDFLAGS+=$(shell pkg-config --libs --static osp3)
+```
+
+The `--static` flag is unnecessary if you built/installed a shared object library.
+
+
+## Linux Privileges
+
+To use an ODROID Smart Power 3 without needing sudo/root at runtime, set appropriate [udev](https://en.wikipedia.org/wiki/Udev) privileges.
+
+You can give access to a specific group, e.g. `plugdev`, by creating/modifying a `udev` config file like `/etc/udev/rules.d/10-local.rules`.
+For example, add the following rules:
+
+```
+# OROID Smart Power 3
+SUBSYSTEMS=="usb", ATTRS{idVendor}=="10c4", ATTRS{idProduct}=="ea60", GROUP="plugdev"
+```
+
+For the new permissions to take effect, the device must be remounted by the kernel - either disconnect and reconnect the device or reboot the system.
+
+
+## Utilities
+
+The following command-line utilities are included.
+See their help output for usage.
+
+* `osp3-dump` - dump the device's serial output.
+* `osp3-poll` - poll the device's serial output for complete log entries.
+
+
+## C API
+
+The following is a simple example that reads data from an ODROID Smart Power 3 device.
+A real application will likely do more complex things with the data (like parse it).
+
+```C
+#include <stdio.h>
+#include <stdlib.h>
+#include <osp3.h>
+
+int main(void) {
+  int ret = 0;
+
+  // Open the device.
+  const char* path = "/dev/ttyUSB0";
+  unsigned int baud = OSP3_BAUD_DEFAULT;
+  osp3_device* dev;
+  if ((dev = osp3_open_device(path, baud)) == NULL) {
+    perror("Failed to open ODROID Smart Power 3 connection");
+    return 1;
+  }
+
+  // Work with the device.
+  unsigned char packet[OSP3_W_MAX_PACKET_SIZE] = { 0 };
+  size_t transferred = 0;
+  unsigned int timeout_ms = 0;
+  while (1) {
+    if (osp3_read(dev, packet, sizeof(packet), &transferred, timeout_ms) < 0) {
+      perror("Failed to read from ODROID Smart Power 3");
+      ret = 1;
+      break;
+    }
+    for (size_t i = 0; i < transferred; i++) {
+      putchar((const char) packet[i]);
+    }
+  }
+
+  // Close the device.
+  if (osp3_close(dev)) {
+    perror("Failed to close ODROID Smart Power 3 connection");
+    ret = 1;
+  }
+
+  return ret;
+}
+```
+
+
+## Project Source
+
+Find this and related project sources at the [energymon organization on GitHub](https://github.com/energymon).  
+This project originates at: https://github.com/energymon/osp3
+
+Bug reports and pull requests for bug fixes and enhancements are welcome.

RELEASES.md

@@ -0,0 +1,11 @@
+# Release Notes
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+
+## Unreleased
+
+- Initial public release.

cmake_uninstall.cmake.in

@@ -0,0 +1,21 @@
+if(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")
+  message(FATAL_ERROR "Cannot find install manifest: @CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")
+endif(NOT EXISTS "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt")
+
+file(READ "@CMAKE_CURRENT_BINARY_DIR@/install_manifest.txt" files)
+string(REGEX REPLACE "\n" ";" files "${files}")
+foreach(file ${files})
+  message(STATUS "Uninstalling $ENV{DESTDIR}${file}")
+  if(IS_SYMLINK "$ENV{DESTDIR}${file}" OR EXISTS "$ENV{DESTDIR}${file}")
+    exec_program(
+      "@CMAKE_COMMAND@" ARGS "-E remove \"$ENV{DESTDIR}${file}\""
+      OUTPUT_VARIABLE rm_out
+      RETURN_VALUE rm_retval
+      )
+    if(NOT "${rm_retval}" STREQUAL 0)
+      message(FATAL_ERROR "Problem when removing $ENV{DESTDIR}${file}")
+    endif(NOT "${rm_retval}" STREQUAL 0)
+  else(IS_SYMLINK "$ENV{DESTDIR}${file}" OR EXISTS "$ENV{DESTDIR}${file}")
+    message(STATUS "File $ENV{DESTDIR}${file} does not exist.")
+  endif(IS_SYMLINK "$ENV{DESTDIR}${file}" OR EXISTS "$ENV{DESTDIR}${file}")
+endforeach(file)