Contributing

CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contribution Guidelines
+
+STM8 eForth is a community project, and contributions are highly appreciated!
+
+Here are some guidelines for contributing:
+
+* Of course there are bugs, and we hate them. If you find one, please file an issue! If you can fix it, please make a pull request!
+* The same goes for less-than-acceptable grammar, or wrong/outdated contents in the docs. Please propose how to improve it (e.g. using a [Gist](https://gist.github.com/)).
+* Please check the issues to see if there's anything related to your contribution. Feel free to comment on closed issues if you feel that the root cause has not been fixed.
+* If you're looking for things to work on please check for [open issues](https://github.com/TG9541/stm8ef/issues), or for cards in the project [boards](https://github.com/TG9541/stm8ef/projects)!
+* If you need a new feature that you think would be an improvement please also file an issue. Describe what you need, why you need it, and the acceptance criteria of a solution.
+
+## Pull Requests
+
+* Please fork the repository.
+* Make your changes in a well-named topic branch.
+* Submit your pull request. Please [reference an issue](https://help.github.com/articles/closing-issues-using-keywords/) (i.e. `resolves #..` ) if it's related to one.
+
+## Coding Style
+
+General:
+* please use Unix line endings,
+* avoid trailing whitespace,
+* and don't use tabs
+
+For Forth code please use [Brodie style](http://www.forth.org/forth_style.html):
+* after colon: 1 space
+* after a defined name: 2 space
+* after stack comment: 2 space (or newline)
+* separate phrases on same line: 3 spaces
+* indent: 3 spaces
+* keep lines shorter than 64 characters
+* use the `mcu/`, and the `lib/` folders (subset of the e4thcom search path)
+
+For assembly code, please use the following formatting:
+* keep lines shorter than 80 characters
+* use upper case mnemonics
+* line comments: semicolon as the first character, start of comment in column 8
+* in-line comments: try to place the semicolon on column 34
+
+## Licensing & Legal Stuff
+
+Please don't contribute code that doesn't fit our [ISC](https://en.wikipedia.org/wiki/ISC_license) style license. 
+If the code isn't yours, or if you don't have the original authors permission to use it under the terms of the license, then please don't put it in a pull request it!

docs/words.md

@@ -545,7 +545,7 @@
 ```
 
 ```
-;       HERE    ( -- a )      ( TOS STM8: -- A,Z,N )
+;       HERE    ( -- a )      ( TOS STM8: -- Y,Z,N )
 ;       Return  top of  code dictionary.
 ```
 

tools/codeloadTCP.py

@@ -6,7 +6,6 @@
 #   2. path of the including file
 #   3. `cwd`/lib
 # Limitations:
-# - no error detection
 # - #require does the same as #include (no conditional uploading)
 # - the telnet port is fixed (localhost 10000)
 
@@ -58,15 +57,16 @@ def upload(path):
                     continue
                 if len(line) > 64:
                     raise ValueError('Line is too long: %s' % (line))
-                print('sending: ' + line)
+                print('TX: ' + line)
                 tn.write(line + '\r')
-                result = tn.expect(['.*\?\r\n', '.*k\r\n', '\r\n'],3)[0]
+                result = tn.expect(['\?\a\r\n', 'k\r\n', 'K\r\n'],3)[0]
                 if result<0:
                     raise ValueError('timeout %s' % (line))
                 elif result == 0:
                     raise ValueError('error %s' % (line))
         except ValueError as err:
-            print(err.args)
+            print(err.args[0])
+            exit(1)
 
 for path in sys.argv[1:]:
     upload(path)

tools/simload.sh

@@ -16,12 +16,16 @@ read -d '' setbreak << 'EOF'
 EOF
 gawk "$setbreak" out/$object/forth.rst >> "$ucsimstart"
 
+echo "simload.sh: starting uCsim"
+
 # start simulator, it's set to break at HI
 sstm8 -w -C$ucsimstart -g -Z10001 -tS103 -Suart=1,port=10000 &
+sleep 1.0
 
 # wait, inject uart code patch, and start over
-sleep 0.2
-nc localhost 10001 <<EOF
+echo "simload.sh: injecting UART code"
+
+nc -w 1 localhost 10001 <<EOF
 download
 :04006000100010205C
 :1010000090AE680390CF5232350C523535100061e6
@@ -32,6 +36,7 @@ download
 run
 EOF
 
+
 # STM8EF: set RESET defaults to include the newly defined words
 export persist=`mktemp`
 cat << 'EOF' > "$persist"
@@ -41,8 +46,13 @@ RAM
 EOF
 
 # wait some more, start transferring Forth code
-sleep 0.8
-tools/codeloadTCP.py "$object/board.fs" "$persist"
+sleep 1.0
+
+echo "simload.sh: running codeloadTCP.py $object/board.fs persist"
+
+tools/codeloadTCP.py "$object/board.fs" "$persist" || exit
+
+echo "simload.sh: injecting UART code"
 
 # gawk: uCsim "dch" dump to Intel HEX conversion
 read -d '' makeHex << 'EOF'
@@ -60,8 +70,11 @@ function App(x,n) {
 EOF
 
 # dump flash data, convert to Intel Hex, kill uCsim
-nc localhost 10001 <<EOF | gawk "$makeHex" > "out/$object/$object-forth.ihx"
+echo "simload.sh: loading $object binary"
+
+nc -w 1 localhost 10001 <<EOF | gawk "$makeHex" > "out/$object/$object-forth.ihx"
 dch 0x8000 0x9FFF 16
 kill
 EOF
 
+echo "simload.sh: bye"