Merge pull request #273 from HassoPlattnerInstituteHCI/additional_cle…

…anup

housekeeping

.gitignore

@@ -1,7 +1,8 @@
-Utils/Serial/*
-!Utils/Serial/include
-!Utils/Serial/src
-!voice-command/build/build-release.js
+utils/serial/*
+!utils/serial/include
+!utils/serial/src
+!utils/serial/binding.gyp
+!utils/voiceCommand/build/build-release.js
 build/
 node_modules/
 package-lock.json
@@ -25,8 +26,8 @@ src/osx/voice-command/build
 *.sln.docstates
 *.plist
 *.xccheckout
-!voice-command/src/osx/voice-command/voice-command.xcodeproj/project.xcworkspace/xcuserdata/baluubas.xcuserdatad
-!voice-command/src/osx/voice-command/voice-command.xcodeproj/xcuserdata/baluubas.xcuserdatad
+!utils/voiceCommand/src/osx/voice-command/voice-command.xcodeproj/project.xcworkspace/xcuserdata/baluubas.xcuserdatad
+!utils/voiceCommand/src/osx/voice-command/voice-command.xcodeproj/xcuserdata/baluubas.xcuserdatad
 *.xcuserdatad
 
 # User-specific files (MonoDevelop/Xamarin Studio)

Firmware/platformio.ini → firmware/platformio.ini

@@ -2,7 +2,7 @@
 description = Dualpanto firmware
 
 [protocol]
-base_dir = ../Protocol
+base_dir = ../utils/protocol
 include_dir = ${protocol.base_dir}/include
 src_dir = ${protocol.base_dir}/src
 src_filter = +<../${protocol.src_dir}>

lib/device.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const serial = require('../build/Release/serial');
+const serial = require('../utils/serial/build/Release/serial');
 const Vector = require('./vector');
 const HapticObject = require('./hapticObject');
 const HandleMovement = require('./handleMovement');

lib/dualpantoframework.js

@@ -22,7 +22,7 @@ module.exports = {
 
 // require async to dirty fix cyclic dependency
 process.nextTick(() => {
-  require('../Utils/ViDeb/index');
+  require('../utils/viDeb/index');
 });
 
 // @TODO: move the following stuff into the correct files

lib/voice-interaction.js

@@ -2,7 +2,7 @@
 
 const EventEmitter = require('events').EventEmitter;
 const say = require('say');
-const VoiceCommand = require('../voice-command');
+const VoiceCommand = require('../utils/voiceCommand');
 const Player = require('./player');
 
 /**

package.json

@@ -11,9 +11,9 @@
     "config": "npm run script config",
     "plotter": "npm run script plotter",
     "docs": "npm run script docs",
-    "script": "node ./Utils/Scripts/run.js",
-    "svgToJs": "node ./Utils/svgConverter/svgToJs.js",
-    "setup-commit-hook": "if-env NODE_ENV=production && echo \" production mode \" || node ./Utils/Scripts/createJsCommitHook.js"
+    "script": "node ./utils/scripts/run.js",
+    "svgToJs": "node ./utils/svgConverter/svgToJs.js",
+    "setup-commit-hook": "if-env NODE_ENV=production && echo \" production mode \" || node ./utils/scripts/createJsCommitHook.js"
   },
   "repository": {
     "type": "git",

README.md → readme.md

@@ -74,3 +74,24 @@ The `examples` dir contains multiple example programs, as well as programs for c
   - `speakText.js` - Uses the voice output.
 - `wall` - Obstacle testing.
   - `wallGenerator.js` - generates a circle obstacle, subdivided into a given number of edges.
+
+## Repository Overview
+
+- `documentation` - \[Markdown\] Contains the documentation about interfaces and setup.
+  - `classes` - Documentaion for the classes exported by the framework. Build this using `npm run docs`.
+  - `protocol` - Definition of the serial communication protocol. The shared source files implementing this can be found in `./utils/protocol/`. The serial implementations are stored in `./firmware/utils/` (firmware side) and `./utils/serial/` (framework side).
+  - `setup` - Instuctions on how to set up the framework for different operating systems.
+- `examples` - \[JavaScript\] Example scripts on how to use the framework. See [example section](#Examples).
+- `firmware` - \[C++\] The firmware for the ESP32 built into the device. Build using the [platformio command](#Available-Scripts).
+- `hardware` - \[JSON\] Config files for different hardware iterations. These are used with the [configure command](#Available-Scripts) to generate source files which are then compiled into the firmware.
+- `lib` - \[JavaScript\] The dualpantoframework library. Refer the [docs](documentation/classes/index.md) for more info about the files.
+- `utils` - Mixed helpers for building and debugging.
+  - `backtrace` - \[sh\] Bash script vor decoding the ESP32's crash backtrace. Functionality is built into the framework's serial plugin now, but this script may be used without a platformio installation.
+  - `geogebra` - Geometric representations of forward and inverse kinematics. Contains both complete websites for easy use, as well as the scripts used to create those websites.
+  - `plotter` - \[JavaScript\] Visualization of the panto's available space and the resolution. Use the [plotter command](#Available-Scripts) to start a server, open the page (note: due to a bug in a dependency, go directly to `[...]/index.html`) and upload one of the hardware config files.
+  - `protocol` - \[C++\] Serial protocol base files, shared between firmware and framework. Based on the specification stored in `./documentation/protocol/`.
+  - `scripts` - \[JavaScript\] The scripts behind the [commands](#Available-Scripts). Check out `./package.json` and `./utils/scripts/run.js` if you want to add functionality.
+  - `serial` - \[C++\] The serial plugin for the framework. Uses the shared protocol files (`./utils/protocol/`) to implement the specification (`./documentation/protocol/`).
+  - `svgConverter` - \[JavaScript\] Converts a `svg` file of a level into a `prototype.js` script. Use the [svgToJs command](#Available-Scripts).
+  - `viDeb` - \[JavaScript\] Implements a emulated device.
+  - `voiceCommand` - \[JavaScript\] Voice input plugin used by the framework.

Utils/Backtrace/backtrace.sh → utils/backtrace/backtrace.sh

@@ -4,11 +4,11 @@
 # In order to find line numbers, add -g3 to the PlatformIO build flags.
 # The default target is set for running this script from the base framework dir.
 # Alternatively, you may pass an path to the elf as the first argument.
-# Default usage: ./Utils/Backtrace/backtrace.sh "0x40085698:0x3ffb5e80 [...]"
-# Alternative usage example for running from this dir: ./backtrace.sh ./../../Firmware/.pioenvs/esp32dev/firmware.elf "0x40085698:0x3ffb5e80 [...]"
+# Default usage: ./utils/backtrace/backtrace.sh "0x40085698:0x3ffb5e80 [...]"
+# Alternative usage example for running from this dir: ./backtrace.sh ./../../firmware/.pioenvs/esp32dev/firmware.elf "0x40085698:0x3ffb5e80 [...]"
 
 if [ "$#" -eq 1 ]; then
-    target=./Firmware/.pioenvs/esp32dev/firmware.elf
+    target=./firmware/.pioenvs/esp32dev/firmware.elf
     backtrace=$1
     echo "Using default target $target"
 else

Utils/Scripts/generateHardwareConfig.js → utils/scripts/generateHardwareConfig.js

@@ -4,7 +4,7 @@
 /* eslint-disable require-jsdoc */
 // the template strings can't ne broken into multiple lines
 /* eslint-disable max-len */
-const input = require('../../Hardware/'+process.argv[2]+'.json');
+const input = require('../../hardware/'+process.argv[2]+'.json');
 const fs = require('fs');
 const crypto = require('crypto');
 const hash = crypto.createHash('md5').update(JSON.stringify(input)).digest();
@@ -232,7 +232,7 @@ constexpr double hashtableStepSizeY = ${hashtable.stepSizeY};
 const uint32_t obstacleChangesPerFrame = ${input.obstacleChangesPerFrame};`;
 
 console.log(headerOutput);
-const headerDir = 'Firmware/include/config/';
+const headerDir = 'firmware/include/config/';
 if (!fs.existsSync(headerDir)) {
   fs.mkdirSync(headerDir, {recursive: true});
 }
@@ -253,7 +253,7 @@ float pidFactor[${pantoCount*3}][3] = {
 };`;
 
 console.log(sourceOutput);
-const sourceDir = 'Firmware/src/config/';
+const sourceDir = 'firmware/src/config/';
 if (!fs.existsSync(sourceDir)) {
   fs.mkdirSync(sourceDir, {recursive: true});
 }

Utils/Scripts/run.js → utils/scripts/run.js

@@ -16,29 +16,29 @@ const buildHandlers = {
          & build('serial-standalone');
   },
   'voice-command': () => {
-    return exec('node', ['./voice-command/build/build-release.js']);
+    return exec('node', ['./utils/voiceCommand/build/build-release.js']);
   },
   'serial-plugin': () => {
     const gypDef = '--cppdefs="NODE_GYP ' + escape(cppDefines.join(' ')) + '"';
-    return exec('node-gyp', ['configure', gypDef])
-         & exec('node-gyp', ['build']);
+    return exec('node-gyp', ['configure', '-C utils/serial', gypDef])
+         & exec('node-gyp', ['build', '-C utils/serial']);
   },
   'serial-standalone': () => {
     return exec(
         cppExec,
         cppArgs.concat(cppDefines.map((d) => cppDefinePrefix + d)).concat([
-          'Utils/Serial/src/standalone/main.cpp',
-          'Utils/Serial/src/standalone/standalone.cpp',
-          'Utils/Serial/src/serial/shared.cpp',
-          'Utils/Serial/src/crashAnalyzer/analyze.cpp',
-          'Utils/Serial/src/crashAnalyzer/buffer.cpp',
+          'utils/serial/src/standalone/main.cpp',
+          'utils/serial/src/standalone/standalone.cpp',
+          'utils/serial/src/serial/shared.cpp',
+          'utils/serial/src/crashAnalyzer/analyze.cpp',
+          'utils/serial/src/crashAnalyzer/buffer.cpp',
           process.platform == 'win32' ?
-            'Utils/Serial/src/serial/win.cpp' :
-            'Utils/Serial/src/serial/unix.cpp',
-          'Protocol/src/protocol/protocol.cpp',
-          '-IUtils/Serial/include',
-          '-IProtocol/include',
-          '-o Utils/Serial/serial']));
+            'utils/serial/src/serial/win.cpp' :
+            'utils/serial/src/serial/unix.cpp',
+          'utils/protocol/src/protocol/protocol.cpp',
+          '-Iutils/serial/include',
+          '-Iutils/protocol/include',
+          '-o utils/serial/serial']));
   },
   'firmware': () => {
     return config(process.argv[4])
@@ -74,18 +74,18 @@ const cleanHandlers = {
          & clean('serial-standalone');
   },
   'voice-command': () => {
-    return remove('./voice-command/.bin');
+    return remove('./utils/voiceCommand/.bin');
   },
   'serial-plugin': () => {
-    return remove('./build');
+    return remove('./utils/serial/build');
   },
   'serial-standalone': () => {
     log('Clean serial-standalone not implemented yet', color.yellow);
     return true;
   },
   'firmware': () => {
-    return remove('./Firmware/src/config/config.cpp')
-         & remove('./Firmware/include/config/config.hpp')
+    return remove('./firmware/src/config/config.cpp')
+         & remove('./firmware/include/config/config.hpp')
          & platformio('clean');
   }
 };
@@ -116,24 +116,24 @@ function config(target) {
     target = 'doerte';
   }
   log(`Generating config ${target}`, color.green);
-  return exec('node', ['Utils/Scripts/generateHardwareConfig.js', target]);
+  return exec('node', ['utils/scripts/generateHardwareConfig.js', target]);
 }
 
 function platformio(command) {
   if (command == 'build' || command === undefined) {
     command = '.';
   }
   log(`Running platformio ${command}`, color.green);
-  return exec(platformioExec, ['run', '-d Firmware', `-t ${command}`]);
+  return exec(platformioExec, ['run', '-d firmware', `-t ${command}`]);
 }
 
 function plotter() {
-  return exec('http-server', ['Utils/plotter/']);
+  return exec('http-server', ['utils/plotter/']);
 }
 
 function docs() {
   log(`Building docs`, color.green);
-  return exec('node', ['Utils/Scripts/docs.js']);
+  return exec('node', ['utils/scripts/docs.js']);
 }
 
 const handlers = {

utils/serial/binding.gyp

@@ -0,0 +1,35 @@
+{
+    "variables": {
+        "cppdefs": "NODE_GYP",
+    },
+    "targets": [{
+        "target_name": "serial",
+        "sources": [
+            "./src/node/main.cpp",
+            "./src/node/setup.cpp",
+            "./src/node/poll.cpp",
+            "./src/node/send.cpp",
+            "./src/node/receiveHelpers.cpp",
+            "./src/node/sendHelpers.cpp",
+            "./src/serial/shared.cpp",
+            "./src/crashAnalyzer/buffer.cpp",
+            "./src/crashAnalyzer/analyze.cpp",
+            "../protocol/src/protocol/protocol.cpp"
+        ],
+        "conditions": [
+            ["OS=='win'", {
+                "sources": ["./src/serial/win.cpp"]
+            }],
+            ["OS!='win'", {
+                "sources": ["./src/serial/unix.cpp"]
+            }],
+        ],
+        "include_dirs": [
+            "./include",
+            "../protocol/include"
+        ],
+        "defines": [
+            "<@(cppdefs)"
+        ]
+    }]
+}

voice-command/build/build-release.js → utils/voiceCommand/build/build-release.js

@@ -1,3 +1,4 @@
+/* eslint-disable */
 var os = require('os'),
     fs = require('fs'),
     spawn = require('child_process').spawn;
@@ -7,13 +8,13 @@ var platform = os.platform();
 console.log(platform);
 if(platform === 'darwin') {
     var child = spawn('xcodebuild', {
-    cwd: './voice-command/src/osx/voice-command/'
+    cwd: './utils/voiceCommand/src/osx/voice-command/'
     });
 }
 else if (platform == "win32") {
     var msbuild = 'C:/Windows/Microsoft.NET/Framework64/v4.0.30319/msbuild.exe';
     var child = spawn(msbuild, ['/p:Configuration=Release', 'voice-command.csproj', '/p:Platform=AnyCPU'], {
-    cwd: './voice-command/src/win/voice-command/'
+    cwd: './utils/voiceCommand/src/win/voice-command/'
     });
     child.stdout.on('data', function (data) { console.log('' + data); });
     child.stderr.on('data', function (data) { console.log('' + data); });