README.md 9.81 KB
Newer Older
Jake Read's avatar
Jake Read committed
1
# RNDMC
Jake Read's avatar
Jake Read committed
2

Jake Read's avatar
Jake Read committed
3
4
5
**Reconfigurable Numeric Dataflow Machine Controller**

*aka project 'consistent-sandbox'*
Jake Read's avatar
Jake Read committed
6

Jake Read's avatar
Jake Read committed
7
8
![img software](doc/images/atkapi.png)
![img hardware](doc/images/machine-with-atkapi.jpg)
Jake Read's avatar
Jake Read committed
9

Jake Read's avatar
Jake Read committed
10
11
12
13
14
15
This is a piece of software that is designed to help you assemble high level controllers from dataflow software elements. It serves a graphical programming interface, and is meant to live with dataflow hardware elements from [this project 'automatakit'](https://gitlab.cba.mit.edu/jakeread/automatakit).

It's in the early stages, so bear with us. Everything is going to be great. 

# Usage 

Jake Read's avatar
Jake Read committed
16
## Installing Node.js, WebSocket and SerialPort, and MathJS
Jake Read's avatar
Jake Read committed
17
18
19

To Run DMC, you'll need to install node.js, and then the packages serialport and ws (websocket).

Jake Read's avatar
Jake Read committed
20
### Install Node.js
Jake Read's avatar
Jake Read committed
21
22
23
24
25
26
27
28
29

Node.js is a runtime environment for javascript, so you can write and run js locally. [Download and install it here](https://nodejs.org/en/download/). 

To check that node is installed, you can use

``node -v``

In Windows check that in *Environment Variables, System Variables, Path* there is a path for C:\Users\yourusername\npm folder. If the folder does not exist, create it and set the path.  

Jake Read's avatar
Jake Read committed
30
31
32
33
34
35
36
37
### Packages

I've added a package.json file to the repo, which is [another cool node.js trick](https://docs.npmjs.com/files/package.json) - this means that to install everything, you should be able to (after downloading the repo and cd-ing into it) run:

```npm install```

This should install everything else. If this fails, you can install things one-by-one as listed below.

Jake Read's avatar
Jake Read committed
38
### Install Serialport
Jake Read's avatar
Jake Read committed
39
40
41
42
43
44
45
46
47

Node comes with a package controller called 'npm' - node package manager. You can use this to install dependencies for node programs. 

Serialport is a package for node that allows it to interact with a hardware serial port.

Navigate to the directory where you'll be running from (atkapi). Do

``npm install serialport``

Jake Read's avatar
Jake Read committed
48
### Install WS (WebSocket)
Jake Read's avatar
Jake Read committed
49
50
51
52
53
54

WebSockets are very simple web connections. We use them to chat between the 'server' / heap (node) and the 'view' (your browser).

To install ws, do

``npm install ws``
Jake Read's avatar
Jake Read committed
55

Jake Read's avatar
Jake Read committed
56
### Install MathJS 
Jake Read's avatar
Jake Read committed
57
58
59
60
61

MathJS is just a node package that does maths. To install, you guessed it, do

```npm install mathjs``` 

Jake Read's avatar
Jake Read committed
62
63
64
65
66
67
68
69
## Installing Serial Port Drivers

The ATKRouter uses a ```CP2102N``` USB-to-UART bridge to transmit and receive serial characters. 

[**Drivers are available for all platforms at SiLabs' Website**](https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers)

Download and install drivers, and check in your system's device manager that a 'CP210x USB to UART Bridge' appears.

Jake Read's avatar
Jake Read committed
70
71
72
# Running DMC

To run the program, we launch the main.js file with node, from the command line. One of the things this does is run a tiny HTTP server that we can use to access the UI.
Jake Read's avatar
Jake Read committed
73

Jake Read's avatar
Jake Read committed
74
75
76
77
78
79
cd to the rndmc folder and run: 

``node main``

It's handy to keep a terminal window open beside a browser when running the software - it's not perfect yet - I do this:

Jake Read's avatar
Jake Read committed
80
![term](doc/images/termopen.png)
Jake Read's avatar
Jake Read committed
81
82
83
84
85
86
87
88
89
90

This way I can watch for errors, and restart it when it crashes. Hopefully not a lot of this will happen.

## Open a Browser

The program is now running a tiny HTTP server, where it will deliver an interface. It's set to show up at your local address on port 8080.

In a browser open *localhost:8080* you will see the mods and this msg in the terminal *SEND PROGRAMS TO UI* 

## Using the Browser Interface 
Jake Read's avatar
Jake Read committed
91

Jake Read's avatar
Jake Read committed
92
![img moving](doc/images/mothermother.gif)
Jake Read's avatar
Jake Read committed
93

Jake Read's avatar
Jake Read committed
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
**Words of Warning** 

This is very new software, so bear with me. It's worth having whomever on the team is in charge of controls read the section (below) on what-all is going on with the software, and understanding how to write new modules, and assemble programs. 

#### Getting Around

To navigate, you can scroll in-and-out (try this once there is actually a program loaded) and drag to pan around.

#### Loading a Program

To load a program, hit 'l' on your keyboard. This will open a menu of all of the .json program representations in the /programs directory.

There is an example program there, that will do acceleration-controlled motion with gcode as input. 

#### Loading a Module

To load a module, right-click anywhere on the screen. 

#### Deleting a Module

To delete or copy a module, right-click on its title. 

#### Connecting Outputs to Inputs

Once loaded, modules can be connected by first clicking on the *output* of one and the *input* of another. This will cause events on that output to call events associated with the input.

#### Disconnecting Outputs from Inputs

To disconnect, click the output to disconnect, and then the input to disconnect it from. 
Jake Read's avatar
Jake Read committed
123

Jake Read's avatar
Jake Read committed
124
125
# Troubleshooting

Jake Read's avatar
Jake Read committed
126
127
128
129
130
- ?

# RuNDMC Architecture 


Jake Read's avatar
Jake Read committed
131

Jake Read's avatar
Jake Read committed
132
133
# Writing New Modules 

Jake Read's avatar
Jake Read committed
134
135
 - whenever a menu is requested, the system searches ```modules/ * ``` for *anything*. include your .js of a new module there 
 - anything goes: you can run whatever code will run in node.js ... just follow these simple rules 
Jake Read's avatar
Jake Read committed
136
137
138
139
140
141
142
143
 - TODO: put example here, with comments 

# Writing Hardware Modules 

 - TODO: same, also including links / explanation to atk 

# Development Notes 

Jake Read's avatar
Jake Read committed
144
145
## For MW

Jake Read's avatar
Jake Read committed
146
147
148
 - want that better-planner
 - do axis pullout separately from stepper motor ?

149
150
151
152
153
154
 - bug hunting
  - dereferenced events / stepper axis vector 
  - multiple button calls ... 
  - stepper / planner bug 
  - is load / save really consistent ? what is the state answer ? 

Jake Read's avatar
Jake Read committed
155
- title is still 'xperiment'
156
157
- stepper move.vector is a ref issue? derefed before running calcTrap() ? runs ? in planner ? 

Jake Read's avatar
Jake Read committed
158
- example modules 
Jake Read's avatar
notes    
Jake Read committed
159

Jake Read's avatar
Jake Read committed
160
161
- add reset button to hardware
- add router for reset, test 
162

Jake Read's avatar
OK    
Jake Read committed
163
## Documentation
Jake Read's avatar
notes    
Jake Read committed
164
- GIFS
Jake Read's avatar
Jake Read committed
165

Jake Read's avatar
Jake Read committed
166
## Questionable Moves
Jake Read's avatar
notes    
Jake Read committed
167
- module deletion seems unclean 
Jake Read's avatar
Jake Read committed
168
 - input / output objects should be able to unhook themselves: 
Jake Read's avatar
notes    
Jake Read committed
169
 - keep references of what-is-attached ? 
Jake Read's avatar
Jake Read committed
170

Jake Read's avatar
Jake Read committed
171
172
## WRT Representations

Jake Read's avatar
OK    
Jake Read committed
173
OK, should write this out properly at some point.
Jake Read's avatar
Jake Read committed
174
175
176
177
178
179

Module have 
 Inputs
 Outputs
 State (initial states are settings)

Jake Read's avatar
notes    
Jake Read committed
180
181
182
183
184
Hardware Modules have
 routes
 connected to 
 links 

Jake Read's avatar
Jake Read committed
185
186
187
188
189
190
Also
 Names, IDs
 Paths-to-source 

To assemble a representation of these, we want to have a kind of 'netlist' that, for convenience, we'll treat like a JSON object. We want heirarchy, so consider the representation having 'top-level' outputs / inputs / state as well ? 

Jake Read's avatar
Jake Read committed
191
## Programming Notes
Jake Read's avatar
Jake Read committed
192

Jake Read's avatar
Jake Read committed
193
194
195
196
### 15 Minute Tasks 
 - @ views.js, uiRequestModuleMenu and uiRequestProgramMenu don't properly build trees from folder structure. similarly, reciprical fn's in client.js do the same 
 - @ these load / save functions could also reach into the modules' source to retrieve their proper names, as spec'd in description ... 
 - 's' for save program uses hack-asf DOM alert to ask for path
Jake Read's avatar
Jake Read committed
197

Jake Read's avatar
notes    
Jake Read committed
198
## Desires 
Jake Read's avatar
Jake Read committed
199
- heirarchy zoom 
Jake Read's avatar
notes    
Jake Read committed
200
 - architectural clarity betwixt UI and Heap 
201
- some auto load / save currently.json file so that we can restart program w/o pain ... maybe just save on new user inputs ? 
Jake Read's avatar
Jake Read committed
202
203
- state.setDefault('var', num) or etc / types
- perhaps all state objects like this ... still somehow state.var = // is a good operator ? don't really want state.var.set(num) and state.var.get() 
Jake Read's avatar
Jake Read committed
204
205
206
207
208
209
210
- states / uis / etc - one off / one-at-a-time for updates 
 - i.e. all f'n update calls are to single module-global state update
 - ! 
- states / getters / setters not applicable to sub-elements in an object within state
 - i.e. array access 
- consistent dereferencing, type checking implementation?

Jake Read's avatar
notes    
Jake Read committed
211
212
213
214
215
216
217
## UI Desires
- modules have visual ways to throw errors - i.e. flashing red, popping up... 
- off-screen divs get pointers-to so that we don't get lost
  - 'h' or something to zoom-to-extents
- better module menu
- hover for alt descriptions 

Jake Read's avatar
Jake Read committed
218
219
## Planner Bugs
 - trapezoid linking doesn't account for speed changes properly, i.e. doesn't ramp down into next move if next move's cruise speed is less than our exit speed 
Jake Read's avatar
notes    
Jake Read committed
220
 - should have some stronger ideas about flow control, allowable segment size (based on time) 
Jake Read's avatar
Jake Read committed
221

Jake Read's avatar
notes    
Jake Read committed
222
## Want 
Jake Read's avatar
Jake Read committed
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
- log() for logs-from-module tagged 

## Demo Desires 
- want to show immediacy of hardware: software representation
- want to show physical reconfigurability and software reconfigurability
 - i.e. mill, add rotary tool, pull normal vector from planner moves and route to r motor 
- want to have UI elements
 - button, terminal, 
- live motor torque display, vector from accelerometer 

## Network Desires
- c improvements / dma etc, would be very cool
- flow control probably desired ... what can we model with uart and implement with fpga?
- proper speed tests
- DMA not possible / not enough channels for router implementation / not portable enough ... 
- lights displaying activity

## Bugs
- cannot connect input to output w/o backwards bezier 
Jake Read's avatar
Jake Read committed
242
- when source has changed, opening programs that have references to that source should be carefully done ... 
243

Jake Read's avatar
Jake Read committed
244
245
# The RPI

Jake Read's avatar
Jake Read committed
246
247
248
249
One of the desires here is to run programs headlessly on small embedded computers like the Raspberry Pi. The router has pogo-pins for this, so that when it's mounted beneath a Raspberry Pi the USB and Power lines are automatically hooked up - the 2A Buck Converter on the Router can also be used to power the RPI, so it can all run on one DC power bus. Nice! 

![ATKRouter](https://gitlab.cba.mit.edu/jakeread/atkrouter/raw/master/images/atkrouter.jpg)

Jake Read's avatar
Jake Read committed
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
### Setup the Raspberry Pi

 - [download raspbian](https://www.raspberrypi.org/documentation/installation/installing-images/README.md)
 - [flash and boot, setup etc](https://www.raspberrypi.org/documentation/setup/)

### Install Node on the Raspberry Pi

 - to install node, download the distro you want from nodejs.org 
 - extract the files, and hit these commands

navigate to the distribution
`` cd <distro> `` 
copy that to local space on the pi
`` sudo cp -R * /usr/local/ ``

to check that node is installed, check the version using
`` node -v ``
which should return the version number of the distro you installed.

Jake Read's avatar
Jake Read committed
269
270
However:

Jake Read's avatar
notes    
Jake Read committed
271
``` need to figure out how to get the RPI serialport to talk ``` 
Jake Read's avatar
Jake Read committed
272
273

- https://cnc.js.org/ 
Jake Read's avatar
Jake Read committed
274
275
276
- https://github.com/cncjs/cncjs/wiki/Setup-Guide:-Raspberry-Pi-%7C-Install-Node.js-via-Node-Version-Manager-(NVM)