Compare commits
No commits in common. "master" and "legacy-build" have entirely different histories.
master
...
legacy-bui
33
README.md
33
README.md
|
|
@ -2,7 +2,7 @@
|
||||||
|
|
||||||
Repository with instructions and remarks on assembling and testing Sinara hardware
|
Repository with instructions and remarks on assembling and testing Sinara hardware
|
||||||
|
|
||||||
## Build docs
|
### Build docs
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
nix build
|
nix build
|
||||||
|
|
@ -17,19 +17,7 @@ nix develop
|
||||||
mdbook build
|
mdbook build
|
||||||
```
|
```
|
||||||
|
|
||||||
The output files will be in `book` directory.
|
The output files are in `book` directory.
|
||||||
|
|
||||||
### Alternative way
|
|
||||||
|
|
||||||
Since the docs builder depends only on mdBook, you may get it from anywhere you like - `nix-shell -p mdbook`,
|
|
||||||
`snap install mdbook`, `cargo install mdbook` or any other from your OS.
|
|
||||||
After that you will be able to do:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
mdbook build
|
|
||||||
```
|
|
||||||
|
|
||||||
The output files will be in `book` directory.
|
|
||||||
|
|
||||||
## Contributing
|
## Contributing
|
||||||
|
|
||||||
|
|
@ -45,16 +33,7 @@ Tips for adding hardware instructions:
|
||||||
for images with transparent background)
|
for images with transparent background)
|
||||||
3. Add link to the new chapter to the `src/SUMMARY.md`
|
3. Add link to the new chapter to the `src/SUMMARY.md`
|
||||||
4. Do not forget to tell about all hidden/non-obvious obstacles and pitfalls
|
4. Do not forget to tell about all hidden/non-obvious obstacles and pitfalls
|
||||||
5. Avoid using uncommon, complex, or hard-to-understand words, phrases, or grammar (e.g., ❌constituent -> ✔️component).
|
5. Add testing steps, even the "obvious" ones
|
||||||
Keep in mind that these guides may be used by people with different backgrounds and levels of English proficiency.
|
6. Add JSON sample if needed
|
||||||
6. Add testing steps, even the "obvious" ones
|
7. Add hardware setup (e.g. pins, switches) steps if needed
|
||||||
7. Add JSON sample if needed
|
8. View changed and added pages with `mdbook build` (see building instructions above)
|
||||||
8. Add hardware setup (e.g. pins, switches) steps if needed
|
|
||||||
9. View changed and added pages with `mdbook build` (see building instructions above)
|
|
||||||
10. Check your contributions with linter:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
nix-shell -p nodejs
|
|
||||||
npm install
|
|
||||||
npx markdownlint-cli2 "src/**/*.md" --fix
|
|
||||||
```
|
|
||||||
|
|
|
||||||
|
|
@ -2,16 +2,16 @@
|
||||||
"nodes": {
|
"nodes": {
|
||||||
"nixpkgs": {
|
"nixpkgs": {
|
||||||
"locked": {
|
"locked": {
|
||||||
"lastModified": 1728909085,
|
"lastModified": 1697851979,
|
||||||
"narHash": "sha256-WLxED18lodtQiayIPDE5zwAfkPJSjHJ35UhZ8h3cJUg=",
|
"narHash": "sha256-lJ8k4qkkwdvi+t/Xc6Fn74kUuobpu9ynPGxNZR6OwoA=",
|
||||||
"owner": "NixOS",
|
"owner": "NixOS",
|
||||||
"repo": "nixpkgs",
|
"repo": "nixpkgs",
|
||||||
"rev": "c0b1da36f7c34a7146501f684e9ebdf15d2bebf8",
|
"rev": "5550a85a087c04ddcace7f892b0bdc9d8bb080c8",
|
||||||
"type": "github"
|
"type": "github"
|
||||||
},
|
},
|
||||||
"original": {
|
"original": {
|
||||||
"owner": "NixOS",
|
"owner": "NixOS",
|
||||||
"ref": "nixos-24.05",
|
"ref": "nixos-23.05",
|
||||||
"repo": "nixpkgs",
|
"repo": "nixpkgs",
|
||||||
"type": "github"
|
"type": "github"
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -1,7 +1,7 @@
|
||||||
{
|
{
|
||||||
description = "Sinara assembly and test instructions";
|
description = "Sinara assembly and test instructions";
|
||||||
|
|
||||||
inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-24.05;
|
inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-23.05;
|
||||||
|
|
||||||
outputs = { self, nixpkgs }:
|
outputs = { self, nixpkgs }:
|
||||||
|
|
||||||
|
|
@ -20,7 +20,7 @@
|
||||||
};
|
};
|
||||||
devShell.x86_64-linux = pkgs.mkShell {
|
devShell.x86_64-linux = pkgs.mkShell {
|
||||||
name = "sinara-assembly-dev-shell";
|
name = "sinara-assembly-dev-shell";
|
||||||
buildInputs = with pkgs; [ pkgs.mdbook pkgs.nodejs ];
|
buildInputs = with pkgs; [pkgs.mdbook];
|
||||||
};
|
};
|
||||||
|
|
||||||
};
|
};
|
||||||
|
|
|
||||||
|
|
@ -1,460 +0,0 @@
|
||||||
{
|
|
||||||
"name": "sinara-assembly",
|
|
||||||
"lockfileVersion": 3,
|
|
||||||
"requires": true,
|
|
||||||
"packages": {
|
|
||||||
"": {
|
|
||||||
"devDependencies": {
|
|
||||||
"markdownlint-cli2": "^0.14.0"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/@nodelib/fs.scandir": {
|
|
||||||
"version": "2.1.5",
|
|
||||||
"resolved": "https://registry.npmjs.org/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz",
|
|
||||||
"integrity": "sha512-vq24Bq3ym5HEQm2NKCr3yXDwjc7vTsEThRDnkp2DK9p1uqLR+DHurm/NOTo0KG7HYHU7eppKZj3MyqYuMBf62g==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"@nodelib/fs.stat": "2.0.5",
|
|
||||||
"run-parallel": "^1.1.9"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">= 8"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/@nodelib/fs.stat": {
|
|
||||||
"version": "2.0.5",
|
|
||||||
"resolved": "https://registry.npmjs.org/@nodelib/fs.stat/-/fs.stat-2.0.5.tgz",
|
|
||||||
"integrity": "sha512-RkhPPp2zrqDAQA/2jNhnztcPAlv64XdhIp7a7454A5ovI7Bukxgt7MX7udwAu3zg1DcpPU0rz3VV1SeaqvY4+A==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">= 8"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/@nodelib/fs.walk": {
|
|
||||||
"version": "1.2.8",
|
|
||||||
"resolved": "https://registry.npmjs.org/@nodelib/fs.walk/-/fs.walk-1.2.8.tgz",
|
|
||||||
"integrity": "sha512-oGB+UxlgWcgQkgwo8GcEGwemoTFt3FIO9ababBmaGwXIoBKZ+GTy0pP185beGg7Llih/NSHSV2XAs1lnznocSg==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"@nodelib/fs.scandir": "2.1.5",
|
|
||||||
"fastq": "^1.6.0"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">= 8"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/@sindresorhus/merge-streams": {
|
|
||||||
"version": "2.3.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/@sindresorhus/merge-streams/-/merge-streams-2.3.0.tgz",
|
|
||||||
"integrity": "sha512-LtoMMhxAlorcGhmFYI+LhPgbPZCkgP6ra1YL604EeF6U98pLlQ3iWIGMdWSC+vWmPBWBNgmDBAhnAobLROJmwg==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=18"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/sindresorhus"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/argparse": {
|
|
||||||
"version": "2.0.1",
|
|
||||||
"resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
|
|
||||||
"integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
|
|
||||||
"dev": true
|
|
||||||
},
|
|
||||||
"node_modules/braces": {
|
|
||||||
"version": "3.0.3",
|
|
||||||
"resolved": "https://registry.npmjs.org/braces/-/braces-3.0.3.tgz",
|
|
||||||
"integrity": "sha512-yQbXgO/OSZVD2IsiLlro+7Hf6Q18EJrKSEsdoMzKePKXct3gvD8oLcOQdIzGupr5Fj+EDe8gO/lxc1BzfMpxvA==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"fill-range": "^7.1.1"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">=8"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/entities": {
|
|
||||||
"version": "4.5.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
|
|
||||||
"integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=0.12"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/fb55/entities?sponsor=1"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/fast-glob": {
|
|
||||||
"version": "3.3.2",
|
|
||||||
"resolved": "https://registry.npmjs.org/fast-glob/-/fast-glob-3.3.2.tgz",
|
|
||||||
"integrity": "sha512-oX2ruAFQwf/Orj8m737Y5adxDQO0LAB7/S5MnxCdTNDd4p6BsyIVsv9JQsATbTSq8KHRpLwIHbVlUNatxd+1Ow==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"@nodelib/fs.stat": "^2.0.2",
|
|
||||||
"@nodelib/fs.walk": "^1.2.3",
|
|
||||||
"glob-parent": "^5.1.2",
|
|
||||||
"merge2": "^1.3.0",
|
|
||||||
"micromatch": "^4.0.4"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">=8.6.0"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/fastq": {
|
|
||||||
"version": "1.17.1",
|
|
||||||
"resolved": "https://registry.npmjs.org/fastq/-/fastq-1.17.1.tgz",
|
|
||||||
"integrity": "sha512-sRVD3lWVIXWg6By68ZN7vho9a1pQcN/WBFaAAsDDFzlJjvoGx0P8z7V1t72grFJfJhu3YPZBuu25f7Kaw2jN1w==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"reusify": "^1.0.4"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/fill-range": {
|
|
||||||
"version": "7.1.1",
|
|
||||||
"resolved": "https://registry.npmjs.org/fill-range/-/fill-range-7.1.1.tgz",
|
|
||||||
"integrity": "sha512-YsGpe3WHLK8ZYi4tWDg2Jy3ebRz2rXowDxnld4bkQB00cc/1Zw9AWnC0i9ztDJitivtQvaI9KaLyKrc+hBW0yg==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"to-regex-range": "^5.0.1"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">=8"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/glob-parent": {
|
|
||||||
"version": "5.1.2",
|
|
||||||
"resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-5.1.2.tgz",
|
|
||||||
"integrity": "sha512-AOIgSQCepiJYwP3ARnGx+5VnTu2HBYdzbGP45eLw1vr3zB3vZLeyed1sC9hnbcOc9/SrMyM5RPQrkGz4aS9Zow==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"is-glob": "^4.0.1"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">= 6"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/globby": {
|
|
||||||
"version": "14.0.2",
|
|
||||||
"resolved": "https://registry.npmjs.org/globby/-/globby-14.0.2.tgz",
|
|
||||||
"integrity": "sha512-s3Fq41ZVh7vbbe2PN3nrW7yC7U7MFVc5c98/iTl9c2GawNMKx/J648KQRW6WKkuU8GIbbh2IXfIRQjOZnXcTnw==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"@sindresorhus/merge-streams": "^2.1.0",
|
|
||||||
"fast-glob": "^3.3.2",
|
|
||||||
"ignore": "^5.2.4",
|
|
||||||
"path-type": "^5.0.0",
|
|
||||||
"slash": "^5.1.0",
|
|
||||||
"unicorn-magic": "^0.1.0"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">=18"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/sindresorhus"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/ignore": {
|
|
||||||
"version": "5.3.2",
|
|
||||||
"resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
|
|
||||||
"integrity": "sha512-hsBTNUqQTDwkWtcdYI2i06Y/nUBEsNEDJKjWdigLvegy8kDuJAS8uRlpkkcQpyEXL0Z/pjDy5HBmMjRCJ2gq+g==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">= 4"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/is-extglob": {
|
|
||||||
"version": "2.1.1",
|
|
||||||
"resolved": "https://registry.npmjs.org/is-extglob/-/is-extglob-2.1.1.tgz",
|
|
||||||
"integrity": "sha512-SbKbANkN603Vi4jEZv49LeVJMn4yGwsbzZworEoyEiutsN3nJYdbO36zfhGJ6QEDpOZIFkDtnq5JRxmvl3jsoQ==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=0.10.0"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/is-glob": {
|
|
||||||
"version": "4.0.3",
|
|
||||||
"resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
|
|
||||||
"integrity": "sha512-xelSayHH36ZgE7ZWhli7pW34hNbNl8Ojv5KVmkJD4hBdD3th8Tfk9vYasLM+mXWOZhFkgZfxhLSnrwRr4elSSg==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"is-extglob": "^2.1.1"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">=0.10.0"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/is-number": {
|
|
||||||
"version": "7.0.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/is-number/-/is-number-7.0.0.tgz",
|
|
||||||
"integrity": "sha512-41Cifkg6e8TylSpdtTpeLVMqvSBEVzTttHvERD741+pnZ8ANv0004MRL43QKPDlK9cGvNp6NZWZUBlbGXYxxng==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=0.12.0"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/js-yaml": {
|
|
||||||
"version": "4.1.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.0.tgz",
|
|
||||||
"integrity": "sha512-wpxZs9NoxZaJESJGIZTyDEaYpl0FKSA+FB9aJiyemKhMwkxQg63h4T1KJgUGHpTqPDNRcmmYLugrRjJlBtWvRA==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"argparse": "^2.0.1"
|
|
||||||
},
|
|
||||||
"bin": {
|
|
||||||
"js-yaml": "bin/js-yaml.js"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/jsonc-parser": {
|
|
||||||
"version": "3.3.1",
|
|
||||||
"resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.3.1.tgz",
|
|
||||||
"integrity": "sha512-HUgH65KyejrUFPvHFPbqOY0rsFip3Bo5wb4ngvdi1EpCYWUQDC5V+Y7mZws+DLkr4M//zQJoanu1SP+87Dv1oQ==",
|
|
||||||
"dev": true
|
|
||||||
},
|
|
||||||
"node_modules/linkify-it": {
|
|
||||||
"version": "5.0.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz",
|
|
||||||
"integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"uc.micro": "^2.0.0"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/markdown-it": {
|
|
||||||
"version": "14.1.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz",
|
|
||||||
"integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"argparse": "^2.0.1",
|
|
||||||
"entities": "^4.4.0",
|
|
||||||
"linkify-it": "^5.0.0",
|
|
||||||
"mdurl": "^2.0.0",
|
|
||||||
"punycode.js": "^2.3.1",
|
|
||||||
"uc.micro": "^2.1.0"
|
|
||||||
},
|
|
||||||
"bin": {
|
|
||||||
"markdown-it": "bin/markdown-it.mjs"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/markdownlint": {
|
|
||||||
"version": "0.35.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/markdownlint/-/markdownlint-0.35.0.tgz",
|
|
||||||
"integrity": "sha512-wgp8yesWjFBL7bycA3hxwHRdsZGJhjhyP1dSxKVKrza0EPFYtn+mHtkVy6dvP1kGSjovyG5B8yNP6Frj0UFUJg==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"markdown-it": "14.1.0",
|
|
||||||
"markdownlint-micromark": "0.1.10"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">=18"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/DavidAnson"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/markdownlint-cli2": {
|
|
||||||
"version": "0.14.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/markdownlint-cli2/-/markdownlint-cli2-0.14.0.tgz",
|
|
||||||
"integrity": "sha512-2cqdWy56frU2FTpbuGb83mEWWYuUIYv6xS8RVEoUAuKNw/hXPar2UYGpuzUhlFMngE8Omaz4RBH52MzfRbGshw==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"globby": "14.0.2",
|
|
||||||
"js-yaml": "4.1.0",
|
|
||||||
"jsonc-parser": "3.3.1",
|
|
||||||
"markdownlint": "0.35.0",
|
|
||||||
"markdownlint-cli2-formatter-default": "0.0.5",
|
|
||||||
"micromatch": "4.0.8"
|
|
||||||
},
|
|
||||||
"bin": {
|
|
||||||
"markdownlint-cli2": "markdownlint-cli2.js"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">=18"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/DavidAnson"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/markdownlint-cli2-formatter-default": {
|
|
||||||
"version": "0.0.5",
|
|
||||||
"resolved": "https://registry.npmjs.org/markdownlint-cli2-formatter-default/-/markdownlint-cli2-formatter-default-0.0.5.tgz",
|
|
||||||
"integrity": "sha512-4XKTwQ5m1+Txo2kuQ3Jgpo/KmnG+X90dWt4acufg6HVGadTUG5hzHF/wssp9b5MBYOMCnZ9RMPaU//uHsszF8Q==",
|
|
||||||
"dev": true,
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/DavidAnson"
|
|
||||||
},
|
|
||||||
"peerDependencies": {
|
|
||||||
"markdownlint-cli2": ">=0.0.4"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/markdownlint-micromark": {
|
|
||||||
"version": "0.1.10",
|
|
||||||
"resolved": "https://registry.npmjs.org/markdownlint-micromark/-/markdownlint-micromark-0.1.10.tgz",
|
|
||||||
"integrity": "sha512-no5ZfdqAdWGxftCLlySHSgddEjyW4kui4z7amQcGsSKfYC5v/ou+8mIQVyg9KQMeEZLNtz9OPDTj7nnTnoR4FQ==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=18"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/DavidAnson"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/mdurl": {
|
|
||||||
"version": "2.0.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz",
|
|
||||||
"integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==",
|
|
||||||
"dev": true
|
|
||||||
},
|
|
||||||
"node_modules/merge2": {
|
|
||||||
"version": "1.4.1",
|
|
||||||
"resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz",
|
|
||||||
"integrity": "sha512-8q7VEgMJW4J8tcfVPy8g09NcQwZdbwFEqhe/WZkoIzjn/3TGDwtOCYtXGxA3O8tPzpczCCDgv+P2P5y00ZJOOg==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">= 8"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/micromatch": {
|
|
||||||
"version": "4.0.8",
|
|
||||||
"resolved": "https://registry.npmjs.org/micromatch/-/micromatch-4.0.8.tgz",
|
|
||||||
"integrity": "sha512-PXwfBhYu0hBCPw8Dn0E+WDYb7af3dSLVWKi3HGv84IdF4TyFoC0ysxFd0Goxw7nSv4T/PzEJQxsYsEiFCKo2BA==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"braces": "^3.0.3",
|
|
||||||
"picomatch": "^2.3.1"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">=8.6"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/path-type": {
|
|
||||||
"version": "5.0.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/path-type/-/path-type-5.0.0.tgz",
|
|
||||||
"integrity": "sha512-5HviZNaZcfqP95rwpv+1HDgUamezbqdSYTyzjTvwtJSnIH+3vnbmWsItli8OFEndS984VT55M3jduxZbX351gg==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=12"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/sindresorhus"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/picomatch": {
|
|
||||||
"version": "2.3.1",
|
|
||||||
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-2.3.1.tgz",
|
|
||||||
"integrity": "sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=8.6"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/jonschlinkert"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/punycode.js": {
|
|
||||||
"version": "2.3.1",
|
|
||||||
"resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
|
|
||||||
"integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=6"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/queue-microtask": {
|
|
||||||
"version": "1.2.3",
|
|
||||||
"resolved": "https://registry.npmjs.org/queue-microtask/-/queue-microtask-1.2.3.tgz",
|
|
||||||
"integrity": "sha512-NuaNSa6flKT5JaSYQzJok04JzTL1CA6aGhv5rfLW3PgqA+M2ChpZQnAC8h8i4ZFkBS8X5RqkDBHA7r4hej3K9A==",
|
|
||||||
"dev": true,
|
|
||||||
"funding": [
|
|
||||||
{
|
|
||||||
"type": "github",
|
|
||||||
"url": "https://github.com/sponsors/feross"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "patreon",
|
|
||||||
"url": "https://www.patreon.com/feross"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "consulting",
|
|
||||||
"url": "https://feross.org/support"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
},
|
|
||||||
"node_modules/reusify": {
|
|
||||||
"version": "1.0.4",
|
|
||||||
"resolved": "https://registry.npmjs.org/reusify/-/reusify-1.0.4.tgz",
|
|
||||||
"integrity": "sha512-U9nH88a3fc/ekCF1l0/UP1IosiuIjyTh7hBvXVMHYgVcfGvt897Xguj2UOLDeI5BG2m7/uwyaLVT6fbtCwTyzw==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"iojs": ">=1.0.0",
|
|
||||||
"node": ">=0.10.0"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/run-parallel": {
|
|
||||||
"version": "1.2.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/run-parallel/-/run-parallel-1.2.0.tgz",
|
|
||||||
"integrity": "sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==",
|
|
||||||
"dev": true,
|
|
||||||
"funding": [
|
|
||||||
{
|
|
||||||
"type": "github",
|
|
||||||
"url": "https://github.com/sponsors/feross"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "patreon",
|
|
||||||
"url": "https://www.patreon.com/feross"
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "consulting",
|
|
||||||
"url": "https://feross.org/support"
|
|
||||||
}
|
|
||||||
],
|
|
||||||
"dependencies": {
|
|
||||||
"queue-microtask": "^1.2.2"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/slash": {
|
|
||||||
"version": "5.1.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/slash/-/slash-5.1.0.tgz",
|
|
||||||
"integrity": "sha512-ZA6oR3T/pEyuqwMgAKT0/hAv8oAXckzbkmR0UkUosQ+Mc4RxGoJkRmwHgHufaenlyAgE1Mxgpdcrf75y6XcnDg==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=14.16"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/sindresorhus"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/to-regex-range": {
|
|
||||||
"version": "5.0.1",
|
|
||||||
"resolved": "https://registry.npmjs.org/to-regex-range/-/to-regex-range-5.0.1.tgz",
|
|
||||||
"integrity": "sha512-65P7iz6X5yEr1cwcgvQxbbIw7Uk3gOy5dIdtZ4rDveLqhrdJP+Li/Hx6tyK0NEb+2GCyneCMJiGqrADCSNk8sQ==",
|
|
||||||
"dev": true,
|
|
||||||
"dependencies": {
|
|
||||||
"is-number": "^7.0.0"
|
|
||||||
},
|
|
||||||
"engines": {
|
|
||||||
"node": ">=8.0"
|
|
||||||
}
|
|
||||||
},
|
|
||||||
"node_modules/uc.micro": {
|
|
||||||
"version": "2.1.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
|
|
||||||
"integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
|
|
||||||
"dev": true
|
|
||||||
},
|
|
||||||
"node_modules/unicorn-magic": {
|
|
||||||
"version": "0.1.0",
|
|
||||||
"resolved": "https://registry.npmjs.org/unicorn-magic/-/unicorn-magic-0.1.0.tgz",
|
|
||||||
"integrity": "sha512-lRfVq8fE8gz6QMBuDM6a+LO3IAzTi05H6gCVaUpir2E1Rwpo4ZUog45KpNXKC/Mn3Yb9UDuHumeFTo9iV/D9FQ==",
|
|
||||||
"dev": true,
|
|
||||||
"engines": {
|
|
||||||
"node": ">=18"
|
|
||||||
},
|
|
||||||
"funding": {
|
|
||||||
"url": "https://github.com/sponsors/sindresorhus"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
13
package.json
13
package.json
|
|
@ -1,13 +0,0 @@
|
||||||
{
|
|
||||||
"devDependencies": {
|
|
||||||
"markdownlint-cli2": "^0.14.0"
|
|
||||||
},
|
|
||||||
"markdownlint-cli2": {
|
|
||||||
"config": {
|
|
||||||
"line_length": {
|
|
||||||
"line_length": 120,
|
|
||||||
"code_blocks": false
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
|
|
@ -2,7 +2,6 @@
|
||||||
|
|
||||||
- [Build and test firmware](./build_test_firmware.md)
|
- [Build and test firmware](./build_test_firmware.md)
|
||||||
- [Hardware](./hw/hardware.md)
|
- [Hardware](./hw/hardware.md)
|
||||||
- [Sinara Kasli](./hw/kasli.md)
|
|
||||||
- [Sinara Kasli-SOC](./hw/kasli_soc.md)
|
- [Sinara Kasli-SOC](./hw/kasli_soc.md)
|
||||||
- [Sinara 4624 AWG Phaser (Upconverter/Baseband)](./hw/phaser.md)
|
- [Sinara 4624 AWG Phaser (Upconverter/Baseband)](./hw/phaser.md)
|
||||||
- [Sinara 4456 synthesizer Mirny / Sinara 4457 Almazny Mezzanine card](./hw/mirny_almazny.md)
|
- [Sinara 4456 synthesizer Mirny / Sinara 4457 Almazny Mezzanine card](./hw/mirny_almazny.md)
|
||||||
|
|
@ -10,8 +9,6 @@
|
||||||
- [Sinara 2118 BNC-TTL / 2128 SMA-TTL](./hw/bnc_sma_ttl.md)
|
- [Sinara 2118 BNC-TTL / 2128 SMA-TTL](./hw/bnc_sma_ttl.md)
|
||||||
- [Sinara 2138 MCX-TTL](./hw/mcx_ttl.md)
|
- [Sinara 2138 MCX-TTL](./hw/mcx_ttl.md)
|
||||||
- [Sinara 5432 DAC Zotino / Sinara 5632 DAC Fastino](./hw/zotino_fastino.md)
|
- [Sinara 5432 DAC Zotino / Sinara 5632 DAC Fastino](./hw/zotino_fastino.md)
|
||||||
- [Sinara 5633 HV Amplifier](./hw/hvamp.md)
|
|
||||||
- [Sinara 5716 DAC Shuttler](./hw/shuttler.md)
|
|
||||||
- [Sinara 5518 BNC-IDC / 5528 SMA-IDC adapter](./hw/bnc_sma_idc_adapter.md)
|
- [Sinara 5518 BNC-IDC / 5528 SMA-IDC adapter](./hw/bnc_sma_idc_adapter.md)
|
||||||
- [Sinara 4410/4412 DDS Urukul (AD9910/AD9912)](./hw/urukul.md)
|
- [Sinara 4410/4412 DDS Urukul (AD9910/AD9912)](./hw/urukul.md)
|
||||||
- [Sinara 5108 Sampler](./hw/sampler.md)
|
- [Sinara 5108 Sampler](./hw/sampler.md)
|
||||||
|
|
@ -20,17 +17,10 @@
|
||||||
- [Sinara 8452 DSP Stabilizer](./hw/stabilizer.md)
|
- [Sinara 8452 DSP Stabilizer](./hw/stabilizer.md)
|
||||||
- [Sinara 9805 RF Power Amplifier Booster](./hw/booster.md)
|
- [Sinara 9805 RF Power Amplifier Booster](./hw/booster.md)
|
||||||
- [Sinara 8451 Thermostat](./hw/thermostat.md)
|
- [Sinara 8451 Thermostat](./hw/thermostat.md)
|
||||||
- [Sinara 2245 LVDS DIO](./hw/lvds_dio.md)
|
|
||||||
- [Software/Support](./sw_sup/software_support.md)
|
- [Software/Support](./sw_sup/software_support.md)
|
||||||
- [Starting with ARTIQ](./sw_sup/artiq_start.md)
|
|
||||||
- [Building legacy firmware](./sw_sup/artiq_legacy.md)
|
- [Building legacy firmware](./sw_sup/artiq_legacy.md)
|
||||||
- [Networking](./sw_sup/networking.md)
|
- [Networking](./sw_sup/networking.md)
|
||||||
- [DRTIO](./sw_sup/drtio.md)
|
- [DRTIO](./sw_sup/drtio.md)
|
||||||
- [UART Logs](./sw_sup/uart_logs.md)
|
- [UART Logs](./sw_sup/uart_logs.md)
|
||||||
- [Flashing the Firmware](./sw_sup/flashing_firmware.md)
|
- [Flashing the Firmware](./sw_sup/flashing_firmware.md)
|
||||||
- [Moninj](./sw_sup/moninj.md)
|
- [Moninj](./sw_sup/moninj.md)
|
||||||
- [Clocking](sw_sup/clocking.md)
|
|
||||||
- [device_db.py](sw_sup/device_db.md)
|
|
||||||
- [Setup your PC for building ARTIQ firmware](sw_sup/setup_build_pc.md)
|
|
||||||
- [AFWS client](sw_sup/afws_client.md)
|
|
||||||
- [Integration with PyCharm](sw_sup/pycharm.md)
|
|
||||||
|
|
|
||||||
|
|
@ -8,54 +8,38 @@
|
||||||
* 🙅 Avoid the boards touching conductive materials - wires, metals. Use at
|
* 🙅 Avoid the boards touching conductive materials - wires, metals. Use at
|
||||||
least plastic ESD bags if you need the cards to be put at the desk or any other surface.
|
least plastic ESD bags if you need the cards to be put at the desk or any other surface.
|
||||||
* 💁 Be gentle to the EEM ports and any other connectors. Support them when plugging, hold when unplugging
|
* 💁 Be gentle to the EEM ports and any other connectors. Support them when plugging, hold when unplugging
|
||||||
* 🙆 If you need to take the cards out, take them out one-by-one from the end, unplug EEM and cables
|
* 🙆 If you need to take the cards out, take them out one-by-one from the end, unplug EEM and cables if you feel high tension
|
||||||
if you feel high tension
|
|
||||||
* 🙆 Use dedicated power supplies for each crate, preferably given or equivalent to given by us
|
* 🙆 Use dedicated power supplies for each crate, preferably given or equivalent to given by us
|
||||||
* 🙅 Avoid unnecessary inserts and pullouts, especially of MMCX cables
|
* 🙅 Avoid unnecessary inserts and pullouts, especially of MMCX cables
|
||||||
|
|
||||||
Failure to comply with this voids the warranty.
|
Failure to comply with this voids the warranty.
|
||||||
|
|
||||||
## Shipping hints and warnings
|
|
||||||
|
|
||||||
* 🙆 Leave the cards in the crate
|
|
||||||
* 🙆 Ensure screws are tight
|
|
||||||
* 🙆 Ensure cards are in card guides
|
|
||||||
* ⚠️ Remove any cables from front panels
|
|
||||||
* ⚠️ Remove SFP adapters and insert caps/stubs
|
|
||||||
* 💁 Also advised to put caps on SMA connectors
|
|
||||||
* ✅ Wrap each crate in the bubble wrap individually until you don't feel the edges of the crate
|
|
||||||
(usually 10 layers of standard buble wrap)
|
|
||||||
* 🈁 Fill in the space around the crate in the box with foamy stuff
|
|
||||||
|
|
||||||
## Kasli standalone
|
## Kasli standalone
|
||||||
|
|
||||||
### Checklist for Kasli
|
### Checklist
|
||||||
|
|
||||||
1. Build firmware (see commands below)
|
1. Build firmware (see commands below)
|
||||||
2. Flash firmware and settings
|
2. Flash firmware and settings
|
||||||
3. Test hardware with the PSU, which is going to be shipped
|
3. Test hardware with the PSU, which is going to be shipped
|
||||||
4. Create a flash-drive with `device_db.py` file for customers (FAT32)
|
4. Create a flash-drive with `device_db.py` file for customers (FAT32)
|
||||||
|
|
||||||
### CLI commands - build and flash for Kasli
|
### CLI commands - build and flash
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
mkdir <variant>
|
mkdir <variant>
|
||||||
cd <variant>/
|
cd <variant>/
|
||||||
nix develop github:m-labs/artiq\?ref=release-8#boards
|
nix develop github:m-labs/artiq\?ref=release-7
|
||||||
# master/standalone only
|
# master/standalone only
|
||||||
artiq_mkfs -s ip 192.168.1.75/24 kasli.config
|
artiq_mkfs -s ip 192.168.1.75 kasli.config
|
||||||
artiq_flash storage -f kasli.config
|
artiq_flash storage -f kasli.config
|
||||||
artiq_ddb_template -o device_db.py <variant>.json
|
artiq_ddb_template -o device_db.py <variant>.json
|
||||||
python -m artiq.gateware.targets.kasli <variant>.json
|
python -m artiq.gateware.targets.kasli_generic <variant>.json
|
||||||
artiq_flash --srcbuild -d artiq_kasli/<variant>/
|
artiq_flash --srcbuild -d artiq_kasli/<variant>/
|
||||||
artiq_rtiomap dev_map.bin
|
|
||||||
artiq_coremgmt config write -f device_map dev_map.bin
|
|
||||||
artiq_coremgmt reboot
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Kasli-SoC (zynq)
|
## Kasli-SoC (zynq)
|
||||||
|
|
||||||
### Checklist for Kasli-SoC
|
### Checklist
|
||||||
|
|
||||||
1. Build firmware (see commands below) for SD card variant
|
1. Build firmware (see commands below) for SD card variant
|
||||||
2. Copy `results/boot.bin` to the SD card
|
2. Copy `results/boot.bin` to the SD card
|
||||||
|
|
@ -65,27 +49,25 @@ artiq_coremgmt reboot
|
||||||
6. Test hardware with the PSU, which is going to be shipped
|
6. Test hardware with the PSU, which is going to be shipped
|
||||||
7. Create a flash-drive with `device_db.py` file for customers (FAT32)
|
7. Create a flash-drive with `device_db.py` file for customers (FAT32)
|
||||||
|
|
||||||
### CLI commands - build and flash for Kasli-SoC
|
### CLI commands - build and flash
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
mkdir <variant>
|
mkdir <variant>
|
||||||
cd <variant>/
|
cd <variant>/
|
||||||
nix develop git+https://git.m-labs.hk/m-labs/artiq-zynq\?ref=release-8
|
nix develop git+https://git.m-labs.hk/m-labs/artiq-zynq\?ref=release-7
|
||||||
artiq_ddb_template -o device_db.py <variant>.json
|
artiq_ddb_template -o device_db.py <variant>.json
|
||||||
nix build -L --impure --expr 'let fl = builtins.getFlake "git+https://git.m-labs.hk/m-labs/artiq-zynq?ref=release-8"; in (fl.makeArtiqZynqPackage {target="kasli_soc"; variant="[master, standalone, satellite]"; json=<full path to the json description>;}).kasli_soc-[master, standalone, satellite]-sd'
|
nix build -L --impure --expr 'let fl = builtins.getFlake "git+https://git.m-labs.hk/m-labs/artiq-zynq?ref=release-7"; in (fl.makeArtiqZynqPackage {target="kasli_soc"; variant="[master, standalone, satellite]"; json=<full path to the json description>;}).kasli_soc-[master, standalone, satellite]-sd'
|
||||||
# copy `results/boot.bin` to the SD card
|
# copy `results/boot.bin` to the SD card
|
||||||
# insert SD card to the Kasli-SoC and boot
|
# insert SD card to the Kasli-SoC and boot
|
||||||
artiq_coremgmt -D 192.168.1.56 config write -s ip 192.168.1.75 # or just place extra/CONFIG.TXT near the boot.bin on SD card
|
artiq_coremgmt -D 192.168.1.56 config write -s ip 192.168.1.75 # or just place extra/CONFIG.TXT near the boot.bin on SD card
|
||||||
# update firmware (alternative to copy to SD, if ARTIQ already running and connected)
|
# update firmware (alternative to copy to SD, if ARTIQ already running)
|
||||||
artiq_coremgmt config write -f boot result/boot.bin
|
artiq_coremgmt config write -f boot result/boot.bin
|
||||||
artiq_coremgmt reboot
|
# reboot via power supply
|
||||||
artiq_rtiomap dev_map.bin
|
|
||||||
artiq_coremgmt config write -f device_map dev_map.bin
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Testing (common)
|
## Testing (common)
|
||||||
|
|
||||||
```shell
|
```
|
||||||
artiq_sinara_tester
|
artiq_sinara_tester
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -94,18 +76,17 @@ you can use this book's pages, or if there is no instruction for testing your ha
|
||||||
|
|
||||||
### Known issues
|
### Known issues
|
||||||
|
|
||||||
* ~~[artiq-zynq#197](https://git.m-labs.hk/M-Labs/artiq-zynq/issues/197) - some cards
|
* ~~[artiq-zynq#197](https://git.m-labs.hk/M-Labs/artiq-zynq/issues/197) - some cards (Sampler, Mirny, Zotino and others)
|
||||||
(Sampler, Mirny, Zotino and others) do not work properly with some EEM ports.
|
do not work properly with some EEM ports. You might need to connect the card to the other ports until it gets working.~~
|
||||||
You might need to connect the card to the other ports until it gets working.~~
|
|
||||||
resolved (hopefully)
|
resolved (hopefully)
|
||||||
|
|
||||||
## Master-satellite setups
|
## Master-satellite setups
|
||||||
|
|
||||||
1. Change `base` in JSON to the respective `master` or `satellite`, remove `core_addr` in satellites
|
1. Change `base` in JSON to the respective `master` or `satellite`, add `"enable_sata_drtio": true` if needed to the master,
|
||||||
|
remove `core_addr` in satellites
|
||||||
2. Build and flash firmware for each crate with JSONs (see instructions above)
|
2. Build and flash firmware for each crate with JSONs (see instructions above)
|
||||||
3. Create combined `device_db.py`:
|
3. Create composed `device_db.py`: e.g. `artiq_ddb_template -o device_db.py -s 1 <satellite1>.json -s 2 <satellite2>.json <master>.json`
|
||||||
e.g. `artiq_ddb_template -o device_db.py -s 1 <satellite1>.json -s 2 <satellite2>.json <master>.json`
|
|
||||||
4. Connect satellite crates to the master respective to their numbers via the fiber (see example picture)
|
4. Connect satellite crates to the master respective to their numbers via the fiber (see example picture)
|
||||||
|
|
||||||
5. Ethernet is needed only for master
|
5. Ethernet is needed only for master
|
||||||
6. Test hardware as it would be one crate
|
6. Test hardware as it would be one crate
|
||||||
|
|
|
||||||
|
|
@ -1,2 +1 @@
|
||||||
ip=192.168.1.75
|
ip=192.168.1.75
|
||||||
rtio_clock=int_125
|
|
||||||
|
|
|
||||||
Binary file not shown.
Binary file not shown.
|
|
@ -7,8 +7,8 @@ connected to the Zotino/Fastino and not the Kasli. See [Zotino/Fastino page](./z
|
||||||
|
|
||||||
## Setup
|
## Setup
|
||||||
|
|
||||||
BNC/SMA-IDC adapters should be connected to the Zotino/Fastino with 26 pin cable only. Be aware of the order of
|
BNC/SMA-IDC adapters should be connected to the Zotino/Fastino with 26 pin cable only. Be aware of the order of the Zotino/Fastino's ports -
|
||||||
the Zotino/Fastino's ports - see numbers of the channels at the board when connecting.
|
see numbers of the channels at the board when connecting.
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
|
|
@ -21,6 +21,6 @@ zotino0/fastino0 0.1 -0.1 0.2 -0.2 0.3 -0.3 0.4 -0.4 0.5 -0.5 0.6 -0.6 0.7 -0.7
|
||||||
Press ENTER when done.
|
Press ENTER when done.
|
||||||
```
|
```
|
||||||
|
|
||||||
Similar to Zotino/Fastino, check output voltages on the BNC/SMA connectors with multimeter, alongside on
|
Similar to Zotino/Fastino, check output voltages on the BNC/SMA connectors with multimeter, alongside on the Zotino/Fastino itself.
|
||||||
the Zotino/Fastino itself. These voltages should be very close to the respective `artiq_sinara_test`'s
|
These voltages should be very close to the respective `artiq_sinara_test`'s suggested voltages.
|
||||||
suggested voltages. See [Zotino/Fastino page](./zotino_fastino.md) for details.
|
See [Zotino/Fastino page](./zotino_fastino.md) for details.
|
||||||
|
|
@ -13,8 +13,8 @@
|
||||||
"hw_rev": "vX.Y", // optional
|
"hw_rev": "vX.Y", // optional
|
||||||
"ports": [<port num>],
|
"ports": [<port num>],
|
||||||
"edge_counter": <bool>,
|
"edge_counter": <bool>,
|
||||||
"bank_direction_low": "input", // or "output"
|
"bank_direction_low": "input",
|
||||||
"bank_direction_high": "output" // or "input"
|
"bank_direction_high": "output"
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -23,7 +23,7 @@
|
||||||
Switch the direction switches (shown on the picture below) according to customer requests.
|
Switch the direction switches (shown on the picture below) according to customer requests.
|
||||||
Remember, that you can only switch directions in groups of four.
|
Remember, that you can only switch directions in groups of four.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Test
|
## Test
|
||||||
|
|
||||||
|
|
@ -53,7 +53,6 @@ Connect ttl4 to ttl0. Press ENTER when done.
|
||||||
```
|
```
|
||||||
|
|
||||||
1. Mount a wire with respective connector to the chosen TTL output (any should work, choose most convenient one)
|
1. Mount a wire with respective connector to the chosen TTL output (any should work, choose most convenient one)
|
||||||
2. Connect the end of the wire to the TTL input requested by the `artiq_sinara_test`
|
2. Connect the end of the wire to the TTL input requested by the `artiq_sinara_test` (you may use fast connector for SMA)
|
||||||
(you may use fast connector for SMA)
|
|
||||||
3. Press ENTER and check that `artiq_sinara_test` prints `PASSED`
|
3. Press ENTER and check that `artiq_sinara_test` prints `PASSED`
|
||||||
4. Repeat 2-3 for every connector
|
4. Repeat 2-3 for every connector
|
||||||
|
|
|
||||||
|
|
@ -8,41 +8,9 @@
|
||||||
|
|
||||||
### Flashing
|
### Flashing
|
||||||
|
|
||||||
#### Easier way
|
|
||||||
|
|
||||||
Download and unpack the [booster firmware](../extra/booster/booster0.5.0.tar.xz), and then:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
nix-shell -p dfu-util
|
|
||||||
dfu-util -a 0 -s 0x08000000:leave --download booster0.5.0.bin
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Build from source on Fedora 38
|
|
||||||
|
|
||||||
Creating proper Nix shell for updated Rust is quite troublesome, so the faster way is actually to use any
|
|
||||||
classic Linux distribution:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git clone https://github.com/quartiq/booster.git # download sources
|
|
||||||
sudo dnf install clang dfu-util
|
|
||||||
cd booster/
|
|
||||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # install Rust, we need rustup
|
|
||||||
rustup target add thumbv7em-none-eabihf
|
|
||||||
cargo install cargo-binutils
|
|
||||||
rustup component add llvm-tools-preview
|
|
||||||
cargo build --release
|
|
||||||
cargo objcopy --release -- -O binary booster.bin
|
|
||||||
# enter dfu mode by either serial terminal or
|
|
||||||
# press `DFU Bootloader` button while rebooting
|
|
||||||
dfu-util -a 0 -s 0x08000000:leave --download booster.bin
|
|
||||||
```
|
|
||||||
|
|
||||||
#### For version before September 2023 on NixOS
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
git clone git@github.com:quartiq/booster.git
|
git clone git@github.com:quartiq/booster.git
|
||||||
cd booster
|
cd booster
|
||||||
git checkout a1f83b63180511ecd68f88a04621624941d17a41 # or earlier
|
|
||||||
nix-shell -p rustup cargo rustc dfu-util
|
nix-shell -p rustup cargo rustc dfu-util
|
||||||
rustup target add thumbv7em-none-eabihf
|
rustup target add thumbv7em-none-eabihf
|
||||||
cargo install cargo-binutils
|
cargo install cargo-binutils
|
||||||
|
|
@ -58,18 +26,15 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
|
||||||
|
|
||||||
1. `nix-shell -p cutecom mosquitto appimage-run`
|
1. `nix-shell -p cutecom mosquitto appimage-run`
|
||||||
2. Create mosquitto config `mosquitto.conf` with your bound address:
|
2. Create mosquitto config `mosquitto.conf` with your bound address:
|
||||||
|
```
|
||||||
```text
|
|
||||||
bind_address 192.168.1.123
|
bind_address 192.168.1.123
|
||||||
allow_anonymous true
|
allow_anonymous true
|
||||||
```
|
```
|
||||||
|
|
||||||
3. `mosquitto -c mosquitto.conf -d`
|
3. `mosquitto -c mosquitto.conf -d`
|
||||||
4. Run `cutecom`
|
4. Run `cutecom`
|
||||||
5. Connect to the Booster via `/dev/ttyACMX` port, baud 9600, switch from LF to CR on newer version
|
5. Connect to the Booster via `/dev/ttyACMX` port, baud 9600
|
||||||
6. Send `help` command to check if it works
|
6. Send `help` command to check if it works
|
||||||
7. Enter commands (change details if necessary):
|
7. Enter commands (change details if necessary):
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
write broker-address 192.168.1.123
|
write broker-address 192.168.1.123
|
||||||
# only if you need static IP address
|
# only if you need static IP address
|
||||||
|
|
@ -79,16 +44,6 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
|
||||||
# apply changes and wait until it fully rebooted
|
# apply changes and wait until it fully rebooted
|
||||||
reset
|
reset
|
||||||
```
|
```
|
||||||
|
|
||||||
Newer version:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
write broker "192.168.1.123"
|
|
||||||
write ip "192.168.1.75"
|
|
||||||
# apply changes and wait until it fully rebooted
|
|
||||||
reset
|
|
||||||
```
|
|
||||||
|
|
||||||
8. Check the Booster connects to your broker.
|
8. Check the Booster connects to your broker.
|
||||||
9. Download AppImage from [MQTT Explorer](https://mqtt-explorer.com/)
|
9. Download AppImage from [MQTT Explorer](https://mqtt-explorer.com/)
|
||||||
10. Run it with `appimage-run /path/to/MQTT-Explorer-XXX.AppImage`
|
10. Run it with `appimage-run /path/to/MQTT-Explorer-XXX.AppImage`
|
||||||
|
|
@ -97,28 +52,17 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
|
||||||
|
|
||||||
## Calibration
|
## Calibration
|
||||||
|
|
||||||
1. Assemble Kasli with one Urukul, build and flash firmware for it with [booster.json](../extra/booster/booster.json)
|
1. Assemble Kasli with one Urukul, build and flash firmware for it with [booster.json](../extra/booster.json)
|
||||||
2. Run [dds_for_booster.py](../extra/booster/dds_for_booster.py) experiment once
|
2. Run [dds_for_booster.py](../extra/dds_for_booster.py) experiment once
|
||||||
3. Attach parallel 50 Ohm load to the oscilloscope, as shown on the picture:
|
3. Attach parallel 50 Ohm load to the oscilloscope, as shown on the picture: ,
|
||||||
,
|
|
||||||
4. Configure oscilloscope for 1M Ohm impedance
|
4. Configure oscilloscope for 1M Ohm impedance
|
||||||
5. Attach attenuator to the Urukul's RF2
|
5. Attach attenuator to the Urukul's RF2
|
||||||
6. `cd py/`
|
6. `cd py/`
|
||||||
7. You may also need to download or install python's `gmqtt` and `miniconf`:
|
7. You may also need to download or install python's `gmqtt` and `miniconf`
|
||||||
|
8. Enable channels: `python -m booster --broker 192.168.1.123 --prefix dt/sinara/booster/xx-xx-xx-xx-xx-xx --channel N tune=0.1`
|
||||||
```shell
|
9. Using [booster_template](../extra/booster_template.ods) fill in `y0`, `y1`, `m`, `c`, values using instructions below
|
||||||
python -m venv env
|
|
||||||
source env/bin/activate.fish
|
|
||||||
pip install git+https://github.com/quartiq/miniconf.git@84cc9046bf504cc2d0d33b84d2f3133f2faf2248#subdirectory=py/miniconf-mqtt
|
|
||||||
```
|
|
||||||
|
|
||||||
8. Enable channels:
|
|
||||||
`python -m booster --broker 192.168.1.123 --prefix dt/sinara/booster/xx-xx-xx-xx-xx-xx --channel N tune=0.1`
|
|
||||||
9. Using [booster_template](../extra/booster/booster_template.ods) fill in `y0`, `y1`, `m`, `c`,
|
|
||||||
values using instructions below
|
|
||||||
10. Update settings with the adjusted values
|
10. Update settings with the adjusted values
|
||||||
11. Save settings with
|
11. Save settings with `python -m booster --broker 192.168.1.123 --prefix dt/sinara/booster/xx-xx-xx-xx-xx-xx --channel N save`
|
||||||
`python -m booster --broker 192.168.1.123 --prefix dt/sinara/booster/xx-xx-xx-xx-xx-xx --channel N save`
|
|
||||||
12. Reboot and check settings are applied
|
12. Reboot and check settings are applied
|
||||||
|
|
||||||
### Input power
|
### Input power
|
||||||
|
|
@ -134,6 +78,7 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
|
||||||
_Note: default setting and Urukul's measured values are usually the same across channels, so you can
|
_Note: default setting and Urukul's measured values are usually the same across channels, so you can
|
||||||
extrapolate them for all channels._
|
extrapolate them for all channels._
|
||||||
|
|
||||||
|
|
||||||
### Output and reflected power
|
### Output and reflected power
|
||||||
|
|
||||||
1. Connect Urukul's output (see booster template for exact ports) to the Booster's input
|
1. Connect Urukul's output (see booster template for exact ports) to the Booster's input
|
||||||
|
|
@ -151,3 +96,4 @@ extrapolate them for all channels._
|
||||||
13. Do steps 1-10 for every channel
|
13. Do steps 1-10 for every channel
|
||||||
|
|
||||||
_Note: default setting values are usually the same across channels, so you can extrapolate them for all channels._
|
_Note: default setting values are usually the same across channels, so you can extrapolate them for all channels._
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -4,11 +4,20 @@
|
||||||
|
|
||||||
## JSON
|
## JSON
|
||||||
|
|
||||||
Not present in the JSON.
|
Put the `ext_ref_frequency` field into the JSON description if the Kasli is going to use an external frequency:
|
||||||
|
|
||||||
Peripherals typically should choose `"clk_sel": 2` for MMCX connection and `"clk_sel": 1` for external SMA connection.
|
```json
|
||||||
Refer to the [official docs](https://m-labs.hk/artiq/manual/core_drivers_reference.html) by searching for `clk_sel`.
|
{
|
||||||
You may also need to add `"refclk": <number>` field to the target card.
|
"hw_rev": "<hw rev>",
|
||||||
|
"base": "<base>",
|
||||||
|
...
|
||||||
|
"ext_ref_frequency": <freq in Hz>,
|
||||||
|
...
|
||||||
|
"peripherals": [...]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
On peripherals you should choose `"clk_sel": 2` on connected devices.
|
||||||
|
|
||||||
## Setup external clocker
|
## Setup external clocker
|
||||||
|
|
||||||
|
|
@ -18,13 +27,13 @@ Here is example setup for SynthNV RF signal generator:
|
||||||
1. Connect SynthNV to the workstation via USB, and
|
1. Connect SynthNV to the workstation via USB, and
|
||||||
2. Install and run `cutecom`: `nix-shell -p cutecom`
|
2. Install and run `cutecom`: `nix-shell -p cutecom`
|
||||||
3. Set settings as on the picture below:
|
3. Set settings as on the picture below:
|
||||||
|
|
||||||
4. Open the device, usually it is `/dev/ttyACM0`
|
4. Open the device, usually it is `/dev/ttyACM0`
|
||||||
5. Put `?` into `Input` field and press `Enter` for current settings and help commands
|
5. Put `?` into `Input` field and press `Enter` for current settings and help commands
|
||||||
6. For changing the frequency, enter `f<freq in MHz>`, e.g. `f125.0` for 125 MHz
|
6. For changing the frequency, enter `f<freq in MHz>`, e.g. `f125.0` for 125 MHz
|
||||||
7. Set RF power so that clocker would recognize the signal with `a<power>` command, e.g. `a63`
|
7. Set RF power so that clocker would recognize the signal with `a<power>` command, e.g. `a63`
|
||||||
8. Check for desired amplitude and frequency at the `RFOut` (see picture below for reference) pin via oscilloscope
|
8. Check for desired amplitude and frequency at the `RFOut` (see picture below for reference) pin via oscilloscope
|
||||||
|
|
||||||
9. If everything is ok, connect `RFOut` to the `CLK IN` on the Clocker (see instructions below for details)
|
9. If everything is ok, connect `RFOut` to the `CLK IN` on the Clocker (see instructions below for details)
|
||||||
|
|
||||||
### Setup the Clocker
|
### Setup the Clocker
|
||||||
|
|
@ -32,13 +41,12 @@ Here is example setup for SynthNV RF signal generator:
|
||||||
1. Switch `CLK SEL` pin to `EXT`/`INT` according to customer needs
|
1. Switch `CLK SEL` pin to `EXT`/`INT` according to customer needs
|
||||||
2. Connect MMCx cables according to the customer needs and boards specifications (see image below for reference):
|
2. Connect MMCx cables according to the customer needs and boards specifications (see image below for reference):
|
||||||
if the `INT` source is chosen, connect MMCx cable to `INT CLK`, otherwise connect external clocker to SMA `EXT CLK`
|
if the `INT` source is chosen, connect MMCx cable to `INT CLK`, otherwise connect external clocker to SMA `EXT CLK`
|
||||||
3. Connect the Clocker to the Kasli via 30-pin ports, or via external power supply
|
3. Connect the Clocker to the Kasli via 30-pin ports
|
||||||
|
|
||||||
4. Connect the Clocker's SMA output to the Kasli's `CLK`/`CLK IN` SMA pin
|
4. Connect the Clocker's SMA output to the Kasli's `CLK`/`CLK IN` SMA pin
|
||||||
5. After assembling the crates and flashing the firmware, start Kasli and set config if needed:
|
5. After assembling the crates and flashing the firmware, start Kasli and write config as follows:
|
||||||
`artiq_coremgmt config write -s rtio_clock ext0_bypass`.
|
`artiq_coremgmt config write -s rtio_clock ext0_bypass`. Please refer to the [official manual](https://m-labs.hk/artiq/manual/installing.html#miscellaneous-configuration-of-the-core-device)
|
||||||
Please refer to the [official manual](https://m-labs.hk/artiq/manual/core_device.html#clocking)
|
for the details and available options
|
||||||
for the details and available options. In most cases you may skip this step.
|
|
||||||
6. Reboot either via `artiq_coremgmt reboot` or via power supply if the board's firmware doesn't have such command
|
6. Reboot either via `artiq_coremgmt reboot` or via power supply if the board's firmware doesn't have such command
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
@ -46,12 +54,10 @@ Here is example setup for SynthNV RF signal generator:
|
||||||
Run `artiq_sinara_test` and check that it doesn't fail on the connected devices.
|
Run `artiq_sinara_test` and check that it doesn't fail on the connected devices.
|
||||||
|
|
||||||
Alternatively, if it would be shipped standalone:
|
Alternatively, if it would be shipped standalone:
|
||||||
|
|
||||||
1. Switch to external source
|
1. Switch to external source
|
||||||
2. Connect to the external `CLK IN` clock source (frequency generator) via SMA cable
|
2. Connect to the external `CLK IN` clock source (frequency generator) via SMA cable
|
||||||
3. Power up Clocker with power supply or EEM
|
3. Power up Clocker with power supply or EEM
|
||||||
4. Check via oscilloscope all (internal and external) clocker outputs, that they output clock signal
|
4. Check via oscilloscope all (internal and external) clocker outputs, that they output clock signal respective to the input frequency
|
||||||
respective to the input frequency
|
|
||||||
5. Shut down Clocker
|
5. Shut down Clocker
|
||||||
6. Switch to internal source
|
6. Switch to internal source
|
||||||
7. Connect clock source to the internal `CLK IN` via MMCx cable
|
7. Connect clock source to the internal `CLK IN` via MMCx cable
|
||||||
|
|
|
||||||
|
|
@ -17,4 +17,4 @@ Activate the camera's frame grabber output, type 'g', press ENTER, and trigger t
|
||||||
Just press ENTER to skip the test.
|
Just press ENTER to skip the test.
|
||||||
```
|
```
|
||||||
|
|
||||||
## TODO
|
**TODO**
|
||||||
|
|
@ -4,5 +4,4 @@ In this section you will find instructions on testing the hardware.
|
||||||
If you didn't find one for your hardware, feel free to compose and add your instruction.
|
If you didn't find one for your hardware, feel free to compose and add your instruction.
|
||||||
|
|
||||||
Useful links:
|
Useful links:
|
||||||
|
|
||||||
* [Sinara Wiki](https://github.com/sinara-hw/meta/wiki)
|
* [Sinara Wiki](https://github.com/sinara-hw/meta/wiki)
|
||||||
|
|
@ -1,29 +0,0 @@
|
||||||
# Sinara 5633 HV Amplifier
|
|
||||||
|
|
||||||
* [Wiki](https://github.com/sinara-hw/HVAMP_32/wiki)
|
|
||||||
|
|
||||||
## Setup
|
|
||||||
|
|
||||||
1. Connect the HV Amplifier to the Zotino/Fastino with IDC connectors (stand-alone mode) or with mezzanine connectors (meazzanine mode). Be aware of pin alignment when using it in the meazzanine mode
|
|
||||||
2. Connect the DC barrel or ATX cable to HV Amplifier but **don't supply power**
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
After running `artiq_sinara_test` on the connected Zotino/Fastino:
|
|
||||||
|
|
||||||
```text
|
|
||||||
*** Testing Zotino DACs and USER LEDs.
|
|
||||||
Voltages:
|
|
||||||
zotino0 0.1 -0.1 0.2 -0.2 0.3 -0.3 0.4 -0.4 0.5 -0.5 0.6 -0.6 0.7 -0.7 0.8 -0.8 0.9 -0.9 1.0 -1.0 1.1 -1.1 1.2 -1.2 1.3 -1.3 1.4 -1.4 1.5 -1.5 1.6 -1.6
|
|
||||||
Press ENTER when done.
|
|
||||||
|
|
||||||
*** Testing Fastino DACs and USER LEDs.
|
|
||||||
Voltages:
|
|
||||||
fastino0 0.1 -0.1 0.2 -0.2 0.3 -0.3 0.4 -0.4 0.5 -0.5 0.6 -0.6 0.7 -0.7 0.8 -0.8 0.9 -0.9 1.0 -1.0 1.1 -1.1 1.2 -1.2 1.3 -1.3 1.4 -1.4 1.5 -1.5 1.6 -1.6
|
|
||||||
Press ENTER when done.
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Turn on the external power supply connecting to the HV Amplifier **(⚠️Danger: High Voltage active, don't touch the bare PCB without PPE)**
|
|
||||||
2. Probe with multimeter/DC voltmeter each pair of pins from bottom to top (left pins are ground)
|
|
||||||
3. Check that respective pins have voltages multipled by the gains as described by `artiq_sinara_test` (e.g. for 5x gain variant 0.1V pin => 0.1V x 5 = 0.5V )
|
|
||||||
4. Check LEDs are on
|
|
||||||
|
|
@ -1,11 +0,0 @@
|
||||||
# Kasli
|
|
||||||
|
|
||||||
## Mounting fan onto heatsink
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
1. ⚠️ Verify the fan has the **correct polarity (powering on with wrong polarity will burn the MOSFET in series💥)**
|
|
||||||
2. Place the fan on a heatsink
|
|
||||||
3. Tap 3 threads on the heatsink using M2.5 pointy tapping screws (e.g. front panel screws)
|
|
||||||
4. Replace the tapping screws with M2.5x14mm screws
|
|
||||||
5. Verify the fan is secure
|
|
||||||
|
|
@ -5,14 +5,4 @@
|
||||||
Check the BOOT mode switches - they both should be at SD if the Kasli-SoC going to be shipped to customer.
|
Check the BOOT mode switches - they both should be at SD if the Kasli-SoC going to be shipped to customer.
|
||||||
POR jumper needs only for JTAG mode.
|
POR jumper needs only for JTAG mode.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Mounting fan onto heatsink
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
1. ⚠️ Verify the fan has the **correct polarity (powering on with wrong polarity will burn the MOSFET in series💥)**
|
|
||||||
2. Place the fan on a heatsink
|
|
||||||
3. Tap 3 threads on the heatsink using M2.5 pointy tapping screws (e.g. front panel screws)
|
|
||||||
4. Replace the tapping screws with M2.5x14mm screws
|
|
||||||
5. Verify the fan is secure
|
|
||||||
|
|
@ -1,81 +0,0 @@
|
||||||
# Sinara 2245 LVDS DIO card
|
|
||||||
|
|
||||||
* [Wiki](https://github.com/sinara-hw/DIO_LVDS_RJ45/wiki)
|
|
||||||
* [Datasheet](https://m-labs.hk/docs/sinara-datasheets/2245.pdf)
|
|
||||||
|
|
||||||
## JSON
|
|
||||||
|
|
||||||
Be aware of the reversed EEM order on the card:
|
|
||||||
|
|
||||||
```json
|
|
||||||
[
|
|
||||||
{
|
|
||||||
"type": "dio",
|
|
||||||
"board": "DIO_LVDS",
|
|
||||||
"ports": [1],
|
|
||||||
"bank_direction_low": "input",
|
|
||||||
"bank_direction_high": "input",
|
|
||||||
"edge_counter": false // or true
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"type": "dio",
|
|
||||||
"board": "DIO_LVDS",
|
|
||||||
"ports": [0],
|
|
||||||
"bank_direction_low": "output",
|
|
||||||
"bank_direction_high": "output"
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Setup
|
|
||||||
|
|
||||||
Switch DIPs in required position per each channel individually. Each RJ45 have 4 channels.
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
```bash
|
|
||||||
*** Testing TTL inputs.
|
|
||||||
TTL device to use as stimulus (default: ttl0): ttl0
|
|
||||||
|
|
||||||
Connect ttl0 to ttl4. Press ENTER when done.
|
|
||||||
|
|
||||||
PASSED # <--------
|
|
||||||
Connect ttl0 to ttl5. Press ENTER when done.
|
|
||||||
|
|
||||||
FAILED
|
|
||||||
Connect ttl0 to ttl6. Press ENTER when done.
|
|
||||||
|
|
||||||
FAILED
|
|
||||||
Connect ttl0 to ttl7. Press ENTER when done.
|
|
||||||
|
|
||||||
FAILED
|
|
||||||
...
|
|
||||||
|
|
||||||
*** Testing TTL inputs.
|
|
||||||
TTL device to use as stimulus (default: ttl0): ttl1
|
|
||||||
|
|
||||||
Connect ttl1 to ttl4. Press ENTER when done.
|
|
||||||
|
|
||||||
FAILED
|
|
||||||
Connect ttl1 to ttl5. Press ENTER when done.
|
|
||||||
|
|
||||||
PASSED # <--------
|
|
||||||
Connect ttl1 to ttl6. Press ENTER when done.
|
|
||||||
|
|
||||||
FAILED
|
|
||||||
Connect ttl1 to ttl7. Press ENTER when done.
|
|
||||||
|
|
||||||
FAILED
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
||||||
1. Connect a RJ45 output port to a input port
|
|
||||||
2. Run `artiq_sinara_tester`
|
|
||||||
3. One TTL will pass while other will fail
|
|
||||||
4. Run `artiq_sinara_tester` again and increment the stimulus (e.g. `ttl0->ttl1->ttl2->ttl3`)
|
|
||||||
until all channels on the input port passed at least once
|
|
||||||
5. Plug into to another input port and repeat 2-4 until all input ports are tested
|
|
||||||
|
|
||||||
It is incompatible with other TTL cards, so you will need to use same or other LVDS card for proper testing.
|
|
||||||
|
|
@ -3,7 +3,7 @@
|
||||||
* [Wiki](https://github.com/sinara-hw/DIO_MCX/wiki)
|
* [Wiki](https://github.com/sinara-hw/DIO_MCX/wiki)
|
||||||
* [Datasheet](https://m-labs.hk/docs/sinara-datasheets/2238.pdf)
|
* [Datasheet](https://m-labs.hk/docs/sinara-datasheets/2238.pdf)
|
||||||
|
|
||||||
## JSON
|
# JSON
|
||||||
|
|
||||||
```json
|
```json
|
||||||
[
|
[
|
||||||
|
|
@ -33,7 +33,7 @@ and 2 entries in the JSON.
|
||||||
Switch the direction switches (shown on the picture below) according to customer requests.
|
Switch the direction switches (shown on the picture below) according to customer requests.
|
||||||
Remember, that you can only switch directions in groups of four.
|
Remember, that you can only switch directions in groups of four.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
## Test
|
## Test
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -9,73 +9,10 @@
|
||||||
{
|
{
|
||||||
"type": "mirny",
|
"type": "mirny",
|
||||||
"almazny": true, // for mirny with almazny only
|
"almazny": true, // for mirny with almazny only
|
||||||
"almazny_hw_rev": "v1.2", // optional, must be provided for legacy (<=v1.1) Almazny
|
"ports": [<port num>]
|
||||||
"ports": [<port num>],
|
|
||||||
"clk_sel": "mmcx", // optional
|
|
||||||
"refclk": 125e6 // optional
|
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
## Getting the firmware
|
|
||||||
|
|
||||||
On Hydra you can find [Mirny 0.3.1 firmware](https://nixbld.m-labs.hk/job/artiq/gluelogic/mirny-cpld-release).
|
|
||||||
It contains a single `.jed` file that can be flashed following [flashing instructions](#flashing).
|
|
||||||
This firmware supports Almazny v1.2+.
|
|
||||||
|
|
||||||
If you are using a legacy Almazny (v1.0-1.1), due to different signals routed, you need to flash the older
|
|
||||||
[0.2.4 firmware with Almazny support](https://nixbld.m-labs.hk/job/artiq/gluelogic/mirny-cpld-legacy-almazny).
|
|
||||||
|
|
||||||
### Building firmware (optional)
|
|
||||||
|
|
||||||
However, if you need to make chances or build from source, follow these instructions.
|
|
||||||
|
|
||||||
Once you get your hands on the firmware source code, you will need to work around few shortcomings of Nix, mainly
|
|
||||||
not being able to run dynamically linked executables.
|
|
||||||
|
|
||||||
You will need:
|
|
||||||
|
|
||||||
* Xilinx ISE 14.7 installed on your system (this guide is assuming `/opt/Xilinx` path),
|
|
||||||
* an environment with Migen.
|
|
||||||
|
|
||||||
One way to do it is to create an FHS environment, like ARTIQ does for Vivado, within ARTIQ's `flake.nix`
|
|
||||||
(to leverage Migen already being there), by adding these lines:
|
|
||||||
|
|
||||||
```nix
|
|
||||||
iseEnv = pkgs.buildFHSEnv {
|
|
||||||
name = "ise-env";
|
|
||||||
targetPkgs = vivadoDeps;
|
|
||||||
};
|
|
||||||
|
|
||||||
ise = pkgs.buildFHSEnv {
|
|
||||||
name = "ise";
|
|
||||||
targetPkgs = vivadoDeps;
|
|
||||||
profile = "set -e; source /opt/Xilinx/14.7/ISE_DS/settings64.sh";
|
|
||||||
runScript = "ise";
|
|
||||||
};
|
|
||||||
```
|
|
||||||
|
|
||||||
Add them below `vivadoEnv`. Then add `iseEnv` and `ise` to the dev shell's build inputs. Call `nix develop` on that.
|
|
||||||
|
|
||||||
Then you can build Mirny:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
nix develop
|
|
||||||
ise-env
|
|
||||||
cd ../mirny # or wherever your source is at
|
|
||||||
source /opt/Xilinx/14.7/ISE_DS/settings64.sh
|
|
||||||
python mirny_impl.py
|
|
||||||
```
|
|
||||||
|
|
||||||
### Flashing
|
|
||||||
|
|
||||||
For flashing, you will need Xilinx ISE 14.7 installed on your system (here assuming `/opt/Xilinx` path), and `xc3sprog`
|
|
||||||
with the appropriate HS2 JTAG adapter.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
nix-shell -p xc3sprog
|
|
||||||
xc3sprog -c jtaghs2 -m /opt/Xilinx/14.7/ISE_DS/ISE/xbr/data -v build/mirny.jed
|
|
||||||
```
|
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
### Without Almazny
|
### Without Almazny
|
||||||
|
|
@ -100,17 +37,17 @@ mirny0_ch3 info: {'f_outA': 1300000000.0, 'f_outB': 10400000000, 'output_divider
|
||||||
After running `artiq_sinara_test`:
|
After running `artiq_sinara_test`:
|
||||||
|
|
||||||
1. Install gqrx `nix-shell -p gqrx`
|
1. Install gqrx `nix-shell -p gqrx`
|
||||||
2. Connect HackRF One via USB cable only
|
2. Connect bladeRF via USB cable only
|
||||||
3. Run gqrx and choose `HackRF HackRF One...`
|
3. Run gqrx and choose `BladeRF #<number>...`
|
||||||
4. Default settings
|
4. Default settings
|
||||||
5. When gqrx loaded, start DSP processing with frequency at mirnyN_chM freq
|
5. When gqrx loaded, start DSP processing with frequency at mirnyN_chM freq
|
||||||
6. Connect the probe through attenuator to the Mirny's port
|
6. Connect the probe through attenuator to the Mirny's port
|
||||||
7. You should see significant signal emission on choosen freq compared to nearby freqs (see image below)
|
7. You should see significant signal emission on choosen freq compared to nearby freqs (see image below)
|
||||||
8. Repeat 5-7 for every channel
|
8. Repeat 5-7 for every channel
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### With Almazny (ARTIQ 7)
|
### With Almazny
|
||||||
|
|
||||||
At first, `artiq_sinara_test` will prompt you for testing Mirnies as the would be without Almazny.
|
At first, `artiq_sinara_test` will prompt you for testing Mirnies as the would be without Almazny.
|
||||||
After that, it will prompt you with testing the Almazny:
|
After that, it will prompt you with testing the Almazny:
|
||||||
|
|
@ -155,11 +92,7 @@ RF OFF. Press ENTER when done.
|
||||||
Similar to _Without Almazny_, check mirnies' channels emissions on defined frequencies.
|
Similar to _Without Almazny_, check mirnies' channels emissions on defined frequencies.
|
||||||
You should also see differences in various modes, but that may require disabling the gain.
|
You should also see differences in various modes, but that may require disabling the gain.
|
||||||
|
|
||||||
|
|
||||||
### Tips
|
### Tips
|
||||||
|
|
||||||
~~Mirnies often fail `ValueError: MUXOUT not high`, in that case restart the tests or reboot the board(s).~~ - fixed
|
Mirnies often fail `ValueError: MUXOUT not high`, in that case restart the tests or reboot the board(s).
|
||||||
in [9569cfb](https://github.com/m-labs/artiq/commit/9569cfb26329c0acdc1705d3256d2506b7bccce5)
|
|
||||||
|
|
||||||
For Almazny v1.0 and 1.1 support, CPLD firmware 0.2.4 (linked above) must be flashed onto Mirny.
|
|
||||||
|
|
||||||
For Almazny v1.2+ support, CPLD firmware 0.3.1+ (with fixes) must be flashed onto Mirny.
|
|
||||||
|
|
@ -25,20 +25,25 @@ phaser0 10+0 10+1 10+2 10+3 10+4 MHz
|
||||||
### Upconverter
|
### Upconverter
|
||||||
|
|
||||||
1. Install gqrx `nix-shell -p gqrx`
|
1. Install gqrx `nix-shell -p gqrx`
|
||||||
2. Connect HackRF One via USB cable only
|
2. Connect bladeRF via USB cable only
|
||||||
3. Run gqrx and choose `HackRF HackRF One...`
|
3. Run gqrx and choose `Nuand bladeRF SN <number>...`
|
||||||
4. Default settings
|
4. Input rate 20000000, other settings are default
|
||||||
5. Lower the gain in `Input options`
|
5. Lower the gain in `Input options`
|
||||||
6. When gqrx loaded, start DSP processing with frequency near 2.875 GHz +- DUC frequencies from `artiq_sinara_test`
|
6. When gqrx loaded, start DSP processing with frequency near 2.875 GHz +- DUC frequencies from `artiq_sinara_test`
|
||||||
in `Receiver Options`
|
in `Receiver Options`
|
||||||
7. Connect the probe through attenuator to the Phaser's RF ports
|
7. Connect the probe through attenuator to the Phaser's RF ports
|
||||||
8. You should see 5 tones on `artiq_sinara_test`'s frequencies, like on the pictures below for RF0 and RF1 respectively:
|
8. You should see 5 tones on `artiq_sinara_test`'s frequencies, like on the pictures below for RF0 and RF1 respectively:
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
### Baseband
|
### Baseband
|
||||||
|
|
||||||
1. Connect the probe through attenuator to the Phaser's ports RF0 or RF1 (not the ADC)
|
1. Install gqrx `nix-shell -p gqrx`
|
||||||
2. Find FTT (Fourier Transform) function in the oscilloscope
|
2. Connect bladeRF via USB cable only
|
||||||
3. Start processing with frequency near DUC frequencies from `artiq_sinara_test`
|
3. Run gqrx and choose `Nuand bladeRF SN <number>...`
|
||||||
4. You should see 5 tones on `artiq_sinara_test`'s frequencies
|
4. Input rate 15000000, other settings are default
|
||||||
|
5. When gqrx loaded, start DSP processing with frequency near 2.875 GHz (???)
|
||||||
|
6. Connect the probe through attenuator to the Phaser's ports RF0 or RF1 (not the ADC)
|
||||||
|
7. You should see 5 tones on `artiq_sinara_test`'s frequencies (???):
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -33,4 +33,3 @@ PASSED
|
||||||
1. Apply 1.5V (connect the AA-battery) to the `samplerX`'s requested channel
|
1. Apply 1.5V (connect the AA-battery) to the `samplerX`'s requested channel
|
||||||
2. Press `Enter`, the `artiq_sinara_test` should output `PASSED`
|
2. Press `Enter`, the `artiq_sinara_test` should output `PASSED`
|
||||||
3. Repeat steps 1-2 for every available channel.
|
3. Repeat steps 1-2 for every available channel.
|
||||||
4. Disassemble AA-battery tool as it risks getting corrosion
|
|
||||||
|
|
|
||||||
|
|
@ -1,138 +0,0 @@
|
||||||
# Sinara 5716 DAC Shuttler
|
|
||||||
|
|
||||||
The Sinara 5716 DAC Shuttler consists of the [Shuttler](https://github.com/sinara-hw/Shuttler),
|
|
||||||
[Remote AFE-Board](https://github.com/sinara-hw/Shuttler), and
|
|
||||||
[EEM FMC Carrier](https://github.com/sinara-hw/EEM_FMC_Carrier) (EFC) Board.
|
|
||||||
|
|
||||||
The EFC Board has an FPGA running Kasli Satellite. DRTIO communication is established through the EEM Cable.
|
|
||||||
At first power up, EFC Board and connected Kasli/Kasli-soc calibrate the clock skews on their own EEM transceiver
|
|
||||||
and then store the value into the flash memory/SD Card.
|
|
||||||
|
|
||||||
## JSON
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"type": "shuttler",
|
|
||||||
"ports": [<port num>]
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
## Hardware Configurations and Connections
|
|
||||||
|
|
||||||
### EEM Cable Connection
|
|
||||||
|
|
||||||
Only the EEM0 port on the EFC board is used. The EEM Cable provides power. You can ignore the barrel jack at
|
|
||||||
the back of the board if it is placed.
|
|
||||||
|
|
||||||
### CLK Input
|
|
||||||
|
|
||||||
The EFC requires a **common** clock source with the connected device.
|
|
||||||
|
|
||||||
For the EFC Board v1.0, please refer to this [issue](https://github.com/sinara-hw/EEM_FMC_Carrier/issues/44).
|
|
||||||
|
|
||||||
For the EFC Board v1.1 (or later), there is a DIP switch to select the clock source.
|
|
||||||
|
|
||||||
|
|
||||||
| Clock Source | CLK_SEL0 | CLK_SEL1 |
|
|
||||||
|---|---|---|
|
|
||||||
| Front Panel SMA | 0 | 0 |
|
|
||||||
| Internal Oscillator(default) | 1 | 0 |
|
|
||||||
| MMCX | 0 | 1 |
|
|
||||||
| PE CLK | 1 | 1 |
|
|
||||||
|
|
||||||
### VADJ Power
|
|
||||||
|
|
||||||
The EFC Board has configurable Digital IO Voltage Level/PSU called VADJ. You should configure VADJ to 1.8V by
|
|
||||||
fitting W1/W2 jumper accordingly.
|
|
||||||
|
|
||||||
|
|
||||||
### Remote AFE Board Connections
|
|
||||||
|
|
||||||
The Remote AFE Board is not installed in the crate and should be shipped separately. When you test the EFC Board,
|
|
||||||
please connect the Mini SAS Cables in this orientation.
|
|
||||||
|
|
||||||
|
|
||||||
There is no PSU for the Remote AFE Board at this moment. For testing purposes, you should connect the Remote AFE
|
|
||||||
Board to a lab PSU supplying +15V, -15V, and +5V. Please make sure all voltages share a common GND and check the
|
|
||||||
pinouts carefully. Incorrect power connections can damage the Remote AFE Board.
|
|
||||||
|
|
||||||
## Building EFC Board Gateware and Firmware
|
|
||||||
|
|
||||||
The EFC Board gateware and firmware are on the [Artiq](https://github.com/m-labs/artiq) repo.
|
|
||||||
|
|
||||||
To build the gateware and firmware,
|
|
||||||
|
|
||||||
```shell
|
|
||||||
python -m artiq.gateware.targets.efc --hw-rev [v1.0, v1.1]
|
|
||||||
```
|
|
||||||
|
|
||||||
## Routing Table Configuration if Shuttler is Connected to Kasli Satellite
|
|
||||||
|
|
||||||
When Kasli Satellite is compiled with Shuttler, Shuttler is connected to the Satellite Repeater instance. Therefore,
|
|
||||||
you will need to specify the routing table on the Kasli/Kasli-soc master in order to access the Shuttler hardware.
|
|
||||||
Shuttler locates at DEST 4 connecting to Repeater ID #3. The ID number goes up accordingly if more than one
|
|
||||||
Shuttler is connected.
|
|
||||||
|
|
||||||
Here provides an example to configure the routing table.
|
|
||||||
You have 1 Kasli Master and 1 Kasli Satellite. Kasli Master (SFP1)(DEST1) port is connected to
|
|
||||||
Kasli Satellite(SFP0)(DEST0). Shuttler is connected to Kasli Satellite with DRTIO over EEM Cable(DEST4).
|
|
||||||
|
|
||||||
1. Initialize the Routing Table: `artiq_route rt.bin init`
|
|
||||||
2. Add the routing table entry for Kasli Master's Peripherals: `artiq_route rt.bin set 0 0`
|
|
||||||
3. Add the routing table entry for Kasli Satellite's Peripherals: `artiq_route rt.bin set 1 1 0`
|
|
||||||
4. Add the routing table entry for Shuttler: `artiq_route rt.bin set 4 1 4 0`
|
|
||||||
5. Flash the routing table on Kasli Master: `artiq_coremgmt config write -f routing_table rt.bin`
|
|
||||||
|
|
||||||
## Flashing
|
|
||||||
|
|
||||||
When you are building a crate with shuttler(s), you should erase the flash/sd card config on both the EFC and
|
|
||||||
Kasli/Kasli-SoC. Always flash the EFC Board first before flashing the Kasli/Kasli-soc.
|
|
||||||
|
|
||||||
If either of the following elements is changed, you will need to **ERASE** the stored calibrated values on both
|
|
||||||
the EFC and Kasli Master, or the communication between the boards cannot be established:
|
|
||||||
|
|
||||||
1. EEM Cable
|
|
||||||
2. Clock-Related Cable
|
|
||||||
3. EFC Board Gateware
|
|
||||||
4. Kasli/Kasli-Soc Master Gateware
|
|
||||||
5. EFC Board/Kasli/Kasli-Soc PCB
|
|
||||||
|
|
||||||
To erase the flash on the EFC board,
|
|
||||||
|
|
||||||
```shell
|
|
||||||
artiq_flash -t efc erase
|
|
||||||
```
|
|
||||||
|
|
||||||
To flash the gateware and firmware onto the EFC board,
|
|
||||||
|
|
||||||
```shell
|
|
||||||
artiq_flash --srcbuild -t [efc1v0, efc1v1] -d artiq_efc/shuttler
|
|
||||||
```
|
|
||||||
|
|
||||||
## Testing
|
|
||||||
|
|
||||||
1. Connect the Remote AFE Card to the Shuttler
|
|
||||||
2. Power up the Remote AFE Board and the Kasli/Kasli-Soc with the connected Shuttler.
|
|
||||||
3. Check all Remote AFE Board Power Indicator LEDs.
|
|
||||||
4. Run the `artiq_sinara_test`.
|
|
||||||
|
|
||||||
```text
|
|
||||||
*** Testing LEDs.
|
|
||||||
Check for blinking. Press ENTER when done.
|
|
||||||
...
|
|
||||||
Testing LED: shuttler0_led0
|
|
||||||
Testing LED: shuttler0_led1
|
|
||||||
|
|
||||||
*** Testing Shuttler.
|
|
||||||
Testing: shuttler0
|
|
||||||
Check Remote AFE Board Relay LED Indicators.
|
|
||||||
Press Enter to Continue.
|
|
||||||
|
|
||||||
Testing Shuttler DAC
|
|
||||||
Voltages: 0.1 -0.1 0.2 -0.2 0.3 -0.3 0.4 -0.4 0.5 -0.5 0.6 -0.6 0.7 -0.7 0.8 -0.8
|
|
||||||
Press Enter to Continue.
|
|
||||||
|
|
||||||
PASSED
|
|
||||||
|
|
||||||
...
|
|
||||||
```
|
|
||||||
|
|
@ -4,132 +4,19 @@
|
||||||
* [QUARTIQ Manual](https://quartiq.de/stabilizer/)
|
* [QUARTIQ Manual](https://quartiq.de/stabilizer/)
|
||||||
* [Firmware](https://github.com/quartiq/stabilizer)
|
* [Firmware](https://github.com/quartiq/stabilizer)
|
||||||
|
|
||||||
EEM is used for power only, and it can be alternatively powered by 12V barrel jack or PoE.
|
|
||||||
|
|
||||||
## JSON
|
## JSON
|
||||||
|
|
||||||
Not present in the JSON.
|
No JSON modifications required.
|
||||||
|
|
||||||
## Getting the firmware
|
|
||||||
|
|
||||||
You can get the firmware from [Hydra](https://nixbld.m-labs.hk/jobset/mcu/mcu-contrib).
|
|
||||||
|
|
||||||
* `stabilizer-dual-iir` supports Pounder v1.2 - probably you should flash this one,
|
|
||||||
* `stabilizer-dual-iir-pounder_v1_0` supports Pounder 1.0 and 1.1 (legacy),
|
|
||||||
* `stabilizer-lockin` is a different application which we do not usually flash.
|
|
||||||
|
|
||||||
These all include changes to the mainline code to include Pounder telemetry.
|
|
||||||
|
|
||||||
### Building (optional)
|
|
||||||
|
|
||||||
Please keep in mind that the firmware from the official Quartiq repository does not include support for Pounder in MQTT,
|
|
||||||
you may need to use a fork for that. But if the stabilizer is without a Pounder, it's also a valid option.
|
|
||||||
|
|
||||||
There is no Nix Flake support to make things easier, so you need to set up rust and cargo manually.
|
|
||||||
Start with cloning the stabilizer repository and opening a new shell with dfu-util (for flashing) and rustup
|
|
||||||
(for building).
|
|
||||||
|
|
||||||
```shell
|
|
||||||
nix-shell -p dfu-util rustup
|
|
||||||
```
|
|
||||||
|
|
||||||
Set up the toolchain, this should be done only once:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
rustup target add thumbv7em-none-eabihf
|
|
||||||
cargo install cargo-binutils
|
|
||||||
rustup component add llvm-tools-preview
|
|
||||||
rustup update
|
|
||||||
rustup default stable
|
|
||||||
```
|
|
||||||
|
|
||||||
Building:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
cargo build --release
|
|
||||||
cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin
|
|
||||||
```
|
|
||||||
|
|
||||||
## Flashing
|
|
||||||
|
|
||||||
Once you have the binary, you can now flash it.
|
|
||||||
|
|
||||||
1. Without firmware on the device or with older firmware (without USB serial console),
|
|
||||||
you need to use the jumper method:
|
|
||||||
1. Have the Stabilizer disconnected from power.
|
|
||||||
2. Use a jumper of some sort to short BOOT pins on the board.
|
|
||||||
3. Turn on the power.
|
|
||||||
4. You can remove the jumper after few seconds.
|
|
||||||
2. With newer firmware with USB serial console:
|
|
||||||
1. Connect the Stabilizer to power.
|
|
||||||
2. Connect USB cable to the Stabilizer.
|
|
||||||
3. Ensure you have `pyserial` module either with `nix-shell -p python312Packages.pyserial` for NixOS users
|
|
||||||
or using `pip install pyserial` if you are using venv.
|
|
||||||
4. Run `python -m serial /dev/ttyACM0` to connect the serial port using `pyserial`.
|
|
||||||
5. Input `platform dfu` in the console.
|
|
||||||
3. Once the device is now in DFU mode, flash the device with the following command (needs `nix-shell -p dfu-util`):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
dfu-util -a 0 -s 0x08000000:leave -R -D stabilizer-dual-iir.bin
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Look for "File downloaded successfully".
|
|
||||||
|
|
||||||
For normal usage, the stabilizer must be configured with USB console later (try `help` command first),
|
|
||||||
to set its IP address and MQTT broker address. However, for general testing (like the one below), you don't need to
|
|
||||||
configure it any further.
|
|
||||||
|
|
||||||
### Clearing settings
|
|
||||||
|
|
||||||
In case someone sets some setting wrongly, or updates the firmware and suddenly there's an incompatibility,
|
|
||||||
you may find (firmware, not yourself) in a state of panic, where it will not allow you to change the settings back.
|
|
||||||
|
|
||||||
1. Get into DFU mode (described above), probably with jumper method.
|
|
||||||
2. Use dfu-util to clear the flash completely:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
dfu-util -a 0 -s 0x08000000:mass-erase:force:leave
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Reflash the target firmware.
|
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
1. Ensure that the [firmware](#getting-the-firmware) has been flashed onto the Stabilizer
|
1. Ensure that the [firmware](https://github.com/quartiq/stabilizer) has been flashed onto the Stabilizer
|
||||||
2. Turn on the crate/Stabilizer via EEM cable or power supply
|
2. Turn on the crate/Stabilizer via EEM cable or power supply
|
||||||
3. Set up the signal generator for an amplitude of 1V, frequency of 10kHz, and a sine wave
|
3. Set up the signal generator for an amplitude of 1V, frequency of 10kHz, and a sine wave
|
||||||
4. Use the splitter to connect the generator's output to ADC0 and to the oscilloscope (refer to the picture below)
|
4. Use the splitter to connect the generator's output to ADC0 and to the oscilloscope (refer to the picture below)
|
||||||
|
|
||||||
5. Configure the oscilloscope so that the sine wave is clearly visible
|
5. Configure the oscilloscope so that the sine wave is clearly visible
|
||||||
6. Connect the second channel of the oscilloscope to the Stabilizer's DAC0
|
6. Connect the second channel of the oscilloscope to the Stabilizer's DAC0
|
||||||
7. Ensure that there is the same wave on the second channel, with a small delay, as on the first channel
|
7. Ensure that there is the same wave on the second channel, with a small delay, as on the first channel
|
||||||
8. Repeat steps 4-7 for ADC/DAC1 (refer to the picture below for connection reference)
|
8. Repeat steps 4-7 for ADC/DAC1 (refer to the picture below for connection reference)
|
||||||
|
|
||||||
|
|
||||||
## Setting up MQTT
|
|
||||||
|
|
||||||
For testing the Stabilizer, it's usually enough to do the settings above, as signal is filtered by the firmware.
|
|
||||||
However, if you need to test the network connectivity or Pounder telemetry, MQTT may come useful.
|
|
||||||
|
|
||||||
On PC side:
|
|
||||||
|
|
||||||
1. Get IP address of your machine, e.g. with ``ip a``. Make note of it, that's the broker address.
|
|
||||||
2. Get mosquitto, e.g. with ``nix-shell -p mosquitto``.
|
|
||||||
3. Run mosquitto with the config from Stabilizer repository: ``mosquitto -c mosquitto.conf``
|
|
||||||
4. If you don't have it yet, download [MQTT Explorer](https://github.com/thomasnordquist/MQTT-Explorer/releases).
|
|
||||||
5. Call ``nix-shell -p appimage-run``, then ``appimage-run MQTT-Explorer-0.4.0-beta6.AppImage``.
|
|
||||||
6. Connect to the MQTT broker under your own IP address.
|
|
||||||
|
|
||||||
Configure Stabilizer:
|
|
||||||
|
|
||||||
1. Connect the Stabilizer to power.
|
|
||||||
2. Connect USB cable to the Stabilizer.
|
|
||||||
3. Run ``cutecom`` or your favorite terminal emulator, connect to ``/dev/ttyACM0``.
|
|
||||||
4. Change the broker setting with: ``set /net/broker "<ip of your machine>"``.
|
|
||||||
5. Store the setting with ``store /net/broker``.
|
|
||||||
6. (Optional) Set the IP address of the stabilizer by following steps 4 and 5, but with ``/net/ip`` setting instead.
|
|
||||||
7. Reboot with ``platform reboot``.
|
|
||||||
|
|
||||||
Now, disconnect the USB and connect the Ethernet cable to the Stabilizer, as both won't fit at the same time.
|
|
||||||
Stabilizer should connect to moquitto automatically, and you should see the MQTT settings pop up in the MQTT Explorer.
|
|
||||||
If the IP address is not set, Stabilizer will try to use DHCP to get an address.
|
|
||||||
|
|
|
||||||
|
|
@ -17,13 +17,12 @@ With enabled SUServo mode, you only need to add `suservo` to JSON file, with its
|
||||||
## Setup
|
## Setup
|
||||||
|
|
||||||
To enable, on bottoms of each Urukul, switch first switches 1 and 2 to `ON`, as on the picture:
|
To enable, on bottoms of each Urukul, switch first switches 1 and 2 to `ON`, as on the picture:
|
||||||
|
|
||||||
|
|
||||||
### Easier access to the switches (for big racks)
|
### Easier access to the switches (for big racks)
|
||||||
|
|
||||||
When the crate is assembled, it may be difficult to pull out the cards to access the switches.
|
When the crate is assembled, it may be difficult to pull out the cards to access the switches.
|
||||||
Hence for big racks it may be easier to remove the upper perforated panel. For this:
|
Hence for big racks it may be easier to remove the upper perforated panel. For this:
|
||||||
|
|
||||||
1. Unscrew from both sides:
|
1. Unscrew from both sides:
|
||||||
|
|
||||||
2. Remove empty front panels
|
2. Remove empty front panels
|
||||||
|
|
@ -62,12 +61,10 @@ Verify frequency and power behavior.
|
||||||
```
|
```
|
||||||
|
|
||||||
1. Connect oscilloscope to the `urukul0` port and configure with time and voltage scale and trigger threshold
|
1. Connect oscilloscope to the `urukul0` port and configure with time and voltage scale and trigger threshold
|
||||||
so that you'll see sine wave, like on the picture:
|
so that you'll see sine wave, like on the picture: 
|
||||||
|
|
||||||
2. Verify amplitude and frequency
|
2. Verify amplitude and frequency
|
||||||
3. Apply 1.5V (connect the AA-battery) to the `sampler0` port, as on the
|
3. Apply 1.5V (connect the AA-battery) to the `sampler0` port, as on the
|
||||||
picture: 
|
picture: 
|
||||||
4. You should see significant amplitude decrease, as in the picture:
|
4. You should see significant amplitude decrease, as in the picture: 
|
||||||
|
|
||||||
5. Verify amplitude difference, and the frequency to be unchanged
|
5. Verify amplitude difference, and the frequency to be unchanged
|
||||||
6. Repeat steps 1-5 for every available channel.
|
6. Repeat steps 1-5 for every available channel.
|
||||||
|
|
|
||||||
|
|
@ -23,36 +23,9 @@ dfu-util -a 0 -s 0x08000000:leave -D thermostat.bin
|
||||||
Then check that fans are working properly.
|
Then check that fans are working properly.
|
||||||
You may also check fan controls via `fan` commands (see the firmware documentation).
|
You may also check fan controls via `fan` commands (see the firmware documentation).
|
||||||
|
|
||||||
## Test PID
|
|
||||||
|
|
||||||
1. For Zotino: connect 10-pins IDC 2.54mm FC cable from internal Thermostat connector to the Zotino TEC
|
|
||||||
2. General TEC: connect external connector to the TEC
|
|
||||||
3. Connect Ethernet and PSU
|
|
||||||
4. Run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git clone gitea@git.m-labs.hk:esavkin/thermostat.git
|
|
||||||
cd thermostat
|
|
||||||
git checkout zotino-tec
|
|
||||||
nix develop
|
|
||||||
python pytec/tec_qt.py
|
|
||||||
```
|
|
||||||
|
|
||||||
5. In `Output Config`, set limits:
|
|
||||||
* `Max Cooling Current` - 400 mA
|
|
||||||
* `Max Heating Current` - 400 mA
|
|
||||||
* `Max Voltage Difference` - 1 V
|
|
||||||
6. `PID Config` -> `PID Auto Tune` set desired target temperature,
|
|
||||||
which should be slightly above your room temperature (+10C)
|
|
||||||
7. Set `Thermistor Config` -> `B` and other values, according to the datasheet of the TEC module,
|
|
||||||
for example for Zotino `B` is `3455 K`
|
|
||||||
8. Run `PID Config` -> `PID Auto Tune` -> `Run` and check graphs that the measured temperature
|
|
||||||
goes to the target temperature, and eventually stabilizes at +- 0.01 of the target
|
|
||||||
|
|
||||||
## Common problems
|
## Common problems
|
||||||
|
|
||||||
### Thermostat doesn't connect or doesn't enter DFU mode
|
### Thermostat doesn't connect or doesn't enter DFU mode
|
||||||
|
|
||||||
Carefully take out Thermostat from its protective box, unscrewed all screws before.
|
Carefully take out Thermostat from its protective box, unscrewed all screws before. Apply jumper and power on the Thermostat.
|
||||||
Apply jumper and power on the Thermostat.
|
|
||||||
Now it should be in DFU mode.
|
Now it should be in DFU mode.
|
||||||
|
|
@ -20,36 +20,15 @@
|
||||||
|
|
||||||
## Setup
|
## Setup
|
||||||
|
|
||||||
Check if [SUServo](./suservo.md) is enabled/disabled respective to customer needs.
|
Check if [SUServo](./suservo.md) is enabled/disabled respective to customer needs. Connect to the clocker source.
|
||||||
Connect to the clock source - either Clocker, Kasli or external via SMA.
|
|
||||||
|
|
||||||
### Synchronization
|
### Synchronization
|
||||||
|
|
||||||
Phase synchronization enables phase control from Kasli/Kasli-SoC with an absolute phase reference,
|
Phase synchronization enables phase control from Kasli/Kasli-SoC with an absolute phase reference, i.e. you can use the phase control API in the coredevice driver.
|
||||||
i.e. you can use the phase control API in the coredevice driver. Without synchronization the phase between Urukuls
|
Without synchronization the phase between Urukuls will not drift, but it can change across reboots, and the phase control API cannot be used.
|
||||||
will not drift, but it can change across reboots, and the phase control API cannot be used. Synchronization requires
|
Synchronization requires Kasli and Urukul to be clocked from the same oscillator with <<1ns noise, otherwise the synchronization may fail, and that's
|
||||||
Kasli and Urukul to be clocked from the same oscillator with <<1ns noise, otherwise the synchronization may fail,
|
why this feature is disabled by default.
|
||||||
and that's why this feature is disabled by default. There is no intrinsic impact on Urukul output phase noise and
|
There is no intrinsic impact on Urukul output phase noise and the synchronization process is quick and reliable when done correctly.
|
||||||
the synchronization process is quick and reliable when done correctly.
|
|
||||||
|
|
||||||
### One-EEM mode
|
|
||||||
|
|
||||||
Users may choose to use only one EEM port, if they want more cards to be in their crate. However following features
|
|
||||||
will become unavailable:
|
|
||||||
|
|
||||||
* SU-Servo
|
|
||||||
* Low-latency RF switch control
|
|
||||||
* Synchronization
|
|
||||||
|
|
||||||
RF switches are still available but the commands need to go over the SPI bus so it's higher-latency
|
|
||||||
and lower-resolution.
|
|
||||||
|
|
||||||
### Urukul 4412
|
|
||||||
|
|
||||||
Urukul 4412 has higher frequency resolution (47 bit against 32 at Urukul 4410), however lacks such features:
|
|
||||||
|
|
||||||
* SU-Servo
|
|
||||||
* Synchronization
|
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
|
|
@ -84,6 +63,7 @@ Press ENTER when done.
|
||||||
3. Measure frequencies and amplitudes on each connector, check with `artiq_sinara_test`'s respective values
|
3. Measure frequencies and amplitudes on each connector, check with `artiq_sinara_test`'s respective values
|
||||||
4. When done, proceed with `artiq_sinara_test` and check LEDs are lighting up one after another
|
4. When done, proceed with `artiq_sinara_test` and check LEDs are lighting up one after another
|
||||||
|
|
||||||
|
|
||||||
## Common problems
|
## Common problems
|
||||||
|
|
||||||
### Urukul AD9912 product id mismatch or missing LEDs
|
### Urukul AD9912 product id mismatch or missing LEDs
|
||||||
|
|
@ -95,24 +75,19 @@ ValueError: Urukul AD9912 product id mismatch
|
||||||
Some Urukuls may fail with this error during testing, usually meaning that the Urukul has not been flashed with the
|
Some Urukuls may fail with this error during testing, usually meaning that the Urukul has not been flashed with the
|
||||||
firmware, especially if the ID is `65535` (you will need to edit the code to check this).
|
firmware, especially if the ID is `65535` (you will need to edit the code to check this).
|
||||||
|
|
||||||
Another common symptom of no firmware is that no LEDs are lit up, besides Power Good - whereas if the firmware has been
|
Another common symptom of no firmware is that no LEDs are lit up, besides Power Good - whereas if the firmware has been flashed, the RF channels will be lit red.
|
||||||
flashed, the RF channels will be lit red.
|
|
||||||
|
|
||||||
You can flash the firmware yourself with a JTAG adapter:
|
You can flash the firmware yourself with a JTAG adapter:
|
||||||
|
|
||||||
1. Download the latest binary release from [quartiq/urukul](https://github.com/quartiq/urukul) and extract the
|
1. Download the latest binary release from [quartiq/urukul](https://github.com/quartiq/urukul) and extract the `urukul.jed` file.
|
||||||
`urukul.jed` file.
|
2. Connect the Urukul with the JTAG adapter to the PC and connect its EEM0 to any available Kasli/Kasli-SoC (**do not hot-plug**), then power on the Kasli/Kasli-SoC.
|
||||||
2. Connect the Urukul with the JTAG adapter to the PC and connect its EEM0 to any available Kasli/Kasli-SoC
|
|
||||||
(**do not hot-plug**), then power on the Kasli/Kasli-SoC.
|
|
||||||
3. Run `nix-shell -p xc3sprog`.
|
3. Run `nix-shell -p xc3sprog`.
|
||||||
4. Run `xc3sprog -c jtaghs2 urukul.jed -m /opt/Xilinx/Vivado/<available version>/data/xicom/cable_data/digilent/lnx64/xbr/`.
|
4. Run `xc3sprog -c jtaghs2 urukul.jed -m /opt/Xilinx/Vivado/<available version>/data/xicom/cable_data/digilent/lnx64/xbr/`.
|
||||||
5. If the last command outputs Verify: Success, then your Urukul is ready. It can also output the message
|
5. If the last command outputs Verify: Success, then your Urukul is ready. It can also output the message
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
*** buffer overflow detected ***: terminated
|
*** buffer overflow detected ***: terminated
|
||||||
Aborted (core dumped)
|
Aborted (core dumped)
|
||||||
```
|
```
|
||||||
|
|
||||||
, which is okay if `Verify: Success` was also emitted.
|
, which is okay if `Verify: Success` was also emitted.
|
||||||
|
|
||||||
### no valid window/delay
|
### no valid window/delay
|
||||||
|
|
@ -130,8 +105,8 @@ It may be due to misconfiguration of SUServo. Check that both firmware and pins
|
||||||
|
|
||||||
### Improper frequency
|
### Improper frequency
|
||||||
|
|
||||||
This can happen due to lack/bad clock source connection. Check that clock source is connected respective to the
|
This can happen due to lack/bad clock source connection. Check that clock source is connected respective to the customer needs,
|
||||||
customer needs, and if it is connected to the [Clocker](clocker.md), check that clocker receives clock signal properly.
|
and if it is connected to the [Clocker](clocker.md), check that clocker receives clock signal properly.
|
||||||
|
|
||||||
### Urukul proto_rev mismatch
|
### Urukul proto_rev mismatch
|
||||||
|
|
||||||
|
|
@ -147,9 +122,9 @@ Check the ports are connected respectively to the JSON description.
|
||||||
ValueError: PLL lock timeout
|
ValueError: PLL lock timeout
|
||||||
```
|
```
|
||||||
|
|
||||||
This can happen due to lack/bad clock source connection. Check that clock source is connected respective
|
This can happen due to lack/bad clock source connection. Check that clock source is connected respective to the customer needs,
|
||||||
to the customer needs, and if it is connected to the [Clocker](clocker.md), check that clocker receives clock signal
|
and if it is connected to the [Clocker](clocker.md), check that clocker receives clock signal properly and `EXT`/`INT` pin
|
||||||
properly and `EXT`/`INT` pin matches real clocker source.
|
matches real clocker source.
|
||||||
|
|
||||||
### Urukul AD9910 AUX_DAC mismatch
|
### Urukul AD9910 AUX_DAC mismatch
|
||||||
|
|
||||||
|
|
@ -158,24 +133,3 @@ ValueError: Urukul AD9910 AUX_DAC mismatch
|
||||||
```
|
```
|
||||||
|
|
||||||
Ensure it is the AD9910 and not the AD9912. Also check SUServo pins are set up respective to the JSON description.
|
Ensure it is the AD9910 and not the AD9912. Also check SUServo pins are set up respective to the JSON description.
|
||||||
|
|
||||||
### Jagged signal with 1GHz external clock on AD9910
|
|
||||||
|
|
||||||
By default, on AD9910 external clock signal is divided by 4, while it should be not divided at all with PLL disabled.
|
|
||||||
Change the `clk_div` parameter to the CPLD in the device_db file:
|
|
||||||
|
|
||||||
```python
|
|
||||||
device_db["urukulX_cpld"] = {
|
|
||||||
"type": "local",
|
|
||||||
"module": "artiq.coredevice.urukul",
|
|
||||||
"class": "CPLD",
|
|
||||||
"arguments": {
|
|
||||||
"spi_device": "spi_urukul0",
|
|
||||||
"sync_device": None,
|
|
||||||
"io_update_device": "ttl_urukul0_io_update",
|
|
||||||
"refclk": 1000000000.0,
|
|
||||||
"clk_sel": 1,
|
|
||||||
"clk_div" : 1 # <--- add this line
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
|
||||||
|
|
@ -12,22 +12,21 @@
|
||||||
"ports": [<port num>]
|
"ports": [<port num>]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"type": "fastino",
|
"type": "fastino",
|
||||||
"hw_rev": "v1.2", // optional
|
"hw_rev": "v1.2", // optional
|
||||||
"log2_width": <0 to 5, default 0>, // pack multiple (in powers of 2) DAC channels into one RTIO write
|
|
||||||
"ports": [<port num>]
|
"ports": [<port num>]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Fastino uses one physical EEM channel, despite having two EEM ports.
|
Fastino uses two physical EEM channels, but in the JSON file there should be only one channel specified,
|
||||||
|
and it should be the one connected to Fastino's EEM0.
|
||||||
|
|
||||||
## Setup
|
## Setup
|
||||||
|
|
||||||
Connect the BNC/SMA-IDC adapters to the Zotino/Fastino with 26-pin cable if needed by customer.
|
Connect the BNC/SMA-IDC adapters to the Zotino/Fastino with 26-pin cable if needed by customer. Be aware of the ports order -
|
||||||
Be aware of the ports order - see reference numbers on the board.
|
see reference numbers on the board.
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
|
|
@ -50,35 +49,10 @@ Press ENTER when done.
|
||||||
3. If there are [BNC/SMA-IDC adapters](./bnc_sma_idc_adapter.md), also check their voltages - they should be the same
|
3. If there are [BNC/SMA-IDC adapters](./bnc_sma_idc_adapter.md), also check their voltages - they should be the same
|
||||||
4. Check LEDs are on
|
4. Check LEDs are on
|
||||||
|
|
||||||
|
|
||||||
## Common problems
|
## Common problems
|
||||||
|
|
||||||
### High-freq audible noise and output values all near -0.1 on Zotino v1.4.2
|
### High-freq audible noise and output values all near -0.1 on Zotino v1.4.2
|
||||||
|
|
||||||
This may happen when power-cycle is too short. Power down the crate, wait at least 30 seconds, and power up again.
|
This may happen when power-cycle is too short. Power down the crate, wait at least 30 seconds, and power up again.
|
||||||
[Issue](https://github.com/sinara-hw/Zotino/issues/37).
|
[Issue](https://github.com/sinara-hw/Zotino/issues/37).
|
||||||
|
|
||||||
### Zero/meaningless voltage output on Fastino
|
|
||||||
|
|
||||||
Some Fastino may not output any meaningful voltage during testing, usually that means it has no gateware flashed.
|
|
||||||
|
|
||||||
Another common symptom of no gateware is that no LEDs are lit up. Whereas if the gateware has been flashed,
|
|
||||||
the PG and FD LEDs will be lit green.
|
|
||||||
|
|
||||||
You can flash the gateware with a Kasli/Kasli-SoC, be it in the crate or standalone
|
|
||||||
(no specific gateware needed for Kasli/SoC):
|
|
||||||
|
|
||||||
1. Download the latest `fastino.bin` release from [quartiq/fastino](https://github.com/quartiq/fastino/releases).
|
|
||||||
2. Run `git clone https://github.com/quartiq/kasli-i2c.git` and place `fastino.bin` in the kasli-i2c directory.
|
|
||||||
3. Connect the Fastino's EEM0 to any available Kasli/Kasli-SoC EEM port
|
|
||||||
([**do not hot-plug**](../build_test_firmware.md#operating-hints-and-warnings)).
|
|
||||||
You may skip this step if Fastino is connected within a crate.
|
|
||||||
4. Power on the standalone Kasli/Kasli-SoC and connect it to the PC via data micro-USB.
|
|
||||||
5. Run `nix-shell -p python311Packages.pyftdi`.
|
|
||||||
6. Run `cd kasli-i2c; python flash_fastino.py 0 EEM<number> write fastino.bin` where `<number>`
|
|
||||||
is the EEM port number on the Kasli/Kasli-SoC side.
|
|
||||||
7. If PG and FD LEDs are lit green, the Fastino is ready.
|
|
||||||
|
|
||||||
### Fastino output is 10V
|
|
||||||
|
|
||||||
Fastinos by default after power up output 10V on all channels if not driven by the test otherwise.
|
|
||||||
Make sure the EEM ports are specified correctly in the JSON and the EEM cable is connected to EEM0 on the Fastino.
|
|
||||||
|
|
|
||||||
Binary file not shown.
|
Before Width: | Height: | Size: 74 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 110 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 134 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 216 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 81 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 78 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 36 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 114 KiB |
|
|
@ -1,142 +0,0 @@
|
||||||
# AFWS client
|
|
||||||
|
|
||||||
This article is intended to help with using the `afws_client` command properly.
|
|
||||||
|
|
||||||
## Usage
|
|
||||||
|
|
||||||
### What is AFWS
|
|
||||||
|
|
||||||
AFWS (ARTIQ FirmWare Service) - a service, that allows building customer tailored firmware and gateware (binaries)
|
|
||||||
on M-Labs's servers, and receive these binaries in ready-to-flash format. Subscription to this service also includes
|
|
||||||
helpdesk support, and thus is paid on yearly basis (contact sales for prices). It is also typically included when
|
|
||||||
purchasing Carrier (Kasli/Kasli-SoC) for a year, or one-time when purchasing standalone cards for existing crate.
|
|
||||||
Each variant/carrier requires its own subscription.
|
|
||||||
|
|
||||||
### What do I need for obtaining binaries
|
|
||||||
|
|
||||||
You'll need to have credentials - username and password, which you can obtain from helpdesk, if you haven't yet.
|
|
||||||
Don't forget to specify variant (sticker on top of the crate) that you need to obtain binaries for.
|
|
||||||
|
|
||||||
### When do I need to update
|
|
||||||
|
|
||||||
In most cases there is no need to update the firmware, unless you encountered a bug and the fix was backported
|
|
||||||
to your version. However, if you: changed the layout of the cards - either moved EEM connections, added or
|
|
||||||
deleted cards; changed modes/configurations of the cards (e.g. enable/disable SUServo, synchronization, edge counter,
|
|
||||||
SED lanes etc.). In such cases, these changes need to be authorized through helpdesk.
|
|
||||||
|
|
||||||
### How to
|
|
||||||
|
|
||||||
The base command looks like this:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
afws_client <username> build <afws_directory> <variant>
|
|
||||||
```
|
|
||||||
|
|
||||||
Where (remove `<` and `>`):
|
|
||||||
|
|
||||||
* `<username>` - your username from credentials
|
|
||||||
* `<afws_directory>` - the directory/folder, into which you wish to save the binaries
|
|
||||||
* `<variant>` - name of the crate/variant. It's optional if you have only one variant in the account
|
|
||||||
|
|
||||||
After running this command, it will ask you for the password (the line will remain blank for security reasons).
|
|
||||||
If everything matches (username and password are correct, specified variant is in your account and not expired),
|
|
||||||
AFWS will start building the firmware, which takes 10-15 minutes. Sometimes there might be some problems, in which
|
|
||||||
case don't hesitate to contact helpdesk.
|
|
||||||
|
|
||||||
After the build done, the AFWS client will automatically download the binaries into `<afws_directory>`, from which
|
|
||||||
you can flash them into your Carrier.
|
|
||||||
|
|
||||||
#### View build logs
|
|
||||||
|
|
||||||
You may want to view the build logs (for example, in case of problems with configuration).
|
|
||||||
For this, add `--log` option after build:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
afws_client <username> build --log <afws_directory> <variant>
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Specify version
|
|
||||||
|
|
||||||
By default, AFWS client tries to figure out the installed ARTIQ version. However it works only for Kasli, and
|
|
||||||
not Kasli-SoC. It also may fail to determine ARTIQ version if you are using AFWS client without ARTIQ installation.
|
|
||||||
Additionally, you may want to specify version regardless of installed version.
|
|
||||||
In all these cases, you'll need to specify **both** `--major-ver` and `--rev` arguments, so your command
|
|
||||||
will look like this:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
afws_client <username> build --major-ver <MAJOR_VER> --rev <REV> <afws_directory> <variant>
|
|
||||||
```
|
|
||||||
|
|
||||||
Where:
|
|
||||||
|
|
||||||
* `MAJOR_VER` - ARTIQ major version, either `7` (legacy), `8` (current stable),
|
|
||||||
`9` (current beta) or `10` (experimental with `nac3` compiler)
|
|
||||||
* `REV` - revision from respective branch and repository - i.e. commit hash. You may obtain it either from:
|
|
||||||
* [ARTIQ repository](https://github.com/m-labs/artiq) (for Kasli 2.0 and earlier) by
|
|
||||||
[selecting branch](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-branches-in-your-repository/viewing-branches-in-your-repository)
|
|
||||||
and selecting `XXX commits` above list of files. From here, the list of commits in specified branch will appear
|
|
||||||
and you will be able to choose the commit and press ["Copy full SHA for YYY"](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/about-commits#using-the-file-tree)
|
|
||||||
button in the right side.
|
|
||||||
* [ARTIQ on Zynq repository](https://git.m-labs.hk/M-Labs/artiq-zynq) (for Kasli-SoC). In similar way to GitHub,
|
|
||||||
you can choose branch, commit history and copy SHA1 of the commit.
|
|
||||||
|
|
||||||
The branches currently map as following:
|
|
||||||
|
|
||||||
* ARTIQ-7 - release-7
|
|
||||||
* ARTIQ-8 - release-8
|
|
||||||
* ARTIQ-9 - master
|
|
||||||
* ARTIQ-10 - nac3
|
|
||||||
|
|
||||||
The binaries you receive are "pure" - if the inputs are the same (same version,
|
|
||||||
same JSON), the system outputs exactly the same binaries, and if you did it recently, they will be obtained from Nix
|
|
||||||
cache (i.e. not rebuilt).
|
|
||||||
|
|
||||||
#### Change password
|
|
||||||
|
|
||||||
After you received credentials from us, we strongly recommend changing the password as soon as possible via
|
|
||||||
`afws_client <username> passwd` command. This command will ask you for existing password and new desired password.
|
|
||||||
|
|
||||||
The passwords are stored in a hashed way (i.e. cannot be decrypted back), however it's your responsibility to
|
|
||||||
choose good passwords. Just keep in mind, that password may contain only alpha-numeric symbols and underscore
|
|
||||||
`[a-zA-Z0-9_]`. If you cannot login, we may reset your password if you email us at helpdesk.
|
|
||||||
|
|
||||||
#### Get variants
|
|
||||||
|
|
||||||
You may get variants, which are tied to your account by using `get_variants` command:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
afws_client <username> get_variants
|
|
||||||
```
|
|
||||||
|
|
||||||
It will ask for password and output the variants and their respective expiry date:
|
|
||||||
|
|
||||||
```text
|
|
||||||
+-----------+-------------+
|
|
||||||
| Variant | Expiry date |
|
|
||||||
+-----------+-------------+
|
|
||||||
| test | 2028-02-08 |
|
|
||||||
| test3 | 2042-08-08 |
|
|
||||||
+-----------+-------------+
|
|
||||||
```
|
|
||||||
|
|
||||||
#### Get JSONs
|
|
||||||
|
|
||||||
Sometimes you may want to view the JSON description, from which AFWS is building the variant. With the JSON, you can
|
|
||||||
later build the firmware by yourself and/or generate device_db file. The command looks like this (variant
|
|
||||||
needs to be valid, i.e. not expired and authorized in your account):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
afws_client <username> get_json [-o <OUT>] [-f] <variant>
|
|
||||||
```
|
|
||||||
|
|
||||||
Specify output file `-o <OUT>`, if you want to save it directly to file `<OUT>`, use `-f` if you want to force
|
|
||||||
overwrite. If you do not specify any of these options, you'll get the JSON description directly in stdin (i.e. in your
|
|
||||||
console/terminal).
|
|
||||||
|
|
||||||
#### Miscellaneous
|
|
||||||
|
|
||||||
You may also specify custom AFWS provider with these options (put them before username):
|
|
||||||
|
|
||||||
* `--server SERVER` - server to connect to (default: afws.m-labs.hk)
|
|
||||||
* `--port PORT` - port to connect to (default: 80)
|
|
||||||
* `--cert CERT` - SSL certificate file used to authenticate server (default: use system certificates)
|
|
||||||
|
|
@ -1,6 +1,4 @@
|
||||||
# Building legacy firmware
|
# Building ARTIQ-6 and earlier
|
||||||
|
|
||||||
## Building ARTIQ-6 and earlier
|
|
||||||
|
|
||||||
Pre-flake ARTIQ (that is 6 and earlier) requires slightly different steps for building.
|
Pre-flake ARTIQ (that is 6 and earlier) requires slightly different steps for building.
|
||||||
|
|
||||||
|
|
@ -8,20 +6,19 @@ Pre-flake ARTIQ (that is 6 and earlier) requires slightly different steps for bu
|
||||||
|
|
||||||
The following steps need to be done only once.
|
The following steps need to be done only once.
|
||||||
|
|
||||||
First we will need to specify older nixpkg version - 21.05. Open `~/.nix-channels` with your favorite text editor.
|
First we will need to specify older nixpkg version - 21.05. Open ``~/.nix-channels`` with your favorite text editor.
|
||||||
|
|
||||||
If there are any `nixpkgs` present already, comment them out with `#`.
|
If there are any ``nixpkgs`` present already, comment them out with ``#``.
|
||||||
|
|
||||||
Then add the following line:
|
Then add the following line:
|
||||||
|
|
||||||
```text
|
```
|
||||||
https://nixos.org/channels/nixos-21.05 nixpkgs
|
https://nixos.org/channels/nixos-21.05 nixpkgs
|
||||||
```
|
```
|
||||||
|
|
||||||
Save and exit.
|
Save and exit.
|
||||||
|
|
||||||
Now, we need special `nix-scripts` to configure building environment, and a local copy of the artiq repository,
|
Now, we need special ``nix-scripts`` to configure building environment, and a local copy of the artiq repository, in legacy release.
|
||||||
in legacy release.
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
mkdir artiq-legacy
|
mkdir artiq-legacy
|
||||||
|
|
@ -33,27 +30,6 @@ git checkout release-6 # or release-5...
|
||||||
cd ..
|
cd ..
|
||||||
```
|
```
|
||||||
|
|
||||||
Keep in mind that ARTIQ-6 scripts have been removed in `nix-scripts`, so you may need to checkout the last commit
|
|
||||||
that still has them.
|
|
||||||
|
|
||||||
```shell
|
|
||||||
cd nix-scripts
|
|
||||||
git checkout c590df48e0553a670e18ebf9d02047bfcfddb40d
|
|
||||||
cd ..
|
|
||||||
```
|
|
||||||
|
|
||||||
### If you need ARTIQ-6 on Kasli 2.0.2
|
|
||||||
|
|
||||||
Due to a different I2C IO expander chip, ARTIQ-6 firmware may boot on a Kasli 2.0.2, but will not allow Ethernet connection (and possibly DRTIO as well).
|
|
||||||
|
|
||||||
For that, before starting the development shell, patch the ARTIQ-6 with the [commit from ARTIQ-7 that added support for it](https://github.com/m-labs/artiq/commit/ce57d6c34680360da95465295044b1c4a51a4864):
|
|
||||||
|
|
||||||
```shell
|
|
||||||
cd artiq
|
|
||||||
git cherry-pick ce57d6c34680360da95465295044b1c4a51a4864
|
|
||||||
cd ..
|
|
||||||
```
|
|
||||||
|
|
||||||
## Setting up the environment and building firmware
|
## Setting up the environment and building firmware
|
||||||
|
|
||||||
Within ``fish`` shell (others may not work correctly), set up the ARTIQ build environment:
|
Within ``fish`` shell (others may not work correctly), set up the ARTIQ build environment:
|
||||||
|
|
@ -69,17 +45,13 @@ python -m artiq.gateware.targets.kasli_generic <variant>.json
|
||||||
```
|
```
|
||||||
|
|
||||||
If you are building legacy ARTIQ for local use and you want to flash it, use:
|
If you are building legacy ARTIQ for local use and you want to flash it, use:
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
artiq_flash -V <variant> -d artiq_kasli --srcbuild
|
artiq_flash -V <variant> -d artiq_kasli --srcbuild
|
||||||
```
|
```
|
||||||
|
|
||||||
There's a slight discrepancy from usual command - ``-V <variant>`` option is not present in ARTIQ-7+,
|
There's a slight discrepancy from usual command - ``-V <variant>`` option is not present in ARTIQ-7+, but it is necessary here.
|
||||||
but it is necessary here.
|
|
||||||
|
|
||||||
If you want to send the binaries to a customer, there's no need packing up the whole build directory - only `top.bit`,
|
If you want to send the binaries to a customer, there's no need packing up the whole build directory - only ``top.bit``, ``bootloader.bin`` and ``runtime.elf/fbi`` or ``satman.elf/fbi`` are necessary. You can use the ``prep_pkg.py`` script from extras to package them up neatly into a zip file for distributions:
|
||||||
`bootloader.bin` and `runtime.elf/fbi` or `satman.elf/fbi` are necessary. You can use the `prep_pkg.py` script from
|
|
||||||
extras to package them up neatly into a zip file for distributions:
|
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
python prep_pkg.py -v <variant> -d artiq_kasli/
|
python prep_pkg.py -v <variant> -d artiq_kasli/
|
||||||
|
|
@ -90,39 +62,3 @@ Then the customer can use ``artiq_flash`` easily, after extracting the contents:
|
||||||
```shell
|
```shell
|
||||||
artiq_flash -V <variant> -d .
|
artiq_flash -V <variant> -d .
|
||||||
```
|
```
|
||||||
|
|
||||||
## ARTIQ-7
|
|
||||||
|
|
||||||
The process of building firmware for ARTIQ-7 is mostly similar to ARTIQ-8, except there are no named RTIO channels
|
|
||||||
and no remote reboot functionality on Kasli-SoC. DRTIO set ups are also similar to ARTIQ-8.
|
|
||||||
[See reference](../build_test_firmware.md).
|
|
||||||
|
|
||||||
### Kasli, Kasli 2.0
|
|
||||||
|
|
||||||
```shell
|
|
||||||
mkdir <variant>
|
|
||||||
cd <variant>/
|
|
||||||
nix develop github:m-labs/artiq\?ref=release-7
|
|
||||||
# master/standalone only
|
|
||||||
artiq_mkfs -s ip 192.168.1.75 kasli.config
|
|
||||||
artiq_flash storage -f kasli.config
|
|
||||||
artiq_ddb_template -o device_db.py <variant>.json
|
|
||||||
python -m artiq.gateware.targets.kasli_generic <variant>.json
|
|
||||||
artiq_flash --srcbuild -d artiq_kasli/<variant>/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Kasli-SoC
|
|
||||||
|
|
||||||
```shell
|
|
||||||
mkdir <variant>
|
|
||||||
cd <variant>/
|
|
||||||
nix develop git+https://git.m-labs.hk/m-labs/artiq-zynq\?ref=release-7
|
|
||||||
artiq_ddb_template -o device_db.py <variant>.json
|
|
||||||
nix build -L --impure --expr 'let fl = builtins.getFlake "git+https://git.m-labs.hk/m-labs/artiq-zynq?ref=release-7"; in (fl.makeArtiqZynqPackage {target="kasli_soc"; variant="[master, standalone, satellite]"; json=<full path to the json description>;}).kasli_soc-[master, standalone, satellite]-sd'
|
|
||||||
# copy `results/boot.bin` to the SD card
|
|
||||||
# insert SD card to the Kasli-SoC and boot
|
|
||||||
artiq_coremgmt -D 192.168.1.56 config write -s ip 192.168.1.75 # or just place extra/CONFIG.TXT near the boot.bin on SD card
|
|
||||||
# update firmware (alternative to copy to SD, if ARTIQ already running)
|
|
||||||
artiq_coremgmt config write -f boot result/boot.bin
|
|
||||||
# reboot via power supply
|
|
||||||
```
|
|
||||||
|
|
|
||||||
|
|
@ -1,44 +0,0 @@
|
||||||
# Starting with ARTIQ
|
|
||||||
|
|
||||||
This page describes how to start with ARTIQ system for novice users.
|
|
||||||
|
|
||||||
## Connecting wires
|
|
||||||
|
|
||||||
In most cases the system is shipped with power bricks (PSU), DC splitters and SFPs enough to power and control the
|
|
||||||
whole system. Connect them in following order:
|
|
||||||
|
|
||||||
1. Insert Ethernet SFP into the SFP0 of the master or standalone Kasli/Kasli-SoC (Carrier)
|
|
||||||
2. Connect these SFPs to the router or PC via Ethernet cable (in some cases, optical cable)
|
|
||||||
3. Insert optic/direct attach SFPs into the master and satellite Carriers, respective to the numeration,
|
|
||||||
[more info in DRTIO page](drtio.md)
|
|
||||||
4. Power on PSU or EEM power module, by inserting C14 cable, attach DC splitters if available
|
|
||||||
5. Some cards may have "External power" setting (check the quotation), in this case, insert DC connector into the port
|
|
||||||
6. Insert remaining cables into the Carriers (not applicable in case of EEM Power Module).
|
|
||||||
|
|
||||||
## Set the network
|
|
||||||
|
|
||||||
By default standalone/master Carriers arrive with 192.168.1.75/24 set as their static address.
|
|
||||||
Carrier will try to acquire this address from your router, and in case of failure, they will be just unavailable
|
|
||||||
from the network. Check the following articles for troubleshooting network issues:
|
|
||||||
|
|
||||||
* [Networking](networking.md)
|
|
||||||
* [Official docs](https://m-labs.hk/artiq/manual/configuring.html)
|
|
||||||
|
|
||||||
## Run first experiment via artiq_run
|
|
||||||
|
|
||||||
Before diving in to the repository experiments management and scheduling, it is essential to try run your first
|
|
||||||
experiment via most basic way - `artiq_run`. For this you need to enter your ARTIQ environment (console) and run:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
artiq_run --device-db path/to/device_db.py path/to/experiment.py
|
|
||||||
```
|
|
||||||
|
|
||||||
In case your directory contains relevant `device_db` file, you may omit the `--device-db path/to/device_db.py` part.
|
|
||||||
To check this, you may run `ls .` and check if it is in the list.
|
|
||||||
|
|
||||||
On pre-installed NUCs, the ARTIQ commands are available everywhere, and you just need to run them.
|
|
||||||
If you have Nix package manager or NixOS, you will just need to enter the shell with
|
|
||||||
`nix develop github:m-labs/artiq\?ref=release-8`. If you have installed ARTIQ with Conda, you will need to activate
|
|
||||||
the environment with `conda activate <name of the environment with ARTIQ>`.
|
|
||||||
|
|
||||||
You may check for experiments in the [official docs](https://m-labs.hk/artiq/manual/getting_started_core.html).
|
|
||||||
|
|
@ -1,84 +0,0 @@
|
||||||
# Clocking
|
|
||||||
|
|
||||||
This page describes ways to set up clocking. Official documentation references:
|
|
||||||
|
|
||||||
* [Carrier configuration](https://m-labs.hk/artiq/manual/core_device.html#clocking)
|
|
||||||
* Devices' [available options](https://m-labs.hk/artiq/manual/core_drivers_reference.html), [Urukul example](https://m-labs.hk/artiq/manual/core_drivers_reference.html#artiq.coredevice.urukul.CPLD)
|
|
||||||
|
|
||||||
In general, any RF card and Carriers require some clock source. Most of them have both internal clock signal generator
|
|
||||||
and external MMCX and/or SMA connectors to accept the signal. By default the internal clock is used for Carriers,
|
|
||||||
and external MMCX is used for RF cards. However, internal clock may be not good enough for the end-user application,
|
|
||||||
so the end-user may want to change the clock source at any time.
|
|
||||||
|
|
||||||
## Kasli/Kasli-SoC
|
|
||||||
|
|
||||||
For setting clocking on the Carriers you will just need to set `rtio_clock` in the core device config. Be aware, that
|
|
||||||
setting any external clocking will require appropriate external clock signal to be supplied into `CLK IN` SMA connector
|
|
||||||
on the front panel to boot. Therefore, firmware will be halted, the `ERR` LED will be red and **no Ethernet connection
|
|
||||||
will be established**. Since the clock signal is distributed by DRTIO, there is generally no need in setting it up on
|
|
||||||
satellites.
|
|
||||||
|
|
||||||
If you have connection with the Carrier, you can use coremgmt command:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
artiq_coremgmt config write -s rtio_clock <OPTION>
|
|
||||||
```
|
|
||||||
|
|
||||||
For available options refer to the official documentation (at the top of the page).
|
|
||||||
|
|
||||||
### Setting clocking for Kasli without connection
|
|
||||||
|
|
||||||
For RISC-V/legacy Kasli you will just need to connect your PC to the Kasli via _data_ micro-USB cable and run the
|
|
||||||
following:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
# you may also change IP setting here, the default is 192.168.1.75
|
|
||||||
artiq_mkfs kasli.config -s ip xx.xx.xx.xx -s rtio_clock <OPTION>
|
|
||||||
# but don't forget to update `core_addr` variable in the device_db.py file if changed
|
|
||||||
artiq_flash storage -f kasli.config
|
|
||||||
```
|
|
||||||
|
|
||||||
Be aware that all other settings will be **erased**, so you may need to restore them in the `artiq_mkfs` command.
|
|
||||||
|
|
||||||
### Setting clocking for Kasli-SoC without connection
|
|
||||||
|
|
||||||
For this you will need to eject micro-SD card from the Kasli-SoC, either
|
|
||||||
by [removing the top panel](../img/rack_urukul_switch_access.jpg) or by gently pulling the Kasli-SoC from the crate,
|
|
||||||
possibly with other cards. In any case, be cautious and follow
|
|
||||||
the [warnings](../build_test_firmware.md#operating-hints-and-warnings). Once accessed the micro-SD card, simply
|
|
||||||
add `rtio_clock=<OPTION>` on a new line to the existing `CONFIG.TXT` file and save it, or if it is absent, just download
|
|
||||||
default-ish [CONFIG.TXT](../extra/CONFIG.TXT) to the SD card near (same level) `boot.bin` file.
|
|
||||||
|
|
||||||
## RF Devices (Except Clocker)
|
|
||||||
|
|
||||||
If you want to set the clock source specifically for RF devices, you will just need to update the JSON file
|
|
||||||
and [regenerate device_db.py file](device_db.md).
|
|
||||||
|
|
||||||
For example for Urukul, you will just need to check the manual for available variants and apply them in the JSON file,
|
|
||||||
so Urukul entry may look like this:
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"type": "urukul",
|
|
||||||
"dds": "ad9910",
|
|
||||||
"ports": [1, 2],
|
|
||||||
"refclk": 10e6,
|
|
||||||
"clk_sel": 1
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
So basically, `clk_sel` and `refclk` fields need to be set:
|
|
||||||
|
|
||||||
* `clk_sel` selects the source clock, where 0 - internal 100MHz XO; 1 - front-panel SMA; 2 internal MMCX
|
|
||||||
* `refclk` - reference clock frequency in Hz
|
|
||||||
|
|
||||||
These settings may need to be checked with official manual and may differ from device to device.
|
|
||||||
|
|
||||||
## Clocker card
|
|
||||||
|
|
||||||
Main page: [clocker.md](../hw/clocker.md)
|
|
||||||
|
|
||||||
Clocker card allows to distribute clock signal up to 1 GHz without additional software setup. Therefore, there is no way
|
|
||||||
to set it to generate signal, which would be different from input. The only setup allowed is to set to accept signal
|
|
||||||
from `EXT`/`INT` ports, front-panel SMA or card's MMCX ports respectively, by switching the `CLK SEL` switch on the
|
|
||||||
card .
|
|
||||||
|
|
@ -1,38 +0,0 @@
|
||||||
# device_db.py File
|
|
||||||
|
|
||||||
`device_db.py` file contains the database of the devices and their respective interfaces within the firmware/gateware.
|
|
||||||
It is generated from JSON description file and tied with the configuration and the gateware.
|
|
||||||
|
|
||||||
## Generating the device_db.py File
|
|
||||||
|
|
||||||
In some cases you may need to regenerate `device_db.py`, like switching clock source or changing the configuration.
|
|
||||||
Also it is must-do in most cases once firmware/gateware is being updated (for example, when you add, move or remove EEM
|
|
||||||
cards), and in case DRTIO layout changed.
|
|
||||||
Luckily, it is fairly easy to do. For standalone systems:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
artiq_ddb_template -o device_db.py <standalone variant>.json
|
|
||||||
```
|
|
||||||
|
|
||||||
For DRTIO systems:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
artiq_ddb_template -o device_db.py -s 1 <satellite1>.json -s 2 <satellite2>.json <...> -s N <satelliteN>.json <master>.json
|
|
||||||
```
|
|
||||||
|
|
||||||
Keep in mind, that for DRTIO systems the real SFP connections at master should match the numbers at
|
|
||||||
the `artiq_ddb_template` command, or routing table if specified.
|
|
||||||
|
|
||||||
Here is mapping for master Kasli 2.0 (without routing table):
|
|
||||||
|
|
||||||
* SFP0 - Ethernet
|
|
||||||
* SFP1 - Satellite 1
|
|
||||||
* SFP2 - Satellite 2
|
|
||||||
* SFP3 - Satellite 3
|
|
||||||
|
|
||||||
For master Kasli-SoC (without routing table):
|
|
||||||
|
|
||||||
* SFP0 - Satellite 1
|
|
||||||
* SFP1 - Satellite 2
|
|
||||||
* SFP2 - Satellite 3
|
|
||||||
* SFP3 - Satellite 4
|
|
||||||
|
|
@ -4,21 +4,19 @@ This page intends to help users solve problems with their DRTIO systems.
|
||||||
|
|
||||||
## Description (from user experience)
|
## Description (from user experience)
|
||||||
|
|
||||||
[Distributed Real Time Input/Output](https://m-labs.hk/artiq/manual/drtio.html) - allows almost seamlessly connecting
|
[Distributed Real Time Input/Output](https://m-labs.hk/artiq/manual/drtio.html) - allows almost seamlessly connecting several satellites to one master crate,
|
||||||
several satellites to one master crate, so that all the crates can be controlled as one whole crate.
|
so that all the crates can be controlled as one whole crate. The connection between the crates is done either by passive copper
|
||||||
The connection between the crates is done either by passive copper direct attach cables (suitable for one-crate setups)
|
direct attach cables (suitable for one-crate setups) or optical fibers SFP+ adapters (suitable for multiple crates that
|
||||||
or optical fibers SFP+ adapters (suitable for multiple crates that can be distributed up to
|
can be distributed up to [several kilometers](https://github.com/m-labs/artiq/issues/2022)). The DRTIO protocol is not
|
||||||
[several kilometers](https://github.com/m-labs/artiq/issues/2022)). The DRTIO protocol is not compatible with Ethernet,
|
compatible with Ethernet, and moreover, satellites do not have any network access and can be controlled only by master.
|
||||||
and moreover, satellites do not have any network access and can be controlled only by master. However,
|
However, both star (2 levels) and tree topologies are supported as well,
|
||||||
both star (2 levels) and tree topologies are supported as well, with default one being the star (one master and up to
|
with default one being the star (one master and up to 3-4 directly connected satellites), and if any chaining is needed, the
|
||||||
3-4 directly connected satellites), and if any chaining is needed, the
|
routing table setup is needed.
|
||||||
[routing table setup](https://m-labs.hk/artiq/manual/using_drtio_subkernels.html#configuring-the-routing-table)
|
To switch between satellite/master/standalone variants you just need to flash appropriate firmware, and set the respective `base`
|
||||||
is needed. To switch between satellite/master/standalone variants you just need to flash appropriate firmware,
|
field in the JSON description.
|
||||||
and set the respective `base` field in the JSON description.
|
|
||||||
|
|
||||||
The master will attempt to connect the satellite whenever it sees that there are SFPs plugged in. For this purpose,
|
The master will attempt to connect the satellite whenever it sees that there are SFPs plugged in. For this purpose,
|
||||||
it will _ping_ the satellite until it establishes the connection. This connection process can be observed from the logs:
|
it will _ping_ the satellite until it establishes the connection. This connection process can be observed from the logs:
|
||||||
|
|
||||||
```rust
|
```rust
|
||||||
// successful connection
|
// successful connection
|
||||||
[ 5385.011286s] INFO(runtime::rtio_mgt::drtio): [LINK#1] link RX became up, pinging
|
[ 5385.011286s] INFO(runtime::rtio_mgt::drtio): [LINK#1] link RX became up, pinging
|
||||||
|
|
@ -32,34 +30,18 @@ it will _ping_ the satellite until it establishes the connection. This connectio
|
||||||
[ 115.076772s] ERROR(runtime::rtio_mgt::drtio): [LINK#1] ping failed
|
[ 115.076772s] ERROR(runtime::rtio_mgt::drtio): [LINK#1] ping failed
|
||||||
```
|
```
|
||||||
|
|
||||||
During the connection, the clock signal is being distributed, effectively making the clocks across
|
During the connection, the clock signal is being distributed, effectively making the clocks across crates to be synchronized.
|
||||||
crates to be synchronized.
|
|
||||||
|
|
||||||
## Common problems
|
## Common problems
|
||||||
|
|
||||||
### Master and satellite do not connect with each other
|
### Master and satellite do not connect with each other
|
||||||
|
|
||||||
During execution of experiments, may result in following error:
|
* Shady cables and SFP adapters are often the cause, use the adapters from reputable sources, or better, use the one we ship.
|
||||||
|
You may also contact our helpdesk to get help in choosing the right adapters if needed.
|
||||||
```pycon
|
* The adapter is not pushed until the end. You shouldn't be able to pull out the adapters without pulling the petals/handles.
|
||||||
artiq.coredevice.exceptions.RTIODestinationUnreachable: RTIO destination unreachable, output, at XXXXX mu, channel 0xXXX:DEV0
|
* The fiber is not properly connected - you shouldn't be able to pull it out without squeezing the handle. Also the optics
|
||||||
```
|
may be dirty or damaged.
|
||||||
|
|
||||||
* Shady cables and SFP adapters are often the cause, use the adapters from reputable sources, or better,
|
|
||||||
use the one we ship. You may also contact our helpdesk to get help in choosing the right adapters if needed.
|
|
||||||
* The adapter is not pushed until the end. You shouldn't be able to pull out the adapters without
|
|
||||||
pulling the petals/handles.
|
|
||||||
* The fiber is not properly connected - you shouldn't be able to pull it out without squeezing the handle.
|
|
||||||
Also the optics may be dirty or damaged.
|
|
||||||
* Wrong setups - master to master, standalone to standalone. Messing up with SFP ports generally makes it unusable,
|
* Wrong setups - master to master, standalone to standalone. Messing up with SFP ports generally makes it unusable,
|
||||||
but the connection should be established in most cases.
|
but the connection should be established in most cases.
|
||||||
* The fiber adapters are not symmetrical - if one end has 1270/1330 label, another one should be 1330/1270.
|
* The fiber adapters are not symmetrical - if one end has 1270/1330 label, another one should be 1330/1270.
|
||||||
* Connection race condition - rebooting one or both master and satellite may help.
|
|
||||||
* Mismatch with real SFP port and the one, specified during device_db generation: re-attach the SFP ports according to
|
|
||||||
device_db or regenerate device_db according to SFP port attachment.
|
|
||||||
[More info at the device_db article.](device_db.md)
|
|
||||||
|
|
||||||
### Master-satellite interrupted/unstable connection
|
|
||||||
|
|
||||||
This often happens due to overheating issues. Check if the Kasli/SoC fans are working properly and
|
|
||||||
try installing rack fans to increase the air flow.
|
|
||||||
|
|
|
||||||
|
|
@ -6,18 +6,15 @@ Here are some extra steps needed for flashing the firmware.
|
||||||
|
|
||||||
### Windows
|
### Windows
|
||||||
|
|
||||||
From the [official manual](https://m-labs.hk/artiq/manual/flashing.html#installing-and-configuring-openocd):
|
From the [official manual](https://m-labs.hk/artiq/manual/installing.html#configuring-openocd):
|
||||||
|
|
||||||
On Windows, a third-party tool, Zadig, is necessary. Use it as follows:
|
On Windows, a third-party tool, Zadig, is necessary. Use it as follows:
|
||||||
|
|
||||||
1. Make sure the FPGA board’s JTAG USB port is connected to your computer.
|
1. Make sure the FPGA board’s JTAG USB port is connected to your computer.
|
||||||
2. Activate Options → List All Devices.
|
2. Activate Options → List All Devices.
|
||||||
3. Select the “Digilent Adept USB Device (Interface 0)” or “FTDI Quad-RS232 HS” (or similar)
|
3. Select the “Digilent Adept USB Device (Interface 0)” or “FTDI Quad-RS232 HS” (or similar) device from the drop-down list.
|
||||||
device from the drop-down list.
|
|
||||||
4. Select WinUSB from the spinner list.
|
4. Select WinUSB from the spinner list.
|
||||||
5. Click “Install Driver” or “Replace Driver”.
|
5. Click “Install Driver” or “Replace Driver”.
|
||||||
6. After above steps done, you may see the devices in the Device Manager:
|
6. After above steps done, you may see the devices in the Device Manager:
|
||||||
|
|
||||||
|
|
||||||
You may need to repeat these steps every time you plug the FPGA board into a port where it has not been
|
You may need to repeat these steps every time you plug the FPGA board into a port where it has not been plugged into previously on the same system.
|
||||||
plugged into previously on the same system.
|
|
||||||
|
|
@ -3,8 +3,9 @@
|
||||||
The official documentation lacks the description of MONitor/INJector, but it is a common mistake when running the ARTIQ-7.
|
The official documentation lacks the description of MONitor/INJector, but it is a common mistake when running the ARTIQ-7.
|
||||||
Basically it is a service that consists of two parts - one runs on the host PC, another on the Kasli.
|
Basically it is a service that consists of two parts - one runs on the host PC, another on the Kasli.
|
||||||
It allows to watch and control the state of the devices, so you can see it on the dashboard.
|
It allows to watch and control the state of the devices, so you can see it on the dashboard.
|
||||||
That's why the dashboard may emit errors about not working moninj. To fix this, you just need [to run it with Kasli's IP](https://m-labs.hk/artiq/manual/utilities.html#module-artiq.frontend.aqctl_moninj_proxy):
|
That's why the dashboard may emit errors about not working moninj. To fix this, you just need [to run it with Kasli's IP](https://m-labs.hk/artiq/manual/utilities.html#moninj-proxy):
|
||||||
|
|
||||||
```shell
|
```shell
|
||||||
aqctl_moninj_proxy CORE_ADDRESS
|
aqctl_moninj_proxy CORE_ADDRESS
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -6,49 +6,40 @@ a-la `I can't connect, please help`.
|
||||||
## Common problems
|
## Common problems
|
||||||
|
|
||||||
1. `device_db.py` has misleading `core_addr` address.
|
1. `device_db.py` has misleading `core_addr` address.
|
||||||
2. PC and the crate are in different subnets. They should be in the same network. Also you may want to directly
|
2. PC and the crate are in different subnets. They should be in the same network. Also you may want to directly attach the Kasli to the PC.
|
||||||
attach the Kasli to the PC.
|
|
||||||
3. Network restrictions/problems on your router, either by IP, MAC, protocols or anything else.
|
3. Network restrictions/problems on your router, either by IP, MAC, protocols or anything else.
|
||||||
4. Wrong configuration of the Kasli. Change IP or MAC address to correspond your network. For ARTIQ-8 and later, add
|
4. Wrong configuration of the Kasli. Change IP or MAC address to correspond your network. For ARTIQ-8, add
|
||||||
network mask to the `ip` setting on Kasli (not applicable for Kasli-SoC), like `192.168.1.75/24`.
|
network mask to the `ip` setting on Kasli, like `192.168.1.75/24`.
|
||||||
5. Incompatible Ethernet cables/SFP RJ45. Try different cables and SFP adapters.
|
5. Incompatible Ethernet cables/SFP RJ45. Try different cables and SFP adapters.
|
||||||
We usually test them with CAT6 cables, but lower categories should be supported too.
|
We usually test them with CAT6 cables, but lower categories should be supported too.
|
||||||
6. SFP or Ethernet are not pushed til the end.
|
6. SFP or Ethernet are not pushed til the end.
|
||||||
7. Some weird bugs in Vivado, leading to not working SFP on certain combinations of builds and Kaslis (very rare)
|
7. Some weird bugs in Vivado, leading to not working SFP on certain combinations of builds and Kaslis (very rare)
|
||||||
8. Running configured for external reference Kasli without external reference clock signal
|
8. Running configured for external reference Kasli without external reference clock signal
|
||||||
9. Using legacy firmware with newer hardware. ARTIQ-6 doesn't support Kasli v2.0.2 (at least without the patch mentioned in the [legacy](artiq_legacy.md) article)
|
9. Using legacy firmware with newer hardware. ARTIQ-6 doesn't support Kasli v2.0.2
|
||||||
10. Some other device in your network already reserved the configured IP address.
|
|
||||||
|
|
||||||
## Ways to diagnose
|
## Ways to diagnose
|
||||||
|
|
||||||
1. `ping` the device. If destination is unreachable, than it is either didn't connect to the network
|
1. `ping` the device. If destination is unreachable, than it is either didn't connect to the network
|
||||||
or connected to different address. If the packets just do not respond then it is not as clear,
|
or connected to different address. If the packets just do not respond then it is not as clear, we cannot know all the truth.
|
||||||
we cannot know all the truth.
|
|
||||||
2. See the SFP0 LED
|
2. See the SFP0 LED
|
||||||
3. See the ERR LED
|
3. See the ERR LED
|
||||||
4. [UART logs](uart_logs.md)
|
4. [UART logs](uart_logs.md)
|
||||||
5. `nmap` and `arp` to scan your network to help your Kasli get discovered. May be restricted in your network.
|
5. `nmap` and `arp` to scan your network to help your Kasli get discovered. May be restricted in your network.
|
||||||
6. Directly connect your Kasli to the PC via Ethernet and set up networking on the PC:
|
6. Directly connect your Kasli to the PC via Ethernet and set up networking on the PC: `ip addr change 192.168.1.0/24 dev eth0`
|
||||||
`ip addr change 192.168.1.0/24 dev eth0`
|
|
||||||
7. Become a router and capture all the packets when your Kasli tries to connect to the network.
|
7. Become a router and capture all the packets when your Kasli tries to connect to the network.
|
||||||
8. Turn off the Carrier/Kasli and `ping` the configured IP address. If it pings, then you'll need either set different
|
|
||||||
IP address on your Carrier or somehow deal with that other device - remove,
|
|
||||||
assign different address, move to other network etc.
|
|
||||||
|
|
||||||
## Direct connection
|
## Direct connection
|
||||||
|
|
||||||
Sometimes it is neccessary to connect your Kasli/Kasli-SoC (Carrier) directly to the PC/NUC. For example, your Kasli-SoC
|
Sometimes it is neccessary to connect your Kasli/Kasli-SoC (Carrier) directly to the PC/NUC. For example, your Kasli-SoC
|
||||||
may be configured for the wrong network. In order to do this, you will just need to:
|
may be configured for the wrong network. In order to do this, you will just need to:
|
||||||
|
|
||||||
1. Connect Carrier via Ethernet directly to the NUC/PC
|
1. Connect Carrier via Ethernet directly to the NUC/PC
|
||||||
2. Set the network settings (example for default 192.168.1.75 Carrier setting):
|
2. Set the network settings (example for default 192.168.1.75 Carrier setting):
|
||||||
|
```
|
||||||
```text
|
|
||||||
IPv4 method: Manual
|
IPv4 method: Manual
|
||||||
Address: 192.168.1.0
|
Address: 192.168.1.0
|
||||||
Netmask: 255.255.255.0
|
Netmask: 255.255.255.0
|
||||||
Gateway: 192.168.1.0
|
Gateway: 192.168.1.0
|
||||||
DNS, Routes - Auto
|
DNS, Routes - Auto
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
|
|
@ -1,17 +0,0 @@
|
||||||
# Integration with PyCharm®
|
|
||||||
|
|
||||||
It's fairly possible to integrate PyCharm with ARTIQ on Windows.
|
|
||||||
|
|
||||||
## MSYS2
|
|
||||||
|
|
||||||
Below is an example configuration, change it according your installation.
|
|
||||||
|
|
||||||
1. Set System Interpreter to MSYS2 CLANG64 one (pip packages are not supported):
|
|
||||||
|
|
||||||
2. Set Terminal to use MSYS2 CLANG64 one:
|
|
||||||
|
|
||||||
|
|
||||||
After this you will be able to look up definitions from ARTIQ and use convenient integrated Terminal to run `artiq_run`.
|
|
||||||
|
|
||||||
_PyCharm is a registered trademark of JetBrains s.r.o.. For license information, please refer to the
|
|
||||||
JetBrains website or the product documentation._
|
|
||||||
|
|
@ -1,78 +0,0 @@
|
||||||
# Setup your PC for building ARTIQ firmware
|
|
||||||
|
|
||||||
This page should guide you through building the firmware on your own PC.
|
|
||||||
Unfortunately, the building process is not possible on Windows natively (nor MSYS2),
|
|
||||||
but you can use [WSL](https://learn.microsoft.com/en-us/windows/wsl/install).
|
|
||||||
|
|
||||||
## Prerequisites
|
|
||||||
|
|
||||||
You should have a Linux with `nix` and `git` installed. For this purpose you may want to consider NixOS,
|
|
||||||
though it is hard way for everything else. You should have at least 70+ GB of free space (better 100+ GB) on
|
|
||||||
your `/opt` or `/` - most of this space will be taken by Vivado.
|
|
||||||
|
|
||||||
## Installation
|
|
||||||
|
|
||||||
1. Install Vivado 2022.2 from [Vivado archive](https://www.xilinx.com/support/download/index.html/content/xilinx/en/downloadNav/vivado-design-tools/archive.html)
|
|
||||||
into `/opt`.
|
|
||||||
2. Check that `ls -al /opt/Xilinx/Vivado/2022.2/settings64.sh` exists and has read and execute permissions for all:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
$ ls -al /opt/Xilinx/Vivado/2022.2/settings64.sh
|
|
||||||
-rwxr-xr-x 1 nobody nogroup 245 Dec 17 2022 /opt/Xilinx/Vivado/2022.2/settings64.sh
|
|
||||||
```
|
|
||||||
|
|
||||||
3. Add following into the `~/.local/share/nix/trusted-settings.json`, by `mkdir -p ~/.local/share/nix/ && nano ~/.local/share/nix/trusted-settings.json`
|
|
||||||
or with your favorite way (don't forget to save - Ctrl+O in `nano`):
|
|
||||||
|
|
||||||
```json
|
|
||||||
{
|
|
||||||
"extra-sandbox-paths":{
|
|
||||||
"/opt":true
|
|
||||||
},
|
|
||||||
"extra-substituters":{
|
|
||||||
"https://nixbld.m-labs.hk":true
|
|
||||||
},
|
|
||||||
"extra-trusted-public-keys":{
|
|
||||||
"nixbld.m-labs.hk-1:5aSRVA5b320xbNvu30tqxVPXpld73bhtOeH6uAjRyHc=":true
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
|
||||||
|
|
||||||
4. Enable flakes in Nix and add `/opt` to sandbox e.g. adding following to the `nix.conf`
|
|
||||||
(for example `~/.config/nix/nix.conf` or `/etc/nix/nix.conf`):
|
|
||||||
|
|
||||||
```text
|
|
||||||
experimental-features = nix-command flakes
|
|
||||||
extra-sandbox-paths = /opt
|
|
||||||
```
|
|
||||||
|
|
||||||
5. On Ubuntu, the Nix will conflict with Apparmor. You'll need to disable Apparmor for Nix,
|
|
||||||
or for the whole system (you can also delete Apparmor completely, but be careful with it).
|
|
||||||
|
|
||||||
From here, you should be able to enter ARTIQ development shell directly from URL, or by cloning the repository.
|
|
||||||
The later will allow you to edit the source code in case of need.
|
|
||||||
|
|
||||||
For example for Kasli 2.0:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git clone https://github.com/m-labs/artiq.git
|
|
||||||
cd artiq
|
|
||||||
nix develop #boards
|
|
||||||
```
|
|
||||||
|
|
||||||
For Kasli-SoC:
|
|
||||||
|
|
||||||
```shell
|
|
||||||
git clone https://git.m-labs.hk/M-Labs/artiq-zynq.git
|
|
||||||
cd artiq-zynq
|
|
||||||
nix develop
|
|
||||||
```
|
|
||||||
|
|
||||||
For building instructions for your JSON, please refer to the [build and test instructions](../build_test_firmware.md).
|
|
||||||
The reference uses commands like `nix develop github:m-labs/artiq\?ref=release-8#boards` and `nix develop git+https://git.m-labs.hk/m-labs/artiq-zynq\?ref=release-8`.
|
|
||||||
You may safely skip such commands if you entered the development shell (`nix develop`) from cloned git repository.
|
|
||||||
|
|
||||||
If you want to update the source files, you may use `git pull origin master --rebase`.
|
|
||||||
Please refer to the [git documentation](https://www.git-scm.com/docs) or other resources of your choice
|
|
||||||
if you are unfamiliar with `git`. You may also use GUI git tools, like the one integrated into JetBrains IDEs
|
|
||||||
(PyCharm, Intellij and others), VS Code, Sublime Merge or others.
|
|
||||||
|
|
@ -4,8 +4,8 @@ Used for network, booting, and most other issues debugging.
|
||||||
|
|
||||||
## How to get them
|
## How to get them
|
||||||
|
|
||||||
First, connect your Kasli/SoC to the PC with a data micro-USB cable. Once you turn on the device,
|
First, connect your Kasli/SoC to the PC with a data micro-USB cable. Once you turn on the device, wait at least 15 seconds
|
||||||
wait at least 15 seconds until its fully loaded.
|
until its fully loaded.
|
||||||
|
|
||||||
### Development shell
|
### Development shell
|
||||||
|
|
||||||
|
|
@ -15,8 +15,6 @@ wait at least 15 seconds until its fully loaded.
|
||||||
|
|
||||||
### Older Nix and other Linuxes
|
### Older Nix and other Linuxes
|
||||||
|
|
||||||
Ensure your user is in `dialout` group.
|
|
||||||
|
|
||||||
1. Install `cutecom` via `nix-shell -p cutecom` or your package manager
|
1. Install `cutecom` via `nix-shell -p cutecom` or your package manager
|
||||||
2. Run `cutecom` and follow settings from the picture: 
|
2. Run `cutecom` and follow settings from the picture: 
|
||||||
3. Restart the device with `artiq_flash start`, or by power-cycling it (wait 30 seconds before turning on)
|
3. Restart the device with `artiq_flash start`, or by power-cycling it (wait 30 seconds before turning on)
|
||||||
|
|
@ -44,9 +42,9 @@ You may also need to reboot your PC after doing this.
|
||||||
6. 
|
6. 
|
||||||
7. 
|
7. 
|
||||||
|
|
||||||
If you are here after [flashing firmware](flashing_firmware.md) stage, you may fail to see the devices in the described
|
If you are here after [flashing firmware](flashing_firmware.md) stage, you may fail to see the devices in the described locations.
|
||||||
locations. If you see them in the `Universal Serial Bus devices` section, you may need just to uninstall
|
If you see them in the `Universal Serial Bus devices` section, you may need just to uninstall the third _Quad_ device and reconnect the
|
||||||
the third _Quad_ device and reconnect the Kasli/Kasli-SoC to the PC.
|
Kasli/Kasli-SoC to the PC.
|
||||||
|
|
||||||
#### Connecting with PuTTY
|
#### Connecting with PuTTY
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue