Docs

Author: matteosuppo

programmer/README.md

@@ -0,0 +1,140 @@
+use 'godoc cmd/github.com/arduino/arduino-create-agent/programmer' for documentation on the github.com/arduino/arduino-create-agent/programmer command 
+
+Package programmer
+=====================
+
+    import "github.com/arduino/arduino-create-agent/programmer"
+
+Package programmer allows to upload sketches into a board connected to the
+computer It can do it via serial port or via network
+
+**Usage for a serial upload**
+
+Make sure that you have a compiled sketch somewhere on your disk
+
+```go
+commandline = ``"/usr/bin/avrdude" "-C/usr/bin/avrdude.conf" -v -patmega32u4 -cavr109 -P/dev/ttyACM0 -b57600 -D "-Uflash:w:./sketch.hex:i"``
+err := programmer.Serial("/dev/ttyACM0", commandline, programmer.Extra{}, nil)
+```
+
+note that the commandline contains the path of the sketch (sketch.hex)
+
+**Usage for a network upload**
+
+Make sure that you have a compiled sketch somewhere on your disk
+
+```go
+ err := programmer.Network("127.0.10.120", "arduino:avr:yun, "./sketch.hex", "", programmer.Auth{}, nil)
+```
+
+The commandline can be empty or it can contain instructions (depends on the
+board)
+
+**Resolving commandlines**
+
+If you happen to have an unresolved commandline (full of {} parameters) you can
+resolve it
+
+```go
+ t := tools.Tools{}
+ commandline = programmer.Resolve("/dev/ttyACM0", "arduino:avr:leonardo", "./sketch.hex", commandline, programmer.Extra{}, t)
+ ```
+
+t must implement the locater interface (the Tools package does!)
+
+**Logging** If you're interested in the output of the commands, you can
+implement the logger interface. Here's an example:
+
+```go
+ logger := logrus.New()
+ logger.Level = logrus.DebugLevel
+ programmer.Serial("/dev/ttyACM0", commandline, programmer.Extra{}, logger)
+ ```
+
+
+
+Variables
+---------
+
+
+```go
+var Busy = false
+```
+Busy tells wether the programmer is doing something
+
+Functions
+---------
+
+
+```go
+func Kill()
+```
+
+Kill stops any upload process as soon as possible
+
+
+```go
+func Network(port, board, file, commandline string, auth Auth, l Logger) error
+```
+
+Network performs a network upload
+
+
+```go
+func Resolve(port, board, file, commandline string, extra Extra, t Locater) (string, error)
+```
+
+Resolve replaces some symbols in the commandline with the appropriate values it
+can return an error when looking a variable in the Locater
+
+
+```go
+func Serial(port, commandline string, extra Extra, l Logger) error
+```
+
+Serial performs a serial upload
+
+Types
+-----
+
+
+```go
+type Auth struct {
+    Username string `json:"username"`
+    Password string `json:"password"`
+}
+```
+Auth contains username and password used for a network upload
+
+
+```go
+type Extra struct {
+    Use1200bpsTouch   bool   `json:"use_1200bps_touch"`
+    WaitForUploadPort bool   `json:"wait_for_upload_port"`
+    Network           bool   `json:"network"`
+    Auth              Auth   `json:"auth"`
+    Verbose           bool   `json:"verbose"`
+    ParamsVerbose     string `json:"params_verbose"`
+    ParamsQuiet       string `json:"params_quiet"`
+}
+```
+Extra contains some options used during the upload
+
+
+```go
+type Locater interface {
+    GetLocation(command string) (string, error)
+}
+```
+Locater can return the location of a tool in the system
+
+
+```go
+type Logger interface {
+    Debug(args ...interface{})
+    Info(args ...interface{})
+}
+```
+Logger is an interface implemented by most loggers (like logrus)
+
+

programmer/doc.go

@@ -0,0 +1,44 @@
+// Package programmer allows to upload sketches into a board connected to the computer
+// It can do it via serial port or via network
+//
+// **Usage for a serial upload**
+//
+// Make sure that you have a compiled sketch somewhere on your disk
+//
+//   ```go
+//   commandline = ``"/usr/bin/avrdude" "-C/usr/bin/avrdude.conf" -v -patmega32u4 -cavr109 -P/dev/ttyACM0 -b57600 -D "-Uflash:w:./sketch.hex:i"``
+//   err := programmer.Serial("/dev/ttyACM0", commandline, programmer.Extra{}, nil)
+//   ```
+//
+// note that the commandline contains the path of the sketch (sketch.hex)
+//
+// **Usage for a network upload**
+//
+// Make sure that you have a compiled sketch somewhere on your disk
+//
+//   ```go
+//    err := programmer.Network("127.0.10.120", "arduino:avr:yun, "./sketch.hex", "", programmer.Auth{}, nil)
+//   ```
+//
+// The commandline can be empty or it can contain instructions (depends on the board)
+//
+// **Resolving commandlines**
+//
+// If you happen to have an unresolved commandline (full of {} parameters) you can resolve it
+//
+//   ```go
+//    t := tools.Tools{}
+//    commandline = programmer.Resolve("/dev/ttyACM0", "arduino:avr:leonardo", "./sketch.hex", commandline, programmer.Extra{}, t)
+//    ```
+//
+// t must implement the locater interface (the Tools package does!)
+//
+// **Logging**
+// If you're interested in the output of the commands, you can implement the logger interface. Here's an example:
+//
+//   ```go
+//    logger := logrus.New()
+//    logger.Level = logrus.DebugLevel
+//    programmer.Serial("/dev/ttyACM0", commandline, programmer.Extra{}, logger)
+//    ```
+package programmer

programmer/programmer.go

@@ -44,8 +44,8 @@ type Extra struct {
 }
 
 // Resolve replaces some symbols in the commandline with the appropriate values
-// it can return an error when looking a variable in the locater
-func Resolve(port, board, file, commandline string, extra Extra, t locater) (string, error) {
+// it can return an error when looking a variable in the Locater
+func Resolve(port, board, file, commandline string, extra Extra, t Locater) (string, error) {
 	commandline = strings.Replace(commandline, "{build.path}", filepath.ToSlash(filepath.Dir(file)), -1)
 	commandline = strings.Replace(commandline, "{build.project_name}", strings.TrimSuffix(filepath.Base(file), filepath.Ext(filepath.Base(file))), -1)
 	commandline = strings.Replace(commandline, "{serial.port}", port, -1)
@@ -57,7 +57,7 @@ func Resolve(port, board, file, commandline string, extra Extra, t locater) (str
 		commandline = strings.Replace(commandline, "{upload.verbose}", extra.ParamsQuiet, -1)
 	}
 
-	// search for runtime variables and replace with values from locater
+	// search for runtime variables and replace with values from Locater
 	var runtimeRe = regexp.MustCompile("\\{(.*?)\\}")
 	runtimeVars := runtimeRe.FindAllString(commandline, -1)
 
@@ -74,7 +74,7 @@ func Resolve(port, board, file, commandline string, extra Extra, t locater) (str
 }
 
 // Network performs a network upload
-func Network(port, board, file, commandline string, auth Auth, l logger) error {
+func Network(port, board, file, commandline string, auth Auth, l Logger) error {
 	Busy = true
 
 	// Defaults
@@ -97,7 +97,7 @@ func Network(port, board, file, commandline string, auth Auth, l logger) error {
 }
 
 // Serial performs a serial upload
-func Serial(port, commandline string, extra Extra, l logger) error {
+func Serial(port, commandline string, extra Extra, l Logger) error {
 	Busy = true
 	defer func() { Busy = false }()
 
@@ -128,7 +128,7 @@ func Kill() {
 
 // reset opens the port at 1200bps. It returns the new port name (which could change
 // sometimes) and an error (usually because the port listing failed)
-func reset(port string, wait bool, l logger) (string, error) {
+func reset(port string, wait bool, l Logger) (string, error) {
 	info(l, "Restarting in bootloader mode")
 
 	// Get port list before reset
@@ -169,7 +169,7 @@ func reset(port string, wait bool, l logger) (string, error) {
 // waitReset is meant to be called just after a reset. It watches the ports connected
 // to the machine until a port disappears and reappears. The port name could be different
 // so it returns the name of the new port.
-func waitReset(beforeReset []string, l logger) string {
+func waitReset(beforeReset []string, l Logger) string {
 	var port string
 	timeout := false
 
@@ -220,8 +220,8 @@ func waitReset(beforeReset []string, l logger) string {
 var cmd *exec.Cmd
 
 // program spawns the given binary with the given args, logging the sdtout and stderr
-// through the logger
-func program(binary string, args []string, l logger) error {
+// through the Logger
+func program(binary string, args []string, l Logger) error {
 	defer func() { cmd = nil }()
 
 	// remove quotes form binary command and args
@@ -280,7 +280,7 @@ func program(binary string, args []string, l logger) error {
 	return nil
 }
 
-func form(port, board, file string, auth Auth, l logger) error {
+func form(port, board, file string, auth Auth, l Logger) error {
 	// Prepare a form that you will submit to that URL.
 	_url := "http://" + port + "/data/upload_sketch_silent"
 	var b bytes.Buffer
@@ -342,7 +342,7 @@ func form(port, board, file string, auth Auth, l logger) error {
 	return nil
 }
 
-func ssh(port, file, commandline string, auth Auth, l logger) error {
+func ssh(port, file, commandline string, auth Auth, l Logger) error {
 	// Connect via ssh
 	client, err := simplessh.ConnectWithPassword(port+":22", auth.Username, auth.Password)
 	debug(l, "Connect via ssh ", client, err)

programmer/programmer_test.go

@@ -39,7 +39,6 @@ func TestSerial(t *testing.T) {
 		err := programmer.Do(test.Port, commandline, test.Extra, logger)
 		log.Println(err)
 	}
-	t.Fail()
 }
 
 var TestNetworkData = []struct {
@@ -64,7 +63,6 @@ func TestNetwork(t *testing.T) {
 		err := programmer.Do(test.Port, commandline, test.Extra, logger)
 		log.Println(err)
 	}
-	t.Fail()
 }
 
 var TestResolveData = []struct {

programmer/utils.go

@@ -1,24 +1,25 @@
 package programmer
 
-type logger interface {
+// Logger is an interface implemented by most loggers (like logrus)
+type Logger interface {
 	Debug(args ...interface{})
 	Info(args ...interface{})
 }
 
-func debug(l logger, args ...interface{}) {
+func debug(l Logger, args ...interface{}) {
 	if l != nil {
 		l.Debug(args...)
 	}
 }
 
-func info(l logger, args ...interface{}) {
+func info(l Logger, args ...interface{}) {
 	if l != nil {
 		l.Info(args...)
 	}
 }
 
-// locater can return the location of a tool in the system
-type locater interface {
+// Locater can return the location of a tool in the system
+type Locater interface {
 	GetLocation(command string) (string, error)
 }