Merge pull request #101 from bigjosh/dev

Dev

Author: Josh Levine

Getting-started.md

@@ -64,7 +64,7 @@ avrdude -B 4 -D -v -patmega168pb -cusbtiny -Uflash:w:D-TimerFlashX.ino.with_boot
 ```
 
 `-D` skips erasing the flash before programming it. If you are programming virgin chips then the flash should be blank.
-`-B` lowered to 4 slightly increases the programmer clock. Some out of spec chips might fall to program at this speed. 
+`-B` lowered to 4 slightly increases the programmer clock, which reduces programming time. Note that some units might fail at this increased speed. 
 
 Note that these new options are both safe because the verify will fail if anything goes wrong. 
 

Layers.md

@@ -1,49 +1,65 @@
-# Move38 Blinks for the Arduino IDE
-An Arduino core for the Blinks gaming tile. More info at...
-http://move38.com
+# Blinks Software Development Kit (SDK) for Arduino
 
-## Roadmap
+This SDK includes all the software and configuration files to tell the Arduino IDE how to download programs in a blink along with some examples you can try out and modify.
 
-This core requires at least Arduino IDE v1.6.2, where v1.6.5+ is recommended. <br/>
-* [Programmers](#programmers)
-* **[How to install](#how-to-install)**
-* **[Getting started](#getting-started)**
+These instructions will get you set up to write your own games for the [Blinks platform](https://move38.com/pages/blinks-collection) using the Arduino IDE.
 
-Covers installing this repo so that you can write and download code into a Blinks tile using the Arduino IDE. 
+Note that you do not need any of this if you just want to *play* blinks games, only if you want to write them.
 
-Ends with loading a `HelloBlink` program it a tile.
 
-### Writing games
+## Getting Started
 
-The best way to start writing games is to work your way though the examples in the "File->Examples->Examples for Blink Tile" menu in the Arduino IDE (after you have installed this repo as described in the Getting Started above).  
-  
+### Software setup
 
-### [Service Port](Service Port.MD)
+1. Download and run the latest version of the[ Arduino IDE](https://www.arduino.cc/en/Main/Software#download)
+2. Go into File->Preferences->Settings and add...
+`https://github.com/bigjosh/Move38-Arduino-Platform/releases/latest/download/package_move38.com-blinks_index.json`
+...under Additional Boards Manager URLs. If you already have something there, you can use a comma to separate the multiple entries
+3. Go to Tools->Board->Boards Manager and search for "blinks"
+4. Press install on "Blinks by Move38"
+5. Pick "Tools->Board->Move38->blink" from the menus 
+5. Go to "File->Example->Getting Started->Button Press" to load an example program
+6. Program the `Button Press` example code into a blink (see below)
 
-Describes the service port connector on each blink. Lets you add `print` statements to your programs, which can be very helpful during development.  
 
-## How to install
+### Getting your code programmed into a blink
 
-Click on the "Download ZIP" button in the upper right corner of this repo. Extract the ZIP file, and move the extracted files to the location "**~/Documents/Arduino/hardware/Move38-manual/avr**". Create the folder if it doesn't exist. This readme file should be located at "**~/Documents/Arduino/hardware/Move38-manual/avr/README.md**" when you are done.
+Each blink can hold a game in its on-board flash memory. Once a blink has a game programmed into it, it can also share to other blinks over the IR links.  
 
-Open Arduino IDE, and a new category in the boards menu called "Move38-manual" will show up.
+You will need a programmer, a cable, and a connector to get your code from the Arduino IDE into a blink's flash. 
+ 
+The [Blinks Developer Kit](https://move38.com/products/bare-bones-dev-kit) that includes everything you need to start programming your own games, including a a special blink that connects to an included USB programmer to make downloading your code as easy as pushing the "upload" button in the Ardunio IDE. If you have the dev kit, follow the enclosed instructions to select the correct programmer in the IDE and everything should just work.    
+ 
+But you do not need the dev kit to write your own games. Blinks can be programmed with any Arduino-compatible "AVR ISP" programmer and there are hundreds of these available everywhere. You can even use an[ Arduino UNO board plus a few wires](https://www.arduino.cc/en/Tutorial/ArduinoISP#toc2) to program any blink though the 6-pin In System Programming (ISP) connector inside the battery compartment (the arrow marks pin #1). 
 
-In the future, we'll offer a simplified Arduino Boards Manager install path.
+## What is Arduino?
 
-### Notes 
+The Arduino IDE is an an integrated development environment that makes it easy to write and download code to compatible microcontroller boards - and every blink is an Arduino compatible board.
 
-* We called the "vendor/maintainer" folder `Move38-manual` so that you can also use the boards manager and you will be able to tell the two apart in the boards menu.
+We write a program in the IDE using Arduino programming language (basically the C/C++) and then we use a programmer to download the compiled program into a blink. 
 
-* You must manually create the `avr` folder and you must also manually move the files out from this repo into this folder. We could not automatically have the folds inside the repo match the Arduino required folder layout because in in the boards manager, the architecture is in the JSON file rather than the folder structure. Arg. 
+## The `blinklib` library
 
-* The "**~/Documents/Arduino/hardware/Move38-manual/avr**" folder is a Git repo and is also set up for easy editing in Atmel Studio with a solution inside the `\AS7` sub-folder. 
+When you pick "blink" from the boards menu, you configure the Arduino IDE to automatically include a set of binks-specific functions whenever it compiles your code. You use these functions to set the colors on the blink's LEDs and check for button presses and send messages over the IR links and everything else a blink can do. You can see all the available `blinklib` functions [here](cores/blinklib/blinklib.h).     
 
-### API Layers
+## Serial support
 
-The blinks hardware can do incredible things, and you can have unfettered access to it at any level you want. This documents describes those layers from bare metal up.  
+Each blink also has a built in serial port so you can add `printf` statements to your code and view the resulting output on a computer running a serial terminal program. Again, each blink dev kit includes a cable and a USB serial board to make this plug and play, but you can also connect the wires yourself to any serial port than can accept 3.3 - 5 volt signals. More info on serial [here](Service Port.MD).       
 
+## Making changes to the open source `blinklib` library
 
+You can make a fork of this repo and then clone it you the machine that you have the Arduino IDE installed on. Then add a symbolic link called `avr` to the top directory of the cloned repo (the directory with this readme in it) to the `Arduino/hardware/move38` directory. So, for example, on my windows machine I made the symbolic link with the commands...
 
-#### Hardware Abstraction Layer
+```
+d:
+cd D:\Documents\Arduino\hardware
+mkdir move38
+cd move38
+mklink /D avr D:\Github\Move38-Arduino-Platform
+```
 
-Most programmers will want to use the high level `blinks` API, but if you want to get closer to the hardware you can directly call into the `HAL` (Hardware Abstraction Layer) that the `blinks` API is built on top of. Documentation for this layer is in the [README.md](cores/blinkcore/README.md) in the `cores/blinkscore` folder.
+Quit out of the IDE and reload and you should see a new choice under the `boards` menu.
+
+We are always grateful for pull requests with bug fixes. For new features, best to discuss first [in the forums](https://forum.move38.com/c/softwareresources/9) to see what other think and if anyone is already working on something similar. 
+
+###

Production.MD

@@ -1,13 +1,13 @@
-This folder contains the BlinkBIOS bootloader HEX file. This file is created by the BlinkBIOS repo...
+This folder contains the BlinkBIOS bootloader HEX file. The BlinkBIOS is a hardware abstraction layer that is loaded into the bootloader area of flash.
 
-https://github.com/bigjosh/Move38-BlinkBIOS
-
-..and then copied here after each compile by an Atmel Studio post-build event. Note that the this bootloader directory is hardcoded into the text of that event. 
+The blinkBIOS is an abstraction layer that provides access to the blinks hardware and is defined by the `blinkbios_*.h` files in the `cores/blinklib/shared` directory. 
 
+Ideally we would like to program the BIOS once into each blink when it is manufactured and then only update the application section of the flash thereafter, but unfortunately on this chip the entire flash is always erased on each hardware programming cycle, so we must reprogram the bootloader each time. That is why this HEX file must be included here.
+  
 This file is used by...
 
-1. The `upload` and `program` recipes to download a new sketch to a blink. Note that we could make upload only update the actual program and not the BIOS for faster turnaround during development, but I do not want to change this behavior now. The path to the bootloader is hardcoded into the recipes but is relative to the platform folder.
-2. The `Export Binary` function which creates a single HEX file with both the current sketch and the BIOS. In this case, the folder name must be `bootloader` as this is hardcoded into the IDE. 
+1. The `program` recipe in `platform.txt` that downloads a new sketch to a blink. 
+2. The `Export Binary` function which creates a single HEX file with both the current sketch and the BIOS. Note that this folder must be named `bootloader` as this is hardcoded into the Arduino IDE. 
 
 
 

README.md

@@ -1322,9 +1322,6 @@ byte sin8_C( byte theta)
 
 #endif
 
-uint8_t __attribute__((weak)) sterileFlag = 0;             // Set to 1 to make this game sterile. Hopefully LTO will compile this away for us? (update: Whooha yes! )
-                                                           // We make `weak` so that the user program can override it
-
 // This is the main event loop that calls into the arduino program
 // (Compiler is smart enough to jmp here from main rather than call!
 //     It even omits the trailing ret!
@@ -1342,6 +1339,7 @@ void __attribute__((noreturn)) run(void)  {
     statckwatcher_init();   // Set up the sentinel byte at the top of RAM used by variables so we can tell if stack clobbered it
 
     setup();
+    
 
     while (1) {
 
@@ -1356,7 +1354,7 @@ void __attribute__((noreturn)) run(void)  {
         // Note that we directly read the shared block rather than our snapshot. This lets the 6 second flag latch and
         // so to the user program if we do not enter seed mode because we have neighbors. See?
 
-        if (( blinkbios_button_block.bitflags & BUTTON_BITFLAG_3SECPRESSED) && isAlone() && !sterileFlag ) {
+        if (( blinkbios_button_block.bitflags & BUTTON_BITFLAG_3SECPRESSED) && isAlone() ) {
 
             // Button has been down for 6 seconds and we are alone...
             // Signal that we are about to go into seed mode with full blue...

Tools.md

@@ -356,24 +356,6 @@ uint8_t hasWoken(void);
 
 uint8_t startState(void);
 
-// Make the current game sterile so that it can not be propagated to other blinks (niche) 
-// If sterileFlag==1 then holding the button down will never enter seed mode, it will just eventually sleep. 
-// This essentially means that once this built-in game is programmed into a blink it will not transfer to other blinks.
-
-// There are two ways you can use this. If you statically want a game to be sterile, you can add...
-// uint8_t sterileFlag=1;             // Make this game sterile. 
-// outside of any function block. This will completely disable all seeding and also give you some
-// extra flash memory since the seeding code does not even get linked into the executable (thanks gcc LTO!)
-// Alternately, you can use..
-// sterileFlag=1;
-// ...and...
-// sterileFlag=0;
-// inside your code to dynamically enable and disable seeding at any time.
-// NB: setting sterileFlag only suppress button-initiated seeds. 
-
-extern uint8_t sterileFlag;             // Set to 1 to make this game sterile. 
-
-
 /*
 
     These hook functions are filled in by the sketch