diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index ebb8cfbba..000000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,141 +0,0 @@ -# Change log - -Notable changes to the project will be archieved here - - -## [1.8.1](https://gitlab.au.dk/au-cs-ceed/ml-microbit-browser/-/releases/v1.8.1) - 11/01 - 2023 -Fixes some problems after reaching feature parity between DR and master release branches - -### Changed -- Removes ID field from menu properties -- Moved management of menus out of svelte components - -### Fixed -- Fixed type errors and warnings for graph components -- Cookie banner can now select language -- Fixed a bug with predictions causing NaN confidence - -## [1.8.0](https://gitlab.au.dk/au-cs-ceed/ml-microbit-browser/-/releases/v1.8.0) - 22/12 - 2022 -Jest has been introduced! And with it comes the promise of stability. In addition, some graphical and translation issues has been addressed. - -### Added -- Jest has been introduced (see `src/__tests__/` for examples on how they work) -- Tests for finding unused translations -- Tests for inconsistencies in the translations, such as having to include both an english and danish translation of a phrase. -- Both english and danish translations must be of equal length - -### Fixed -- Thanks to jest we have found several issues with the translation, which has been addressed, including removing unused/redundant translations -- The highlights on the pattern matrix now disappears when moving outside the drawing area. - -## [1.7.0](https://gitlab.au.dk/au-cs-ceed/ml-microbit-browser/-/releases/v1.2.0) - 1/12 - 2022 -Jest has been introduced! And with it comes the promise of stability. In addition, some graphical and translation issues has been addressed. - -### Added -- Jest has been introduced (see `src/__tests__/` for examples on how they work) -- Tests for finding unused translations -- Tests for inconsistencies in the translations, such as having to include both an english and danish translation of a phrase. -- Both english and danish translations must be of equal length - -### Fixed -- Thanks to jest we have found several issues with the translation, which has been addressed, including removing unused/redundant translations -- The highlights on the pattern matrix now disappears when moving outside the drawing area. - -## [1.6.0](https://gitlab.au.dk/au-cs-ceed/ml-microbit-browser/-/releases/v1.1.0) - 22/11 - 2022 -Introduces a new pairing pattern system -### Added -- Pairing pattern now automatically fills out squares beneath the targeted square. In addition it outlines any squares below the one that is currently being hovered over. -- The ConnectionBehaviour callback promptOpen is now fired when the connection prompt opens. - -### Fixed -- The information icon is now fixed in place on recorded gestures. Before it would move when scrolling the page -- Spinning icon no longer escapes the menu box after a model has been trained. -- Information icons no longer have higher z-index priority over the control-bar -- Failed connectivity errors that would occur when the micro:bit was successfully connected but loses connection before adding the listener to the services such as accelerometer are now caught and display a 'connection failed' message. -- Added some missing translations for prompts when deleting tests/gestsures -- Reduced the overflow issue that would cause the left hand side menu to overflow when testcenter was open on chromebooks. It is still an issue, but now the home button is accessible. -- Swapped the outline on the bottom input graph for a border, since it caused some graphical issues due to it being placed outside the container. - -## [1.5.0](https://gitlab.au.dk/au-cs-ceed/ml-microbit-browser/-/releases/v1.0.1) - 17/11 - 2022 -Welcome Jon, who has joined the project. - -This version was created to improve stability and transitioning the micro:bit firmware from MakeCode to C++. The C++ firmware can be found as a repository under the AU CS CEED group. -### Added -- Added Dialog box component for contact information - -### Changed -- Removed top bar from DataPage -- Many styling changes to support the upcoming DR-release - -### Fixed -- Flashing error handling. Now gives appropriate feedback -- Alignment issues -- Issues only present on chromebook -- Fixed a null pointer exception that was thrown when resizing the overlay on the output page. -- Closed issue where the pairing pattern would sometimes be wrong on the micro:bit. Issue could not be replicated after new HEX file. -- Fixed text alignment issue on the left hand side menus. Text was not align vertically to the center when collapsed. -- Improved solution for handling failed flashes / get friendly name. Now these should be caught with the promise.catch(e) statement. -- Fixed some connectivity issues on the micro:bit. This was caused by using too little power for the transmission component of the BLE. - - - -## [1.4.0] - 6/10 - 2022 -This release signifies the last release before the DR-cooperation project starts -### Added -- Added compatibility checking for USB and bluetooth -- Added connect with USB step -- Added skeletal animations - -### Changed -- Now allows for multi-line information boxes - -### Fixed -- Fixed the model-page no-output overlay issue - - - -## [1.3.0] - 6/10 - 2022 - -### Added -- Cookie banner and cookie manager -- Introduced a standardized button -- Added Generic Modal -- MicrobitUSB now has an event-emitting implementation -- MicrobitBluetooth can now emit events - - -### Changed -- Reduced the usage of z-layer or reduced their values, keeping them from going wild -- Completely overhauled the code structure, using less position: absolute - -### Fixed -- One can no longer close while transferral is in progress - - -## [1.2.0] - 1/09 - 2022 - -### Added - - Added pairing pattern connection - - Added new connection flow - - Added flashing .hex files through USB - - MBSpecs, a microbit specification file for details such as UUIDs for bluetooth services - -### Changed -- Added interfaces that controls input/output seperately through implementation -- Many files converted to TypeScript - -### Fixed -- Fixed a bug, that caused failed data loading from localStorage - -## [1.1.0] - 30/06 - 2022 - -### Added - - Added support for v1 microbits - - Bluetooth wrapper for interacting with microbits - -### Changed -- Magic values replaced by configuration settings - -## [1.0.0] - 15/09 - 2021 - -Initial release of ML-Machine. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8b06b8b08..538b91576 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,67 +1,13 @@ -# Contributing +Thanks for looking here! We'd love your help. The micro:bit project is only +possible through contributions of companies and individuals around the world. -When contributing to this repository, please first discuss the change you wish to make via issue or any other method -with the maintainers of this repository before making a change. +This project is managed on GitHub, and the best way to contribute is to jump in +and fix/file issues. -Please note we have a code of conduct, please follow it in all your interactions with the project. +https://github.com/microbit-foundation/ml-trainer -## Pull Request Process +Significant features are best discussed first to make sure everyone is agreed +on the best direction. -1. Ensure any install or build dependencies are removed and the tests using `npm run test` are running successfully. -2. Update the README.md with details of changes to the interface, this includes new environment - variables and useful file locations, if applicable. -3. Increase the version numbers in any examples files and the README.md to the new version that this - Pull Request would represent. The versioning scheme we use is [SemVer](http://semver.org/). -4. Create a pull request describing the changes you have made, as briefly as possible. Maintainers may require further - detail or request changes. Avoid changing lines of code, that are unrelated to the change to avoid unnecessary code - ownership changes, such as inserting trailing commas or semicolons. -5. The pull request will be merged when at least two maintainers has accepted the changes. - -Thank you for considering contributing to the project! - -## Code of Conduct - -Please see Micro:bit Educational Foundation's [code of conduct](https://microbit.org/safeguarding/) which outlines our expectations for all those that participate in the community and details on how to report any concerns and what would happen should breaches occur. - -### Our Pledge - -In the interest of fostering an open and welcoming environment, we as -contributors and maintainers pledge to making participation in our project and -our community a harassment-free experience for everyone, regardless of age, body -size, disability, ethnicity, gender identity and expression, level of experience, -nationality, personal appearance, race, religion, or sexual identity and -orientation. - -We stride to make learning an empowering experience for all and constantly weigh the balance between accessibility and -complexity on our platform. - -### Our Standards - -Examples of behavior that contributes to creating a positive environment -include: - -* Using welcoming and inclusive language -* Being respectful of differing viewpoints and experiences -* Gracefully accepting constructive criticism -* Focusing on the empowerment of learning -* Showing empathy towards other users or contributors - -Examples of unacceptable behavior by participants include: - -* The use of sexualized language or imagery and unwelcome sexual attention or - advances -* Trolling, insulting/derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or electronic - address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting - -### Our Responsibilities - -Maintainers of ML-Machine have the responsibility of upholding code quality and interpreting the code of conduct and are -expected to make appropriate and fair decisions in response to behavior and changes. - -Maintainers have the right to remove, edit or reject any changes such as commits, code wiki edits and issues which are -not aligned with our pledge, standards or code of conduct, or to ban temporarily or permanently any contributor for -actions deemed inappropriate or harmful. \ No newline at end of file +The project uses [Prettier](https://prettier.io/) to format code so please +check out their documentation and set it up with your code editor. diff --git a/README.md b/README.md index c03eaa7e1..b7e34b250 100644 --- a/README.md +++ b/README.md @@ -1,174 +1,96 @@ -# ML-Machine +# ml-trainer -ML-Machine is a free and open-source interactive machine-learning platform, utilising external sensors to generate data, -which it can be trained to recognise. This allows for gesture recognition by recording examples of gestures performed by -the user, which the platform can learn and subsequently recognise. The external sensors are provided by the micro:bit -boards, which are communicated with through Bluetooth. When a gesture is recognised an auditory, visual or logical -feedback action is taken. +Train a machine learning model on movement data from the micro:bit's +accelerometer. Run it on your BBC micro:bit, building your own progam that uses +the machine learning model in Microsoft MakeCode. -To learn to recognise a gesture, a label is created for which a set of example movements with the micro:bit -is recorded. These recordings will be processed by a machine-learning algorithm to recognise future examples. To -differentiate the recording and feedback process we allow for two micro:bits to be connected. One will act as a -recording, or input device and another will act as feedback, or output device. +Try it at https://createai.microbit.org -
- -
+## History -## Building ML-Machine +This repository is derived from [ML-Machine](https://ml-machine.org) +([GitHub](https://github.com/microbit-foundation/cctd-ml-machine.)), a free and +open-source interactive machine-learning platform from the [Center for +Computational Thinking and Design at Aarhus University](https://cctd.au.dk/). -ML-Machine can be found at [ML-Machine.org](https://ml-machine.org/) free to use. -Using the platform requires at least one micro:bit, but two is recommended, especially if you are planning on using any -of the I/O feedback. +Significant changes have been made to align with the tech stack of other +Micro:bit Educational Foundation applications, add and remove features, and +revise the user experience for some features also in ML-Machine. We encourage +you to review both projects and see which best fits your needs. -You can find the version on the main branch at [main.ML-Machine.org](https://main.ml-machine.org/). It will have the newest features but may not be stable and features will be removed or changed without any warnings so do not rely on this version. +## Building and running the app -### Running the application locally +Getting up and running: -Alternatively the application can be run locally on your computer without compromising the capabilities of the software. +1. Ensure you have a working [Node.js environment](https://nodejs.org/en/download/). We recommend using the LTS version of Node. +2. Checkout this repository with Git. GitHub have some [learning resources for Git](https://docs.github.com/en/get-started/quickstart/git-and-github-learning-resources) that you may find useful. +3. Install the dependencies by running `npm install` on the command line in the checkout folder. +4. Choose from the NPM scripts documented below. Try `npm start` if you're not sure. -1. Ensure you have [nodejs](https://nodejs.org/) and the package manager [npm](https://www.npmjs.com/) -2. Download or clone this repository -3. In the terminal, run command `npm install` inside the project directory. -4. Once installed, run `npm run dev` to launch the application. -5. Access the application from http://localhost:5173/ +### `npm run dev` -List of commands can be found below. +Runs the app in the development mode. +Open [http://localhost:3000](http://localhost:3000) to view it in the browser. -### ```npm run dev``` +The page will reload if you make edits. -This starts the development environment using Vite. This should be used when developing as it supports hot-reload/live reload. +This does not show TypeScript or lint errors. +Use the eslint plugin for your editor and consider also running `npm run typecheck:watch` to see full type checking errors. -We recommend starting here. +### `npm test` -### ```npm test``` +Launches the [test runner](https://vitest.dev/) in interactive mode (unless the `CI` environment variable is defined). +See the section about [running tests](https://facebook.github.io/create-react-app/docs/running-tests) for more information. -Runs the test suite. Tests are driven by the framework [Vitest](https://vitest.dev/). Runs all tests inside the folder `./src/__tests__/`. +### `npm run build` -If you do not plan to contribute to the project, you may safely ignore this. +Builds the app for production to the `dist` folder.\ +It correctly bundles React in production mode and optimizes the build for the best performance. -### ```npm run check``` +## Deployments -Runs the svelte-check procedure. This will check for various usability issues, unused variables and checks types. This is seldom used, and equivalent checks are performed through Vite and Typescript. Use as a supplement when finalizing a commit. +Most users should use the supported Foundation deployment at https://createai.microbit.org/ -### ```npm run build``` +The editor is deployed by [GitHub actions](https://github.com/microbit-foundation/ml-trainer/actions). -Creates a build for the application. Using Vite, the application will be built and placed in the `./dist/` folder. - -Use this if you are going to deploy the application on a webserver, or if you wish to use `npm start` to run the application. - -### ```npm start``` - -This starts a server, hosting the contents of `./dist/`. This folder is built by running `npm run build`. - -This will expose the application to the network on the default port (5173). - - -### Hex files - -Programs on your micro:bit is contained inside the .hex format files. The files we use can be found in `./public/firmware/`. -The file must be uploaded to your micro:bit in order to use the application. - -Note: The application can upload the program to the micro:bit, there is no need for manual installation of hex files prior to launching the application. - -The source code for these programs are written in c++ and can be found in the folder `./microbit/`. - -If you wish to alter the micro:bit programs, you will need a few tools that depends on which micro:bit version you wish to build for. In the folder `./microbit/` lies a README.md with further instructions, which you can visit by clicking [here](./microbit/) - -## Using ML-Machine - -### Connecting your micro:bit - -The micro:bit can be connected via Bluetooth. The micro:bit requires a specific firmware to be able to communicate with -the platform effectively. The firmware can be acquired as a .hex file which can be manually transferred using your PC's -file system, alternatively, if the micro:bit is connected via USB the platform can automatically upload the firmware to -the micro:bit directly. - -### Creating gestures and recording examples - -To create a gesture go to the data tab through the menu on the left side of the page. Then click the big plus icon to -create an empty gesture and give it a title. - -To record an example ensure that a micro:bit has been connected and select the newly created gesture. Press either of -the buttons in the micro:bit and perform the gesture you wish to recognise immediately. You can do this as many times as -you would like. The more example you give for the gesture, the more confident the algorithm will be in recognising the -gesture in the future. - -### Training the model - -To train the predictive model on the given gesture examples, go to the trainer tab of the menu. Select the train model -option and wait until it has finished. The time this takes is dependent on how many examples you gave each gesture and -how many gestures the model has to learn. - -### Recognising gestures - -The model will attempt to predict which gesture is being performed immediately after training. Go to the model tab to -configure the feedback actions, which will be taken when the model makes a prediction. - -### Configuring prediction and feedback - -In the model tab several options become available once the model has been trained. These can be changed to alter the -behaviour of the platform and micro:bits. - -#### Confidence threshold - -Determines how confident the model has to be for a feedback action to be taken for the given gesture. This is a slider -located to the right of the label and can be adjusted to make the model more sensitive, the default value is 80%, and -can be changes for each gesture. - -Immediately besides it, a confidence-meter shows how confident the model currently is and will change as you perform -gestures. - -#### Changing the LEDs for output micro:bit - -Determines which LEDs on the display of the micro:bit will be lit up when the gesture is detected. This is - -#### Sound feedback - -Determines which sound clip will be played when a gesture is recognised. Depending on which version of micro:bit you -have, the sound will be output on the speaker of the micro:bit or on your computer, if the micro:bit doesn't support -speaker audio. - -#### I/O feedback - -Select the I/O pin you wish to turn on in response to a gesture detection. Combine this with circuitry to make gesture -recognition perform actions outside the platform such as turning on motors or LEDs. - -### Dependencies - -ML-Machine utilises several packages, most notable of which are the following: - -- [Svelte](https://github.com/sveltejs/svelte) provides the web-development framework. -- [Windi CSS](https://github.com/windicss/windicss) provides our styling tool. -- [TensorFlow.js](https://github.com/tensorflow/tfjs) provides machine learning capabilities. -- [Smoothie Charts](https://github.com/joewalnes/smoothie) and [chart.js](https://github.com/chartjs/Chart.js) provides - a visualisation kit. - -## Contributions - -#### Issues +## License -If you experience an issue or have a question regarding the platform please do not hesitate to raise an issue. The -maintainers will answer to any issues raised as quickly as possible. +This software is under the MIT open source license. -#### Code contributions +[SPDX-License-Identifier: MIT](LICENSE) -If you have an improvement on you wish to share with please read the [contributing](CONTRIBUTING.md) page. There you -will find information about how to contribute. The maintainers will review the changes as soon as possible. +Significant code is derived from ML-Machine (also MIT licensed) and is (c) +Center for Computational Thinking and Design at Aarhus University and +contributors. See individual file copyright notices for more details. -### Credits +Conceptually this project draws heavily on the work done by the Center for Computational Thinking and Design at Aarhus University (see [CCTD.dk](https://cctd.au.dk)) and we're hugely grateful for their ongoing support and collaboration. -ML-Machine is a platform created by the Center for Computational Thinking and Design (see [CCTD.dk](https://cctd.au.dk)) at Aarhus University for empowering education in the emerging fields of technology and computation. +We use dependencies via the NPM registry as specified by the package.json file +under common Open Source licenses. -## License +Full details of each package can be found by running `license-checker`: -[MIT](LICENSE) © Center for Computational Thinking and Design at Aarhus University and contributors. +```bash +$ npx license-checker --direct --summary --production +``` -We use dependencies via the NPM registry as specified by the package.json file under common Open Source licenses. +Omit the flags as desired to obtain more detail. -The repository includes forks of Lancaster's micro:bit-samples repositories for micro:bit [V1](https://github.com/lancaster-university/microbit-samples) and [V2](https://github.com/lancaster-university/microbit-v2-samples). They are MIT licensed. +The repository includes forks of Lancaster's micro:bit-samples repositories for +micro:bit [V1](https://github.com/lancaster-university/microbit-samples) and +[V2](https://github.com/lancaster-university/microbit-v2-samples). They are MIT +licensed. ## Code of Conduct -In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. Please see our code of conduct on the [contributing](CONTRIBUTING.md) page and Micro:bit Educational Foundation's [code of conduct](https://microbit.org/safeguarding/) which outlines our expectations for all those that participate in the community and details on how to report any concerns and what would happen should breaches occur. +Trust, partnership, simplicity and passion are our core values we live and +breathe in our daily work life and within our projects. Our open-source +projects are no exception. We have an active community which spans the globe +and we welcome and encourage participation and contributions to our projects +by everyone. We work to foster a positive, open, inclusive and supportive +environment and trust that our community respects the micro:bit code of +conduct. Please see our [code of conduct](https://microbit.org/safeguarding/) +which outlines our expectations for all those that participate in our +community and details on how to report any concerns and what would happen +should breaches occur.