NeuroscienceEngineeringSyndicate/guides.html at main · SainsburyWellcomeCentre/NeuroscienceEngineeringSyndicate · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <meta name="description" content="Standardised guides for contributing engineering solutions to the Neuroscience Engineering Syndicate.">
  <title>Guides — NES</title>
  <link rel="icon" type="image/png" href="assets/nes-logo.png">
  <link rel="stylesheet" href="css/style.css">
</head>
<body>
  <!-- ===== Navbar ===== -->
  <nav class="navbar" id="navbar">
    <div class="container">
      <a href="index.html" class="nav-brand">
        <img src="assets/nes-logo.png" alt="NES Logo">
        <span><span class="brand-accent">NES</span></span>
      </a>
      <div class="nav-links" id="navLinks">
        <a href="index.html">Home</a>
        <a href="solutions.html">Solutions</a>
        <a href="guides.html" class="active">Guides</a>
        <a href="https://github.com/SainsburyWellcomeCentre/NeuroscienceEngineeringSyndicate" target="_blank" rel="noopener">GitHub</a>
      </div>
      <button class="nav-toggle" id="navToggle" aria-label="Toggle navigation">
        <span></span><span></span><span></span>
      </button>
    </div>
  </nav>

  <!-- ===== Page Header ===== -->
  <header class="page-header">
    <div class="container">
      <h1>Contribution <span class="accent-text">Guides</span></h1>
      <p>Everything you need to know about sharing your engineering solutions with the Syndicate — from repository structure to submission workflow.</p>
    </div>
  </header>

  <!-- ===== Guides Content ===== -->
  <section class="section">
    <div class="container guides-content">

      <!-- Guide 1: Repository Structure -->
      <div class="guide-section">
        <div class="section-label">Standards</div>
        <h2 class="section-title" style="font-size: var(--fs-xl);">Repository Structure</h2>
        <p class="section-subtitle" style="margin-bottom: var(--space-xl);">
          A consistent structure makes it easy for anyone to understand and reproduce your solution.
        </p>

        <div class="accordion-item open" id="acc-repo-template">
          <button class="accordion-trigger" aria-expanded="true">
            <span>&#x1F4C1; Recommended Repository Template</span>
            <span class="chevron">&#x25BC;</span>
          </button>
          <div class="accordion-body" style="max-height: 2000px;">
            <div class="accordion-body-inner">
              <h4>Directory layout</h4>
              <pre><code>your-solution/
├── README.md              # Overview, photos, quick-start
├── LICENSE                 # Open-source licence file
├── docs/
│   ├── assembly-guide.md  # Step-by-step assembly
│   ├── wiring-diagram.png # Wiring / connection diagram
│   └── troubleshooting.md # Common issues & fixes
├── hardware/
│   ├── pcb/               # KiCad / Eagle project files
│   ├── cad/               # STEP / STL / F3D files
│   └── bom.csv            # Bill of materials
├── firmware/
│   └── src/               # Microcontroller source code
├── software/
│   └── src/               # Host-side software / GUI
└── tests/
    └── ...                # Validation scripts / data</code></pre>
              <h4>Key files</h4>
              <ul>
                <li><code>README.md</code> — must include a short description, photo/render, and a "Quick Start" section</li>
                <li><code>LICENSE</code> — we recommend <code>CERN-OHL-S-2.0</code> for hardware and <code>MIT</code> or <code>BSD-3-Clause</code> for software</li>
                <li><code>bom.csv</code> — use columns: <code>Reference, Value, Quantity, Manufacturer, MPN, Supplier, Supplier PN</code></li>
              </ul>
            </div>
          </div>
        </div>

        <div class="accordion-item" id="acc-readme-template">
          <button class="accordion-trigger" aria-expanded="false">
            <span>&#x1F4DD; README Template</span>
            <span class="chevron">&#x25BC;</span>
          </button>
          <div class="accordion-body">
            <div class="accordion-body-inner">
              <h4>Recommended README sections</h4>
              <pre><code># Solution Title

![Photo or render](docs/hero-image.png)

## Overview
Brief description of what this solution does and why it exists.

## Specifications
| Parameter       | Value       |
|-----------------|-------------|
| Channels        | 32          |
| Sampling rate   | 30 kHz      |
| Input noise     | &lt; 2 µV RMS |

## Quick Start
1. Order parts from `hardware/bom.csv`
2. Fabricate PCB using files in `hardware/pcb/`
3. Flash firmware: `cd firmware && make flash`

## Assembly
See [Assembly Guide](docs/assembly-guide.md).

## Contributing
PRs welcome — see the NES contribution guidelines.

## Licence
CERN-OHL-S-2.0</code></pre>
            </div>
          </div>
        </div>
      </div>

      <!-- Guide 2: Documentation Standards -->
      <div class="guide-section">
        <div class="section-label">Documentation</div>
        <h2 class="section-title" style="font-size: var(--fs-xl);">Documentation Standards</h2>
        <p class="section-subtitle" style="margin-bottom: var(--space-xl);">
          Good documentation is the difference between a solution that's adopted and one that's forgotten.
        </p>

        <div class="accordion-item" id="acc-photos">
          <button class="accordion-trigger" aria-expanded="false">
            <span>&#x1F4F7; Photos &amp; Diagrams</span>
            <span class="chevron">&#x25BC;</span>
          </button>
          <div class="accordion-body">
            <div class="accordion-body-inner">
              <h4>Required visuals</h4>
              <ul>
                <li><strong>Hero image</strong> — a clear photo or 3D render of the finished solution, placed in <code>README.md</code></li>
                <li><strong>Wiring diagram</strong> — annotated diagram showing all electrical connections</li>
                <li><strong>Assembly photos</strong> — key steps in the build process (compressed to &lt; 500 KB each)</li>
              </ul>
              <h4>File formats</h4>
              <ul>
                <li>Photos: <code>.png</code> or <code>.jpg</code> (avoid raw camera files)</li>
                <li>Schematics: export as PDF alongside native project files</li>
                <li>3D models: include <code>.step</code> for interchange and <code>.stl</code> for quick preview</li>
              </ul>
            </div>
          </div>
        </div>

        <div class="accordion-item" id="acc-bom">
          <button class="accordion-trigger" aria-expanded="false">
            <span>&#x1F4CB; Bill of Materials (BOM)</span>
            <span class="chevron">&#x25BC;</span>
          </button>
          <div class="accordion-body">
            <div class="accordion-body-inner">
              <h4>BOM format</h4>
              <p>Use a CSV file (<code>hardware/bom.csv</code>) with the following columns:</p>
              <pre><code>Reference,Value,Quantity,Manufacturer,MPN,Supplier,Supplier_PN,Notes
C1,100nF,10,Murata,GRM155R71C104KA88D,DigiKey,490-1318-1-ND,0402
R1,10k,5,Yageo,RC0402FR-0710KL,DigiKey,311-10.0KLRCT-ND,0402</code></pre>
              <ul>
                <li>Always include manufacturer part numbers (MPN) — these are globally unique</li>
                <li>Include at least one supplier and supplier PN for ease of ordering</li>
                <li>Add a <code>Notes</code> column for package size, tolerance, or substitution guidance</li>
              </ul>
            </div>
          </div>
        </div>
      </div>

      <!-- Guide 3: Submission Workflow -->
      <div class="guide-section">
        <div class="section-label">Workflow</div>
        <h2 class="section-title" style="font-size: var(--fs-xl);">Submitting a Solution</h2>
        <p class="section-subtitle" style="margin-bottom: var(--space-xl);">
          Adding your solution to the NES database is a simple Git-based workflow.
        </p>

        <div class="accordion-item" id="acc-submit">
          <button class="accordion-trigger" aria-expanded="false">
            <span>&#x1F6E0;&#xFE0F; Step-by-Step Submission</span>
            <span class="chevron">&#x25BC;</span>
          </button>
          <div class="accordion-body">
            <div class="accordion-body-inner">
              <h4>1. Prepare your repository</h4>
              <ul>
                <li>Follow the repository structure template above</li>
                <li>Ensure your README includes a hero image, specs table, and quick-start</li>
                <li>Include a licence file</li>
              </ul>
              <h4>2. Fork the NES website repo</h4>
              <pre><code>git clone https://github.com/SainsburyWellcomeCentre/NeuroscienceEngineeringSyndicate.git
cd NeuroscienceEngineeringSyndicate</code></pre>
              <h4>3. Add your entry to <code>data/solutions.json</code></h4>
              <pre><code>{
  "id": "your-institute-short-name",
  "title": "Your Solution Title",
  "institute": "Your Institute Name",
  "instituteShort": "ABBR",
  "description": "A concise (1-2 sentence) description.",
  "tags": ["hardware", "electrophysiology"],
  "repo": "https://github.com/your-org/your-repo",
  "updated": "2026-03-16",
  "licence": "MIT"
}</code></pre>
              <h4>4. Open a Pull Request</h4>
              <ul>
                <li>Title: <code>Add: Your Solution Title</code></li>
                <li>Description: link to your repo, a screenshot/photo, and a brief rationale</li>
                <li>A maintainer will review within 5 working days</li>
              </ul>
            </div>
          </div>
        </div>

        <div class="accordion-item" id="acc-review">
          <button class="accordion-trigger" aria-expanded="false">
            <span>&#x2705; Review Criteria</span>
            <span class="chevron">&#x25BC;</span>
          </button>
          <div class="accordion-body">
            <div class="accordion-body-inner">
              <h4>What reviewers check</h4>
              <ul>
                <li><strong>Completeness</strong> — does the repo contain everything needed to reproduce the solution?</li>
                <li><strong>Documentation</strong> — is there a clear README with assembly/usage instructions?</li>
                <li><strong>Licensing</strong> — is an appropriate open-source licence applied?</li>
                <li><strong>Quality</strong> — are schematics, code, and CAD files of reasonable quality?</li>
                <li><strong>JSON entry</strong> — does the solutions.json entry follow the schema and link to a valid repo?</li>
              </ul>
              <h4>Common reasons for revision requests</h4>
              <ul>
                <li>Missing BOM or assembly instructions</li>
                <li>No hero image in the README</li>
                <li>Proprietary licence or no licence at all</li>
                <li>Broken repository link</li>
              </ul>
            </div>
          </div>
        </div>
      </div>

      <!-- Guide 4: Licensing -->
      <div class="guide-section">
        <div class="section-label">Legal</div>
        <h2 class="section-title" style="font-size: var(--fs-xl);">Licensing Recommendations</h2>
        <p class="section-subtitle" style="margin-bottom: var(--space-xl);">
          Open licensing ensures your work can be freely used, modified, and shared by other institutes.
        </p>

        <div class="accordion-item" id="acc-licence">
          <button class="accordion-trigger" aria-expanded="false">
            <span>&#x2696;&#xFE0F; Choosing a Licence</span>
            <span class="chevron">&#x25BC;</span>
          </button>
          <div class="accordion-body">
            <div class="accordion-body-inner">
              <h4>Recommended licences by category</h4>
              <ul>
                <li><strong>Hardware (PCB, mechanical)</strong> — <code>CERN-OHL-S-2.0</code> (strongly reciprocal) or <code>CERN-OHL-W-2.0</code> (weakly reciprocal)</li>
                <li><strong>Software / Firmware</strong> — <code>MIT</code>, <code>BSD-3-Clause</code>, or <code>GPL-3.0</code></li>
                <li><strong>Documentation</strong> — <code>CC-BY-4.0</code></li>
              </ul>
              <h4>Why CERN-OHL for hardware?</h4>
              <p>
                The CERN Open Hardware Licence was specifically designed for open hardware projects.
                Unlike software licences, it addresses physical manufacturing, distribution of
                modified designs, and attribution requirements appropriate for hardware.
              </p>
            </div>
          </div>
        </div>
      </div>

    </div>
  </section>

  <!-- ===== Footer ===== -->
  <footer class="footer">
    <div class="container">
      <span class="footer-text">&copy; 2026 Neuroscience Engineering Syndicate</span>
      <div class="footer-links">
        <a href="index.html">Home</a>
        <a href="solutions.html">Solutions</a>
        <a href="https://github.com/SainsburyWellcomeCentre/NeuroscienceEngineeringSyndicate" target="_blank" rel="noopener">GitHub</a>
      </div>
    </div>
  </footer>

  <script src="js/app.js"></script>
</body>
</html>