Merge pull request #67 from rshs-robotics-club/unstable

Final pull request before repository is archived

.github/workflows/compile-test-actions.yml

@@ -19,14 +19,15 @@ jobs:
   compile-inside-container:
     runs-on: ubuntu-latest
     container: 
-      image: eisverygoodletter/debian-stretch-cross:latest
+      image: eisverygoodletter/debian-stretch-cross:bluetooth
       options: --user root
     steps:
       - uses: actions/checkout@v3
         with: 
           path: ./
       - name: compile it
         run: |
+          tree .
           sudo chmod +x ./scripts/runWithinContainer.sh
           sudo bash ./scripts/runWithinContainer.sh -w
         shell: bash

CMakeLists.txt

@@ -23,12 +23,15 @@ set(CMAKE_CXX_COMPILER "arm-linux-gnueabi-g++")
 set(CMAKE_CXX_STANDARD 11)
 set(CMAKE_CXX_STANDARD_REQUIRED true)
 
-set(LIBNAME "ev3-cpp-template-wrapper-lib")
+set(LIBNAME "ev3dev-cpp-template-wrapper-lib")
 project(${LIBNAME} VERSION 3.0.0)
 
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 message(STATUS ${OPTIMIZATION_LEVEL})
 add_compile_options(${OPTIMIZATION_LEVEL})
+# unfortunately there are problems in 
+# libbluetooth so we must use -fpermissive
+add_compile_options(-fpermissive)
 add_definitions(-DDEBUG_MODE_ENABLED)
 add_library(
     ${LIBNAME} 
@@ -43,10 +46,15 @@ add_library(
 
     lib/motor/motor.cpp
 
+    lib/color-sensor/color-sensor.hpp
+    lib/gyro-sensor/gyro.hpp
+
     lib/omni/omni.cpp
 
     lib/vector/vector.cpp
 
+    lib/bluetooth-socket/bluetooth-socket.cpp
+
     lib/ev3dev.cpp
     lib/smbus.cpp
 )
@@ -69,9 +77,10 @@ target_include_directories(
 
 SUBDIRLIST(SUBDIRS ${PROJECT_SOURCE_DIR}/lib/)
 foreach(subdir ${SUBDIRS})
-    message(STATUS ${subdir})
     target_include_directories(${LIBNAME} PUBLIC ${PROJECT_SOURCE_DIR}/lib/${subdir})
 endforeach()
+target_include_directories(${LIBNAME} PUBLIC /home/compiler/crossCompileLibraries/libbluetooth/include/)
+target_link_libraries(${LIBNAME} PRIVATE /home/compiler/crossCompileLibraries/libbluetooth/lib/arm-linux-gnueabi/libbluetooth.a)
 
 set_target_properties(${LIBNAME}
                     PROPERTIES

README.md

@@ -1,17 +1,27 @@
-# NEWS
-## Why is the documentation all over the place?
-### Reasons:
-1. Jump to V3.0.0 was huge
-2. A lot of unneeded features had to be removed. 
-3. Documentation system is currently too complicated and will be overhauled later
-- Eisverygoodletter 28/08/2022
+# ARCHIVE NOTICE
+Since the EV3 bricks are now being replaced by new Spike Prime bricks and the original developers (Eisverygoodletter, txxvgnx, NotOnAClient) have graduated and left the robotics club. This repository no longer has an active maintainer and will be archived.
 
-# welcome to [ev3dev cpp template wrapper]
-### this is a wrapper aimed for lego robotics on ev3dev
+This repository will still remain available and all of its functionality will be intact, but no new features would be added unless a new maintainer is willing to implement features. If you are interested in using this repository or contributing to it, contact me (Eisverygoodletter) at [email protected]
+
+# welcome to `ev3dev-cpp-template-wrapper`'s repository page.
+This library doesn't require excessive tool installation and overly complicated cross-compiler setups. A guide can be found [here](https://rshs-robotics-club.github.io/ev3wrap/master/). Github Codespaces is available for this project at `https://github.com/rshs-robotics-club/ev3dev-cpp-wrapper-example`
+### This is a wrapper around [ddemidov/ev3dev-lang-cpp](https://github.com/ddemidov/ev3dev-lang-cpp). It includes classes for different sensors, with support for:
+-   Building Block Robotics IR Seeker
+-   Ev3 brick buttons
+-   Color Sensors
+-   Gyro Sensors
+-   HiTechnic Compass Sensors
+-   HiTechnic IR Seeker
+-   Ev3 large and medium motors
+-   An `Omni` class used for managing a specific motor setup
+-   Ultrasonic Sensors
+-   Beeping with ev3 speaker (and speaking words)
+-   Class for `Vector` math
+-   Bluetooth communication (both ev3-to-ev3 and ev3-to-computer are possible)
+
+While cross compiling has only been tested on Windows, a Github Codespace
 
-aimed at providing support for a few other sensors (compass and irseeker etc) and wrapping around a highly modified version of `ev3dev.h` and `ev3dev.cpp` from ev3dev-lang-cpp repo
 
-only works on windows
 Find the documentation [here](rshs-robotics-club.github.io)
 
 # we are currently on version V3.0.1

docStructure.yml

@@ -54,6 +54,8 @@ FileSystem:
         tag: "Utilities"
       - Vector:
         tag: "Vector"
+      - BluetoothSocket:
+        tag: "bluetooth-socket"
     - contributing:
       tag: "contribute"
       child_folder_reqs:

docker/Dockerfile

@@ -10,4 +10,11 @@ RUN cd cmake-3.24.0 && \
     make -j $(nproc) && \
     sudo apt-get remove --purge cmake -y && \
     sudo make install && \
-    rm -r *
+    rm -r *
+# install libbluetooth-dev for cross compiling
+RUN wget http://security.debian.org/debian-security/pool/updates/main/b/bluez/libbluetooth-dev_5.43-2+deb9u5_armel.deb
+RUN dpkg -x libbluetooth-dev_5.43-2+deb9u5_armel.deb ./temp && \
+    mkdir ./crossCompileLibraries && \
+    mkdir ./crossCompileLibraries/libbluetooth && \
+    cp -r ./temp/usr/. ./crossCompileLibraries/libbluetooth && \
+    rm -r ./temp

docs/contributing/writingDocumentation.md

@@ -7,6 +7,8 @@ tag: "writingDocumentation"
 ### The library's documentation relies on a [modified version of just-the-docs](https://github.com/rshs-robotics-club/just-the-docs) as its jekyll theme.
 The modification allows the documentation  to have infinite nesting on the navigation bar, and a more centralised navigation structure management.
 
+> A new just-the-docs version has implemented infinite nesting levels. This fork of just-the-docs will no longer be maintained. The documentation won't be switched over to the new version and will be archived instead along with the library repository.
+
 ### The centralised file structure management
 The structure is stored in a file `docsStructure.yml`.
 It should look something like

docs/documentation/bluetooth-socket.md

@@ -0,0 +1,128 @@
+---
+title: "BluetoothSocket"
+tag: "bluetooth-socket"
+---
+
+# `BluetoothSocket` class
+
+### Description
+`BluetoothSocket` is built for 1 to 1 bluetooth communication between 2 ev3 bricks. If your goal is to have multicast/broadcast related functions, either create many `BluetoothSocket`s or you're out of luck.
+
+A `BluetoothSocket` can either be a "server socket" or a "client socket". Server sockets wait for client sockets to connect to them when created. Client sockets are initialised with a goal bluetooth `MAC` address that they attempt to connect to.
+
+`BluetoothSocket`s can be reconnected if the connection is broken. However, the `BluetoothSocket` cannot reconnect to a different robot.
+
+## Initialization
+To initialise a Server socket, use `BluetoothSocket::CreateServerSocket()`
+To initialise a Client socket, use `BluetoothSocket::CreateClientSocketByHostname(std::string hostname)` 
+or 
+`BluetoothSocket::CreateClientSocketByMAC(std::string MAC)`
+Using the `MAC` address is recommended since no time is wasted on device detection. you can use the static function `BluetoothSocket::listDetectedDevices()` to print detected device hostnames and their `MAC` addresses.
+
+>   Warning: normally, inquiry scans are disabled on the ev3 bluetooth adapter. to enable them, use a putty console and run `hciconfig hci0 piscan`, or put `system("hciconfig hci0 piscan")` as your first line in your `main()` function. This allows other robots to detect and connect with your robot. This property is reset every time the robot is rebooted.
+
+## Sending data
+To send data, use the `BluetoothSocket.send(char* msg, int size = CHAR_ARRAY_SIZE)` method. This takes in a `char*` buffer and the size of it. The library assumes that your buffer will be 32 bytes, (defined as `CHAR_ARRAY_SIZE`). You can have a custom size, but you will have to make sure the receiving end can handle that many bytes in 1 message.
+Sending a large number of bytes increases the potential number of `write()` calls required. For simplicity, this library assumes that 1 `write()` call is enough for 1 message, hence the byte restriction at 32.
+
+>   Tip: It is completely fine if your buffer is under 32 bytes.
+
+>   Warning: do not do something like `mysocket.send(std::string("epic message").c_str())`. the string goes out of scope before the pointer is accessed, leading to dangling pointer problems and undefined behaviour. Properly define a `char*` buffer first.
+
+
+## Reading data
+To read data, use the `BluetoothSocket.readValue(char* msg, int size = CHAR_ARRAY_SIZE)` method. If you had sent over 32 bytes of data, make sure you have allocated enough memory for reading, otherwise the data will be split up and read in 2 separate occasions.
+
+>   Warning: watch out for memory leaks! remember to `free()` your `malloc()` buffers
+
+## Detecting disconnections
+Both `send` and `readValue` methods return `bool`s. These represent whether the operation succeeded or not. If they are false, it is very likely that the socket had been disconnected. Check the `BluetoothSocket.hasDisconnected` property for if it had been disconnected.
+
+## Reconnecting after being disconnected
+If the other end of the socket is disconnected for whatever reason, (such as a program crash; ended by stop button etc.) You can use `BluetoothSocket.attemptReconnect();` to try reconnect with the other robot. This is a **non-blocking** method. If it fails to reconnect, it will return `false`. Call this in your event loop or repeatedly in your program until the socket is reconnected.
+
+>   Warning: if `BluetoothSocket.hasDisconnected` is `false` when you attempt to reconnect, it will throw an error (you're already connected!)
+
+
+## Examples
+```cpp
+// bluetooth-server.cpp
+// to be run on "robot2"
+#include <bluetooth-socket.hpp>
+
+using namespace Ev3Wrap;
+int main() {
+    system("hciconfig hci0 piscan");
+    BluetoothSocket serverSocket = BluetoothSocket::CreateServerSocket();
+    while (true) {
+        if (!serverSocket.hasDisconnected) {
+            char* msg = (char*)malloc(sizeof(char) * CHAR_ARRAY_SIZE);
+            strcpy(msg, "Hello!\n");
+            //std::cout << msg << '\n';
+            bool res = serverSocket.send(msg);
+            free(msg);
+        }
+        else {
+            serverSocket.attemptReconnect();
+        }
+    }
+    return 0;
+}
+```
+
+```cpp
+// bluetooth-client.cpp
+// to be run on "robot1"
+#include <bluetooth-socket.hpp>
+
+using namespace Ev3Wrap;
+int main() {
+    system("hciconfig hci0 piscan");
+    BluetoothSocket clientSocket = BluetoothSocket::CreateClientSocketByHostname("robot2");
+    while (true) {
+        if (!clientSocket.hasDisconnected) {
+            char* buffer = (char*)malloc(sizeof(char) * CHAR_ARRAY_SIZE);
+            bool res = clientSocket.readValue(buffer);
+            if (res) {
+                std::cout << buffer << '\n';
+            }
+            free(buffer);
+        }
+        else {
+            clientSocket.attemptReconnect();
+        }
+    }
+    return 0;
+}
+```
+The above 2 programs uses the `BluetoothSocket` to communicate with each other. They will continuously attempt to reconnect with each other if disconnected. Note that server sockets and client sockets have no difference outside of initialisation. Both can send data and read data to the other. In this example, the server socket is sending messages to the client socket.
+
+---
+# Advanced Usage
+Most of the time, `char` is not the data type we want to send. Something like `int` would be far more helpful. Given that `int`s are 4 bytes on the EV3, we can designate the first 4 bytes of our `char*` buffer as an `int`, the next 4 bytes as the next `int`, etc.
+```cpp
+char* myBuffer = (char*)malloc(sizeof(char) * CHAR_ARRAY_SIZE);
+int firstInt = 123;
+int secondInt = 456;
+memcpy(myBuffer, &firstInt, sizeof(firstInt));
+memcpy(myBuffer + sizeof(firstInt), &secondInt, sizeof(secondInt));
+myBluetoothSocket.send(myBuffer);
+free(myBuffer);
+```
+and on the receiving end:
+```cpp
+char* recvBuffer = (char*)malloc(sizeof(char) * CHAR_ARRAY_SIZE);
+if (myBluetoothSocket.readValue(buffer)) {
+    int firstInt, secondInt;
+    memcpy(&firstInt, recvBuffer, sizeof(int));
+    memcpy(&secondInt, recvBuffer + sizeof(firstInt), sizeof(int));
+    free(recvBuffer);
+    // now use firstInt and secondInt for whatever you want
+}
+else {
+    // read value failed. check myBluetoothSocket.hasDisconnected
+    // ...
+}
+```
+
+refer to https://stackoverflow.com/questions/1522994/store-an-int-in-a-char-array for more alternative ways to solve this problem.

docs/index.md

@@ -4,7 +4,10 @@ title: "Introduction"
 nav_order: 1
 tag: "introduction"
 ---
-Note that this is not a completed product
+# Better setup process
+There is now a template available for github codespaces. Select `Use this template -> Open in a codespace` from this [template repository](https://github.com/rshs-robotics-club/ev3dev-cpp-wrapper-example)
+> Please note that the rest of the documentation was written before Github Codespaces are released. Because of this, there is no mention of github codespaces anywhere else in the documentation. If you have a problem with the github codespaces setup, contact `[email protected]`
+
 # Introduction
 If you do not know what ev3dev is, go [here](https://www.ev3dev.org/).
 This library is a wrapper around [ev3dev's official cpp library](https://github.com/ddemidov/ev3dev-lang-cpp). We do not guarantee that this wrapper will work.
@@ -49,10 +52,4 @@ We currently only have support for compiling on windows. (MacOS support not comi
    5. you can find the output `.elf` files in the `bin` folder. Note that linux (ev3dev) does not care about file extensions, but since we're using windows we make it easier for ourselves by distinguishing executables with the `.elf` extension.
    6. If you want to create more executables/projects, you can do so by creating a new `differentprojectName.cpp` file and running `./scripts/compile.sh` again. Now, you will find both `projectName.elf` and `differentprojectName.elf` in the `bin` folder. This is useful when you require quick prototyping in your project.
 ## Oh no! I ran into a problem
-See the troubleshooting section (Not implemented yet) for solutions to common problems. If you can't find any, check [issues](https://github.com/rshs-robotics-club/ev3dev-cpp-template-wrapper/issues). If you still can't find a solution, open a new [issue](https://github.com/rshs-robotics-club/ev3dev-cpp-template-wrapper/issues) and we will try to help you.
-
----
-# [Click here to find the Quick Start tutorials](quickstartTutorials.md)
----
-# [Click here for the documentation](documentation.md)
----
+See the troubleshooting section (Not implemented yet) for solutions to common problems. If you can't find any, check [issues](https://github.com/rshs-robotics-club/ev3dev-cpp-template-wrapper/issues). If you still can't find a solution, open a new [issue](https://github.com/rshs-robotics-club/ev3dev-cpp-template-wrapper/issues) and we will try to help you.

lib/bbr-irseeker/bbr-irseeker.cpp

@@ -50,18 +50,20 @@ __s32 BBRIrSeeker::i2cReadInt(int fd, __u8 address)
 
 void BBRIrSeeker::i2cReadBlockData(int fd, __u8 address, __u8 length, __u8 *values)
 {
-	if (0 > i2c_smbus_read_i2c_block_data(fd, address,length,values)) 
+    int potentialError = i2c_smbus_read_i2c_block_data(fd, address, length, values);
+	if (0 > potentialError) 
 	{
+        std::string msg = "BBR IrSeeker encountered an error while reading. Error code: " + std::to_string(potentialError);
 		close(fd);
-		exit(4);
+		throw std::system_error(std::make_error_code(std::errc::no_such_device), msg);
 	}
 }
 
 void BBRIrSeeker::getBoth(int* direction = nullptr, int* strength = nullptr) {
     int fd = this->begin();
     __u8 values[2];
     this->i2cReadBlockData(fd, 0x08, 2, values);
-    close (fd);
+    close(fd);
     if (strength != nullptr) {
         *strength = (int)values[1];
     }